[patch] example makefile

[Don McCoy <don@xxxxxxxxxxxxxxxx>]

The attached patch adds a makefile that is to be used to compile the 
examples after installing the library.  The quickstart guide has been 
updated to reflect this change.
Regards,

--
Don McCoy
CodeSourcery

Index: doc/quickstart/quickstart.xml
===================================================================
RCS file: /home/cvs/Repository/vpp/doc/quickstart/quickstart.xml,v
retrieving revision 1.20
diff -c -p -r1.20 quickstart.xml
*** doc/quickstart/quickstart.xml	18 Jan 2006 18:30:42 -0000	1.20
--- doc/quickstart/quickstart.xml	19 Jan 2006 22:08:35 -0000
***************
*** 372,378 ****
        <para>
         Automatically Tuned Linear Algebra Software can be used to
         accelerate some linear-algebra functions in Sourcery VSIPL++.
!        Visit <uri>http://math-atlas.sourceforge.net</uri> for more
        information about ATLAS.
        </para>
       </section>
--- 372,378 ----
        <para>
         Automatically Tuned Linear Algebra Software can be used to
         accelerate some linear-algebra functions in Sourcery VSIPL++.
!        Visit <ulink url="http://math-atlas.sourceforge.net";></ulink> for more
        information about ATLAS.
        </para>
       </section>
***************
*** 382,388 ****
        <para>
         The Fastest Fourier Transform in the West can be used to
         accelerate Sourcery VSIPL++ FFT performance.  Visit 
!        <uri>http://www.fftw.org</uri> for more information about
         FFTW. 
        </para>
       </section>
--- 382,388 ----
        <para>
         The Fastest Fourier Transform in the West can be used to
         accelerate Sourcery VSIPL++ FFT performance.  Visit 
!        <ulink url="http://www.fftw.org";></ulink> for more information about
         FFTW. 
        </para>
       </section>
***************
*** 400,407 ****
        <para>
         Here are URLs where you can find out more about IPP and MKL:
         <itemizedlist>
!         <listitem><uri>http://www.intel.com/cd/software/products/asmo-na/eng/perflib/ipp/index.htm</uri></listitem>
!         <listitem><uri>http://www.intel.com/cd/software/products/asmo-na/eng/perflib/mkl/index.htm</uri></listitem>
         </itemizedlist>
        </para>
       </section>
--- 400,407 ----
        <para>
         Here are URLs where you can find out more about IPP and MKL:
         <itemizedlist>
!         <listitem><ulink url="http://www.intel.com/cd/software/products/asmo-na/eng/perflib/ipp/index.htm";></ulink></listitem>
!         <listitem><ulink url="http://www.intel.com/cd/software/products/asmo-na/eng/perflib/mkl/index.htm";></ulink></listitem>
         </itemizedlist>
        </para>
       </section>
*************** config.status: creating src/vsip/impl/ac
*** 920,948 ****
         Sourcery VSIPL++ binary packages are distributed as compressed 
         Tape Archive (TAR) files that are intended to be installed in the 
         root directory.  The following commands will use GNU TAR to unpack 
!        the binary distribution into the location /usr/local:
  <screen>> cd /
! > tar xjf sourceryvsipl++-&version;-ser-builtin-x86_64-unknown-linux-gnu.tar.bz2
  </screen>
       </para>
       <para>
         The directory layout of the installed package is as follows:
  <screen>`-- usr
      `-- local
!         |-- include// Header files
          |   |-- atlas
          |   `-- vsip
          |       `-- impl
!         |-- lib// Sourcery VSIPL++ library and third-party libraries
          |   |-- atlas
          |   `-- pkgconfig
!         `-- share// Documentation and user files
              |-- doc
              |   `-- sourceryvsipl++
              |       |-- quickstart
              |       `-- tutorial
-             |           `-- images
-             |               `-- callouts
              `-- sourceryvsipl++
  </screen>
  
--- 920,947 ----
         Sourcery VSIPL++ binary packages are distributed as compressed 
         Tape Archive (TAR) files that are intended to be installed in the 
         root directory.  The following commands will use GNU TAR to unpack 
!        the binary distribution into the location <filename>/usr/local</filename>:
  <screen>> cd /
! > tar xjf sourceryvsipl++-&version;-serial-builtin-x86_64-sse2.tar.bz2
  </screen>
       </para>
       <para>
         The directory layout of the installed package is as follows:
  <screen>`-- usr
      `-- local
!         |-- include  // Header files
          |   |-- atlas
          |   `-- vsip
          |       `-- impl
!         |-- lib      // Sourcery VSIPL++ library and third-party libraries
          |   |-- atlas
          |   `-- pkgconfig
