diff options
Diffstat (limited to 'doc/html/TechNotes/Automake.html')
| -rw-r--r-- | doc/html/TechNotes/Automake.html | 223 |
1 files changed, 0 insertions, 223 deletions
diff --git a/doc/html/TechNotes/Automake.html b/doc/html/TechNotes/Automake.html deleted file mode 100644 index c6dfc41..0000000 --- a/doc/html/TechNotes/Automake.html +++ /dev/null @@ -1,223 +0,0 @@ -<html> - -<head> -<meta http-equiv=Content-Type content="text/html; charset=utf-8"> -<title>An Automake Primer for HDF5</title> -</head> - -<h2>An Automake Primer for HDF5</h2> -<h4>James Laird - May 2005</h4><br> - -<p><h2><u>How to:</u><h2></p> - -<p><h3>Change a Makefile</h3></p> - -<p><h3>Add a source file to an existing program or library</h3></p> - -<p><h3>Add a simple test</h3></p> - -<p><h3>Add a test with multiple sources</h3></p> - -<p><h3>Add a new directory</h3></p> - -<p><h3>Add a program that is only compiled in parallel</h3></p> - -<p><h3>Change a program's name when it is compiled in parallel</h3></p> - -<p><h3>Add a new library</h3></p> - -<p><h3>Change the library's API</h3></p> -<br> - -<p><h4>Changing a Makefile</h4></p> - -<p>Suppose you need to make a minor change to the Makefile in the test directory -(<code>hdf5/test/Makefile</code>). You have checked out hdf5 from the CVS repository into -<code>~/scratch/hdf5</code>. You want to build the library in a directory named -<code>~/scratch/build</code>.<br> -First, edit the Makefile.am in the source tree. You must make any changes in the Makefile.am, -not the Makefile, since the Makefile is automatically generated.</p> - -<p><code>cd ~/scratch/hdf5/test<br> -vi Makefile.am</code></p> - -<p>Now, go to the root of the source tree and run the reconfigure script, which updates the -source tree. It will create a new Makefile.in in the test directory with your changes.</p> - -<p><code>cd ~/scratch/hdf5<br> -./bin/reconfigure</code></p> - -<p>After running <code>bin/reconfigure</code>, you will want to test your change. Go to -<code>~/scratch/build</code> and run <code>configure</code>.</p> - -<p><code>cd ~/scratch/build<br> - -../hdf5/configure<br> - -make check</code></p> - -<p>Configure generates Makefiles from the Makefiles.in in the source tree. The dependencies are:</p> - -<p><code>Makefile.am -> (bin/reconfigure) -> Makefile.in -> (configure) -> Makefile</code></p> - -<p>Reconfigure should also be used when any change is made to configure.in.</p> -<br> - -<p><h4>Adding a source file to an existing program or library</h4></p> - -<p>Suppose you want to add the source file <code>h5testfoo.c</code> to the HDF5 test -library in the test directory. You open up <code>test/Makefile.am</code> in your -favorite text editor and scroll down until you see the line:</p> - -<p><code>libh5test_la_SOURCES=h5test.c testframe.c</code></p> - -<p>Just add <code>h5testfoo.c</code> to the list of sources. You're done!<br> -Now run <code>bin/reconfigure</code> to create a new Makefile.in from the Makefile.am you just -edited.</p> -<br> - -<p><h4>Adding a simple test</h4></p> - -<p>Suppose you want to create a new test executable named <code>newtest</code> with one -source file, <code>newtest.c</code>. You open up <code>test/Makefile.am</code> and find -the line</p> - -<p><code>TEST_PROG=testhdf5 lheap ohdr ...</code></p> - -<p>Just add <code>newtest</code> to the list of programs. That's it! Automake will by -default guess that your program <code>newtest</code> has one source file named -<code>newtest.c</code>.<br> -Now run <code>bin/reconfigure</code> to update the Makefile.in.</p> -<br> - -<p><h4>Adding a slightly more complicated test</h4></p> - -<p>Suppose you want to create a new test executable named <code>newertest</code> with -several source files. You open up <code>test/Makefile.am</code> as before and find the line</p> - -<p><code>TEST_PROG=testhdf5 lheap ohdr ...</code></p> - -<p>Add <code>newertest</code> to the list of programs.<br> -Now you need to tell Automake how to build newertest. Add a new line below -<code>TEST_PROG</code>:</p> - -<p><code>newtest_SOURCES = source1.c source2.c source3.c</code></p> - -<p>You don't need to mention header files, as these will be automatically detected.<br> -Now run <code>bin/reconfigure</code> to update the Makefile.in.</p> -<br> - -<p><h4>Adding a directory</h4></p> - -<p>To add the directory for a new tool, <code>h5merge</code>, go to the Makefile.am -in the tools directory (the parent directory of the directory you want to add). -Find the line that reads</p> - -<p><code>SUBDIRS=lib h5dump...</code></p> - -<p>Add <code>h5merge</code> to this list of subdirectories.<br> -Now you probably want to create a Makefile.am in the h5merge directory. A good starting -point for this Makefile.am might be the sample Makefile.am in the config directory -(<code>config/Makefile.am.blank</code>). Alternately, you could copy the Makefile.am -from another directory.<br> -Once you have your new Makefile.am in place, edit <code>configure.in</code> in the root -directory. Near the end of the file is a list of files generated by configure. -Add <code>tools/h5merge/Makefile.in</code> to this list.<br> -Now run <code>bin/reconfigure</code>. This will update configure and generate a Makefile.in in the -<code>tools/h5merge</code> directory. Don't forget to add both the Makefile.am and the Makefile.in to -CVS, and to update the manifest!.</p> -<br> - -<p><h4>Adding a program that is only compiled in parallel</h4></p> - -<p>Suppose you only want to compile a program when HDF5 is configured to run in -parallel--for example, a parallel version of h5repack called <code>h5prepack</code>. -Open up the h5repack Makefile.am<br> -The simple solution is:</p> - -<p><code>if BUILD_PARALLEL_CONDITIONAL<br> - H5PREPACK=h5prepack<br> -endif</code></p> - -<p>Now the variable <code>$H5PREPACK</code> will be "h5prepack" if parallel is -enabled and "" if parallel is disabled. Add <code>$H5PREPACK</code> to the list of -programs to be built:</p> - -<p><code>bin_PROGRAMS=h5repack $(H5PREPACK)</code></p> - -<p>Add sources for this program as usual:</p> - -<p><code>h5prepack_SOURCES=...</code></p> - -<p>Don't forget to run <code>bin/reconfigure</code> when you're done!</p> -<br> - -<p><h4>Changing a program's name when it is compiled in parallel</h4></p> - -<p>Automake conditionals can be a very powerful tool. Suppose that instead of building -two versions of h5repack during a parallel build, you want to change the name of -the tool depending on whether or not HDF5 is configured to run in parallel--you -want to create either h5repack or h5prepack, but not both.<br> -Open up the h5repack Makefile.am and use an automake conditional:</p> - -<p><code>if BUILD_PARALLEL_CONDITIONAL<br> - H5REPACK_NAME=h5prepack<br> -else<br> - H5REPACK_NAME=h5repack<br> -endif<br> -bin_PROGRAMS=$(H5REPACK_NAME)</p> - -<p>Now you only build one program, but the name of that program changes. You still need -to define sources for both h5repack and h5prepack, but you needn't type them out twice if -they are the same:</p> - -<p><code>h5repack_SOURCES=...<br> -h5prepack_SOURCES=$(h5repack_SOURCES)</code></p> - -<p>Don't forget to run <code>bin/reconfigure</code> when you're done!</p> -<br> - -<p><h4>Adding a new library</h4></p> - -<p>Suppose you want to add a new library to the HDF5 build tree, libfoo. The procedure for -building libraries is very similar to that for building programs:</p> - -<p><code>lib_LTLIBRARIES=libfoo.la<br> -libfoo_la_SOURCES=sourcefoo.c sourcefootwo.c </code></p> - -<p>This library will be installed in the lib directory when a user types -"<code>make install</code>".<br> -You might instead be building a convenience library for testing purposes (like -<code>libh5test.la</code>) and not want it to be installed. If this is the case, you -would type</p> - -<p><code>check_LTLIBRARIES=libfoo.la</code><br> -instead of<br> -<code>lib_LTLIBRARIES=libfoo.la</code></p> - -<p>To make it easier for other directories to link to your library, -you might want to assign its path to a variable in all HDF5 Makefiles. You can -make changes to all Makefiles by editing <code>config/commence.am</code> and adding a line -like</p> - -<p><code>LIBFOO=$(top_builddir)/foo/src/libfoo.la</code></p> - -<p><code>config/commence.am</code> is textually included in all Makefiles.am when automake -processes them.<br> -As always, if you change a Makefile.am or <code>config/commence.am</code>, don't forget to run -<code>bin/reconfigure</code>.</p> -<br> - -<p><h4>Changing HDF5's API</h4></p> - -<p>If you have added or removed a function from HDF5, or if you have changed a function -signature, you must indicate this by updating the file <code>lt_vers.am</code> located in -the <code>config</code> directory.<br> -If you have changed the API at all, increment <code>LT_VERS_INTERFACE</code> and set -<code>LT_VERS_REVISION</code> to zero.<br> -If you have added functions but not altered or removed existing ones, also increment -<code>LT_VERS_AGE</code>.<br> -If instead you have altered or removed any functions, reset <code>LT_VERS_AGE</code> to -zero.</p> -</body> -</html> |