diff options
Diffstat (limited to 'doc/html/TechNotes/Automake.html')
| -rw-r--r-- | doc/html/TechNotes/Automake.html | 223 |
1 files changed, 223 insertions, 0 deletions
diff --git a/doc/html/TechNotes/Automake.html b/doc/html/TechNotes/Automake.html new file mode 100644 index 0000000..c6dfc41 --- /dev/null +++ b/doc/html/TechNotes/Automake.html @@ -0,0 +1,223 @@ +<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> |