!         `-- share    // Documentation and user files
              |-- doc
              |   `-- sourceryvsipl++
              |       |-- quickstart
+             |       |-- reference
              |       `-- tutorial
              `-- sourceryvsipl++
  </screen>
  
*************** config.status: creating src/vsip/impl/ac
*** 956,967 ****
         compilation options needed in order to build Sourcery VSIPL++ programs.
  
         An example Makefile:
! <screen>pkgcommand=pkg-config vsipl++ --variable=prefix=/path/to/install/usr/local
! CXX      = $(shell pkgcommand --variable=cxx)
! CXXFLAGS = $(shell pkgcommand --cflags)
! LIBS     = $(shell pkgcommand --libs)
  
! example: example.o
      $(CXX) $(CXXFLAGS) -o $@ $^ $(LIBS)
  </screen>
      </para>
--- 955,970 ----
         compilation options needed in order to build Sourcery VSIPL++ programs.
  
         An example Makefile:
! <screen>prefix = /path/to/install/usr/local
! pkgcommand := PKG_CONFIG_PATH=$(prefix)/lib/pkgconfig \
!                      pkg-config vsipl++$(suffix) \
!                      --define-variable=prefix=$(prefix)
! 
! CXX      = $(shell ${pkgcommand} --variable=cxx)
! CXXFLAGS = $(shell ${pkgcommand} --cflags)
! LIBS     = $(shell ${pkgcommand} --libs)
  
! example1: example1.o
      $(CXX) $(CXXFLAGS) -o $@ $^ $(LIBS)
  </screen>
      </para>
*************** example: example.o
*** 977,983 ****
     <abstract>
      <para>
       Sourcery VSIPL++ comes with example programs, installed in the
!      <filename>share/vsip</filename> subdirectory.  This chapter
       explains how to compile, link, and run these programs.  You can
       modify these programs to develop your own Sourcery VSIPL++
       applications.
--- 980,986 ----
     <abstract>
      <para>
       Sourcery VSIPL++ comes with example programs, installed in the
!      <filename>share/sourceryvsipl++</filename> subdirectory.  This chapter
       explains how to compile, link, and run these programs.  You can
       modify these programs to develop your own Sourcery VSIPL++
       applications.
*************** example: example.o
*** 995,1080 ****
     examples in this chapter assume that you are using the GNU C++
     compiler.  If you are using another C++ compiler, you may have to
     make minor changes to the commands shown.
-  </para>
- 
-   <para>
-    The file <filename>/opt/vsip/share/vsip/example1.cpp</filename>
-    contains a very simple VSIPL++ program.  You can use this file as a
-    template for developing much more complex programs.
    </para>
  
!   <para>
!    When building Sourcery VSIPL++ applications, you must ensure that your
!    compiler can find the necessary header and library files.  Since
!    Sourcery VSIPL++ may depend on other libraries, the easiest way to
!    determine the necessary compiler directives is with the pkg-config
!    command.  However, if you installed Sourcery VSIPL++ in a directory not
!    in pkg-config's search path, it will be necessary to first set the
!    <envar>PKG_CONFIG_PATH</envar> environment variable:
!    <screen>> export PKG_CONFIG_PATH=/opt/vsip/lib/pkgconfig</screen>
!   </para>  
  
!   <para>
!    First, to compile the program, use the following command:
!    <screen>> g++ -c `pkg-config --cflags vsipl++` \
!     /opt/vsip/share/vsip/example1.cpp</screen>
!   </para>  
  
!   <para>
!    Next, to link the program, use the following command:
!    <screen>> g++ -o example1 example1.o `pkg-config --libs vsipl++`</screen>
!   </para>  
  
!   <para>
!    Now that you have built the example program, you can run it like any
!    other program, with:
!    <screen>> ./example1</screen>
!   </para>  
  
!   <para>
!    When building applications, it is important to use the same C++
!    compiler that was used to build the Sourcery VSIPL++ library.  Different
!    C++ compilers, even different versions of the same compiler, may
!    have incompatible linking conventions or different standard library
!    implementations.  However, it is possible to determine the compiler
!    used to build Sourcery VSIPL++ via pkg-config:
!    <screen>> pkg-config --variable=cxx vsipl++</screen>
!    Using this, the previous commands to compile and link the example
!    program become:
!    <screen>> `pkg-config --variable=cxx vsipl++` \
!         -c `pkg-config --cflags vsipl++` /opt/vsip/share/vsip/example1.cpp
  > `pkg-config --variable=cxx vsipl++` \
!         -o example1 example1.o `pkg-config --libs vsipl++`</screen>
!   </para>
  
