Vis5D Porting and Development Notes This file attempts to give a *brief* overview of how the autoconf build system works, for the aid of porters and developers. It centers around the GNU autoconf, autoheader, automake, and libtool development tools, and for more information you should see the GNU documentation, which can be found online (among other places) at: http://www.gnu.org/manual/manual.html --------------------------------------------------------------------------- If Vis5D doesn't build on your machine, what you want to do is: 1) Figure out what you need to do to build it, e.g. replace some function call or link to a particular library. If there are problems during the configure run, look in the file config.log for diagnostic output. 2) Write an autoconf test in configure.in (see below) that tests for the problem. 3) Modify the code or the Makefile.am (see below) to alter its behaviour based upon the result of the test in step (2). --------------------------------------------------------------------------- There are essentially three human-edited files which control the build process: configure.in: specifies what tests to run in the configure script acconfig.h: specifies outputs of configure.in that can't be guessed by autoheader Makefile.am: a high-level type of Makefile for input to automake; there's one of these in each subdirectory too (Oh, there's also an acinclude.m4 file that contains some extra macros for configure.in that I gathered from external sources.) --------------------------------------------------------------------------- When an ordinary user builds Vis5D, what happens is that the configure script generates two things: a) config.h from config.h.in config.h contains #define statements indicating results of most of the configure tests, e.g. #define HAVE_LIBNETCDF 1 if the netcdf library was found. It is included by all of the .c files and used to tailor their behavior to the machine in question. (config.h.in was generated by autoheader, as described below.) b) Makefile(s) from Makefile.in(s) in each directory A Makefile, of course, is just the ordinary thing that 'make' uses. Makefile.in is a template, into which the configure script substitutes things like the C compiler name and the linker flags. (The Makefile.in file, in turn, was generated from Makefile.am by automake; see below.) --------------------------------------------------------------------------- To build everything from scratch, assuming you have up-to-date versions of automake, libtool, autoconf, and autoheader (all of which can be gotten from the GNU web site; autoheader comes with autoconf), you run the included script: % ./autogen.sh Once you've got things built for the first time, though, the Makefiles know enough to rebuild the various things when necessary (usually). Unfortunately, there is a bug in automake-1.4 (which will be fixed in the next release) that causes a problem in the generated Makefile.in (and thus the Makefile). To fix the problem by hand, replace occurrences of "$$/" in the top-level Makefile.in with "$$d/". Below, we'll go into some of the individual commands that are run by autogen.sh in more detail, so you have some idea of what is happening. --------------------------------------------------------------------------- 1) % aclocal This is a command that is part of automake, which you shouldn't have to run often. It fetches necessary macros from various sources and uses them to create aclocal.m4; one of the places it fetches macros from is acinclude.m4, so you'll need to re-run aclocal if acinclude.m4 is changed. 2) % autoheader Scans configure.in and aclocal.m4 to see what tests are performed, and uses them to regenerate config.h.in. config.h.in basically contains default settings for the various preprocessor symbols that will eventually be used in config.h. Rerun this when configure.in, aclocal.m4, or acconfig.h change. 3) % automake automake generates Makefile.in files from Makefile.am files (note that it automatically goes into subdirectories as necessary). Makefile.am files are a sort of very high-level Makefile that doesn't look very much like an ordinary Makefile. It specifies the programs and libraries to be built, and automake automatically generates things like: * sets up all the templates where the configure script can substitute its build information (e.g. C compiler flags) * install and uninstall targets * handles shared libraries (which are otherwise nigh-impossible to do portably) You'll need to re-run automake when the Makefile.am files change 4) % autoconf Generates the configure script from configure.in and aclocal.m4. As mentioned above, the configure.in file specifies tests to be performed to determine system features, using a mixture of the m4 macro language and the Bourne Shell (sh) script. autoconf supplies a large number of predefined macros to help you test for features; e.g. AC_PROG_CC is a macro to find out the name of the C compiler. Rerun this when configure.in or aclocal.m4 change. The general philosophy of autoconf is to actively go out and look for a feature, instead of trying to infer it from other information. For example, if you want to know whether your system has the setrlimit() function, it doesn't look at the system name and then go to a table of systems and features. Instead, it directly tries to link a C program calling setrlimit and sees if it succeeds. You specify this in configure.in by calling the following macro: AC_CHECK_FUNCS(setrlimit) (This will #define HAVE_SETRLIMIT in config.h if it is successful, which we can then use to decide in our program if we want to call that function.) Because of this philosophy, a program that is maintained with autoconf will generally compile and run even on many systems that the developer didn't specifically anticipate. --------------------------------------------------------------------------- Standard build targets (can be run after the Makefile is generated by configure): % make Builds the program, libraries, and utilities, automatically rerunning autoconf, autoheader, automake, and/or aclocal if the relevant files have changed. % make clean Gets rid of all object files, libraries, and programs produced by make. You may need to do this if you change a header file or something and the software isn't rebuilding completely (the Makefiles don't have all the possible dependency rules for header files). % make install Install the software under the installation prefix. % make distclean Restore to the state in which Vis5d is distributed. Does 'make clean' and in addition gets rid of the cached configure information, Makefiles, etcetera. configure must be re-run after this if you want to do anything else. % make maintainer-clean Gets rid of even more files than 'make distclean', including some files that may need special tools to rebuild. Currently, this doesn't do much; if you really want to clean the directory, use: % make super-clean Gets rid of *all* the automatically generated files, including the configure script, the Makefile.in files, etcetera. You will need to re-run autogen.sh. Don't do this unless you have automake, autoconf, etcetera! % make dist Make the distribution package; results in a file vis5d-.tar.gz in the current directory. This is the file that you should give out to users. The nice thing about this is that you don't have to worry about any files you might have lying around from your development efforts; only those files explicitely specified in the Makefile.am's will go into the dist.