!   <para>
!    If pkg-config is not available on your system, you can specify the
!    search paths manually.  With most compilers, the
!    <option>-I</option> switch can be used to specify directories
!    containing header files.  Use the following command to compile the
!    program:
!    <screen>> g++ -c -I /opt/vsip/include /opt/vsip/share/vsip/example1.cpp</screen>
!   </para>
  
!   <para>
!    To link the program manually, you must tell the compiler where to
!    find the libraries when linking.  For most compilers, the
!    <option>-L</option> switch is used to specify directories to search
!    for libraries, while the <option>-l</option> switch is used to
!    specify the names of libraries to use.  Use the following command
!    to link the program:
!    <screen>> g++ -o example1 -L /opt/vsip/lib example1.o -l vsip</screen>
!   </para>
  
!   <para>
!    If Sourcery VSIPL++ was configured to use other libraries, such as MPI,
!    it will be necessary to manually specify <option>-L</option> and
!    <option>-l</option> options accordingly.  These necessary options
!    can be determined by looking in the
!    <filename>/opt/vsip/lib/pkgconfig/vsipl++.pc</filename> file.  It
!    contains a line prefixed with "Libs:" which indicates the libraries
!    necessary to link a Sourcery VSIPL++ program.
!   </para>
   </chapter>
  
   &gpl.xml;
--- 998,1110 ----
     examples in this chapter assume that you are using the GNU C++
     compiler.  If you are using another C++ compiler, you may have to
     make minor changes to the commands shown.
    </para>
  
!   <section>
!    <title>Building Manually</title>
!     <para>
!      The file <filename>/opt/vsip/share/sourceryvsipl++/example1.cpp</filename>
!      contains a very simple VSIPL++ program.  You can use this file as a
!      template for developing much more complex programs.
!     </para>
  
!     <para>
!      When building Sourcery VSIPL++ applications, you must ensure that your
!      compiler can find the necessary header and library files.  Since
!      Sourcery VSIPL++ may depend on other libraries, the easiest way to
!      determine the necessary compiler directives is with the pkg-config
!      command.  However, if you installed Sourcery VSIPL++ in a directory not
!      in pkg-config's search path, it will be necessary to first set the
!      <envar>PKG_CONFIG_PATH</envar> environment variable:
!      <screen>> export PKG_CONFIG_PATH=/opt/vsip/lib/pkgconfig</screen>
!     </para>  
  
!    <para>
!      First, to compile the program, use the following command:
!      <screen>> g++ -c `pkg-config --cflags vsipl++` \
!       /opt/vsip/share/sourceryvsipl++/example1.cpp</screen>
!     </para>  
  
!     <para>
!      Next, to link the program, use the following command:
!      <screen>> g++ -o example1 example1.o `pkg-config --libs vsipl++`</screen>
!     </para>  
  
!     <para>
!      Now that you have built the example program, you can run it like any
!      other program, with:
!      <screen>> ./example1</screen>
!     </para>  
! 
!    <section>
!     <title>Using <command>pkg-config</command></title>
!     <para>
!      When building applications, it is important to use the same C++
!      compiler that was used to build the Sourcery VSIPL++ library.  Different
!      C++ compilers, even different versions of the same compiler, may
!      have incompatible linking conventions or different standard library
!      implementations.  However, it is possible to determine the compiler
!      used to build Sourcery VSIPL++ via pkg-config:
!      <screen>> pkg-config --variable=cxx vsipl++</screen>
!      Using this, the previous commands to compile and link the example
!      program become:
!      <screen>> `pkg-config --variable=cxx vsipl++` \
!           -c `pkg-config --cflags vsipl++` /opt/vsip/share/sourceryvsipl++/example1.cpp
  > `pkg-config --variable=cxx vsipl++` \
!           -o example1 example1.o `pkg-config --libs vsipl++`</screen>
!     </para>
!   
!     <para>
!      If pkg-config is not available on your system, you can specify the
!      search paths manually.  With most compilers, the
!      <option>-I</option> switch can be used to specify directories
!      containing header files.  Use the following command to compile the
!      program:
!      <screen>> g++ -c -I /opt/vsip/include /opt/vsip/share/sourceryvsipl++/example1.cpp</screen>
!     </para>
  
!     <para>
!      To link the program manually, you must tell the compiler where to
!      find the libraries when linking.  For most compilers, the
!      <option>-L</option> switch is used to specify directories to search
!      for libraries, while the <option>-l</option> switch is used to
!      specify the names of libraries to use.  Use the following command
!      to link the program:
!      <screen>> g++ -o example1 -L /opt/vsip/lib example1.o -l vsip</screen>
!     </para>
  
!     <para>
!      If Sourcery VSIPL++ was configured to use other libraries, such as MPI,
!      it will be necessary to manually specify <option>-L</option> and
!      <option>-l</option> options accordingly.  These necessary options
!      can be determined by looking in the
!      <filename>/opt/vsip/lib/pkgconfig/vsipl++.pc</filename> file.  It
!      contains a line prefixed with "Libs:" which indicates the libraries
!      necessary to link a Sourcery VSIPL++ program.
!     </para>
!    </section>
!   </section>
  
!   <section>
!     <title>Building with GNU Make</title>
!     <para>  
!      An makefile for compiling the example programs is provided in the same
!      directory as the example source files (<filename>/opt/vsip/share/sourceryvsipl++</filename>).
!      This example uses the pkg-config command to extract the information 
!      needed to correctly compile an application with the Sourcery VSIPL++
!      library.  Create the executable by entering the <command>make</command>
!      command from the examples directory (or directory where you have
!      copied the makefile and source files).  For example:
!      <screen>> cd /opt/vsip/share/sourceryvsipl++/
! > make
! g++ -I/opt/vsip/include   -o example1 example1.o -L/opt/vsip/lib -lvsip
! </screen>
!      Note that your command line will appear differently depending on
!      install location and configuration options.  As described above,
!      the correctly compiler, include paths and library information are
!      obtained automatically.  
!     </para>  
!   </section>
   </chapter>
  
   &gpl.xml;
Index: examples/GNUmakefile.inc.in
===================================================================
RCS file: /home/cvs/Repository/vpp/examples/GNUmakefile.inc.in,v
retrieving revision 1.7
diff -c -p -r1.7 GNUmakefile.inc.in
*** examples/GNUmakefile.inc.in	4 Jan 2006 19:10:03 -0000	1.7
--- examples/GNUmakefile.inc.in	19 Jan 2006 22:08:35 -0000
*************** examples/example1$(EXEEXT): examples/exa
*** 32,34 ****
--- 32,36 ----
  install::
  	$(INSTALL) -d $(DESTDIR)$(pkgdatadir)
  	$(INSTALL_DATA) $(examples_cxx_sources) $(DESTDIR)$(pkgdatadir)
+ 	$(INSTALL_DATA) examples/makefile.standalone \
+ 	  $(DESTDIR)$(pkgdatadir)/Makefile
Index: examples/makefile.standalone.in
===================================================================
RCS file: examples/makefile.standalone.in
diff -N examples/makefile.standalone.in
*** /dev/null	1 Jan 1970 00:00:00 -0000
--- examples/makefile.standalone.in	19 Jan 2006 22:08:35 -0000
***************
*** 0 ****
--- 1,40 ----
+ ########################################################################
+ #
+ # File:   share/sourceryvsipl++/Makefile
+ # Author: Don McCoy
+ # Date:   2006-01-18
+ #
+ # Contents: Makefile for examples to be used after VSIPL++ has been 
+ #            installed.
+ #
+ ########################################################################
+ 
+ ########################################################################
+ # Variables
+ ########################################################################
+ 
+ # This should point to the directory where Sourcery VSIPL++ is installed.
+ prefix = @prefix@
+ 
+ # This selects the desired library.  Use '-debug' for building a version 
+ # suitable for debugging or leave blank to use the optimized version.
+ suffix = 
+ 
+ pkgcommand := PKG_CONFIG_PATH=$(prefix)/lib/pkgconfig 	\
+                      pkg-config vsipl++$(suffix) 	\
+                      --define-variable=prefix=$(prefix)
+ 
+ CXX      = $(shell ${pkgcommand} --variable=cxx)
+ CXXFLAGS = $(shell ${pkgcommand} --cflags)
+ LIBS     = $(shell ${pkgcommand} --libs)
+  
+ 
+ ########################################################################
+ # Rules
+ ########################################################################
+ 
+ all: example1
+ 
+ example1: example1.o
+ 	$(CXX) $(CXXFLAGS) -o $@ $^ $(LIBS)
+ 

2006-01-19  Don McCoy  <don@xxxxxxxxxxxxxxxx>

	* doc/quickstart/quickstart.xml: Changed tags on urls for the sake
	  of consistency.  Corrected section on installing binary packages.
	  Added headings to sections on building applications in addition
	  to referencing the new makefile for building examples.
	* examples/GNUmakefile.inc.in: Copies new makefile during install.
	* examples/makefile.standalone.in: New file.  This gets installed
	  as share/sourceryvsipl++/Makefile - allowing the user an easy
	  way to build the example program.