gnut is very popular with programmers. However, I have gotten so many suggested patches from people who don't understand the autoconf system that I have had to write this little instructions file. If you never want to change any source files, but just want to get gnut running, read the paragraph under "Your First Build" below. For all the rest of you, I have provided specific instructions on what to do after changing any of the "special" source files. For example, if you want to change Makefile you can skip down to the paragraph under "To update 'Makefile'" I have also provided the history of building so that you can easily get up-to-date on the auto*tools and learn why it is so bloody complicated. If you are new to the auto*tools, please remember that this file is here and consult it before sending me any changes to the special files. Your First Build (if you haven't edited any files) Before you can do anything you have to untar the tarfile, which creates a directory "gnut-0.X.XX", and then go into that directory. All the build instructions assume you are in that directory. Here's how to do your first build: mv configure conf-warning mv conf-real configure ./configure (or 'sh ./configure' if in csh on SysV) make make install (only if you want to put it in /usr/local/bin) Source code changes: If you change code, but aren't adding any #include statements, you just have to recompile. This includes any other ".c" file and any ".h" file EXCEPT config.h or acconfig.h. To make the changes take effect, just repeat these steps: make make install (only if you want to put it in /usr/local/bin) *All other changes* All other changes, including adding a "#include" statement to a .c or .h file, require that you have automake and autoconf on your system. Please don't send me patches to the Makefile, or any of the other special files, unless you know it isn't an auto-generated file. Instead read below and see which file you *really* need to change. Also note, the auto-tools are still changing; for the latest updates on how to use them, see the URLs listed at the end of this file under "References". After editing "acconfig.h" "acconfig.h" and "configure.in" are co-dependent. That means, if you change one, you might have to (or want to) change the other. Specifically, any features tested for by configure.in might need to have their #define symbol added to acconfig.h -- and anytime you add a #define symbol to acconfig.h you need to add a test for that feature to configure.in. After making such changes, you should type one command: autoheader followed by all the commands listed under "aclocal.m4". After editing "aclocal.m4" After changing "aclocal.m4", type: aclocal -I macros followed by all the commands listed under "configure.in". To update "config.cache" This file depends on your installed system and on "configure.in". It is auto-generated, so you shouldn't edit it directly. "config.cache" only changes if you change something installed in your system (like updating libraries or drivers) or if you edit "configure.in". If either of these happens, follow the instructions under "configure.in" to update "config.cache". To update "config.h" This file depends on "config.h.in". It is auto-generated, so you shouldn't edit it directly. To change something in "config.h", you have to edit "config.h.in" and then follow the instructions under "config.h.in". To update "config.log" This file depends on your installed system and on "configure.in". It is auto-generated, so you shouldn't edit it directly. "config.log" only changes if you change something installed in your system (like updating libraries or drivers) or if you edit "configure.in". If either of these happens, follow the instructions under "configure.in" to update "config.log". To update "config.status" This file depends on your installed system and on "configure.in". It is auto-generated, so you shouldn't edit it directly. "config.status" only changes if you change something installed in your system (like updating libraries or drivers) or if you edit "configure.in". If either of these happens, follow the instructions under "configure.in" to update "config.status". To update "configure" This file depends on "configure.in". It is auto-generated, so you shouldn't edit it directly. To change something in "configure", you have to edit "configure.in" and then follow the instructions under "configure.in". After editing "configure.in" autoconf automake -a rm config.cache ./configure make make install (only if you want to put it in /usr/local/bin) To update "install-sh" This file is automatically generated by "automake -a", but it has no source file (it comes from the system automake directory). You shouldn't ever have to change "install-sh". If you have just installed a new version of "automake", you should update your "install-sh" and the two other files "missing" and "mkinstalldirs" by doing: rm install-sh rm missing rm mkinstalldirs automake -a To update "Makefile" Makefile depends on Makefile.in and ./configure, and they depend on Makefile.am and configure.in. To get Makefile to change, you should change Makefile.am and then follow the instructions for "Makefile.am". After changing "Makefile.am" After changing "Makefile.am", do these commands: autoconf automake -a rm config.cache ./configure make make install (only if you want to put it in /usr/local/bin) To update "Makefile.in" Makefile.in depends on Makefile.am. To get Makefile.in to change, you should change Makefile.am and then follow the instructions for "Makefile.am". To update "missing" This file is treated the same way as "install-sh" -- see the instructions for "install-sh". To update "mkinstalldirs" This file is treated the same way as "install-sh" -- see the instructions for "install-sh". Explanation (why is it so hard to do a full rebuild?) It's all because of the compatibility problems between different versions of Unix. To handle all the different types of Unix, there have to be a lot of different types of source files, and a lot of different rules for what to do if you want to change something. The best way to explain it is by going through the history. Originally, all changes were made just by changing C source code (in the ".c" and ".h" files) and typing "cc" to compile it into a binary: sources -. \ cc \ `-> binary Then, people figured out that they could save a lot of time by creating a list of rules for which ".c" files depend on which ".h" files. Then, you could compile faster if you only changed one ".c" file. The "make" tool was developed, a program that would automatically figure out what needed to be recompiled. "make" takes a new source file, called "Makefile", and also uses all the program source files. Rebuilding still consisted of just one step: Makefile and -. sources \ make \ `-> binary "make" wasn't quite as smart as it should have been. If you wanted to change the "Makefile" (like when you add new source files) you had to type a special command like "make clean" to force it to recompile everything. Commands like "make clean" are still used today. After a few years, different versions of Unix started to exist (like BSD vs. AT&T System III), and people noticed that you had to change the ".c" and ".h" files in different ways depending on what type of Unix you were compiling for. Those changes were called "configuration", and were kind of tedious, because it took a lot of knowledge and diligence to make all the correct changes for your own particular type of Unix. Eventually it was decided all such changes should be controlled by #ifdef tests (like "#ifdef BSD_4_1"), and the #defines could be specified in the Makefile. Building then required two steps: generic Makefile -. \ STEP 1. manually-edit \ `-> custom Makefile Makefile and -. sources \ STEP 2. make \ `-> binary Next, standard "configuration systems" were created. Usually a configuration system was a set of shell scripts that made all the tests and modifications automatically. The effect was to replace the first manual step with something more automatic. For example, there might be a script called "configure" that did the work. The "configure" script was what you edited when you wanted to change the Makefile, and the Makefile became an automatically-generated file. The two build steps became: configuration-files -. \ STEP 1. configure \ `-> Makefile Makefile and -. sources \ STEP 2. make \ `-> binary Several different types of configuration systems were in place by 1992. Some consisted of a script called "configure" that did all the tests to see what type of Unix you're running on, then generated the Makefiles. The configure script had to know a lot about the syntax of makefiles, as well as knowing a lot about how to test for different features of operating systems. Eventually, the job of doing the operating-system tests and the job of creating the Makefiles from "Makefile templates" was split up into two different tools. By 1994 it was generally agreed that the best tool for the operating-system tests was "autoconf". It took one new source file: "configure.in" and generated a script called "configure" as output. The "configure" script, in turn, took one new source file called "Makefile.in", and generated "Makefile" as an output file. At this point the build had three steps that worked like this: configure.in -. \ STEP 0. autoconf \ `-> configure Makefile.in -. \ STEP 1. configure \ `-> Makefile Makefile and -. sources \ STEP 2. make \ `-> binary Note that Step 0 only had to be done if you changed the configuration requirements, like if you added a major new feature that depended on something that is different on different systems (an example would be adding a graphical user interface to a program that was previously text-only). Therefore, the build process was now split into the "user installation" steps (steps 1 and 2) and the "complete rebuild from scratch" (steps 0 1 and 2) The weak point in this system was "Makefile.in". This had to be a very large and complex file, because it contained all the rules for how to generate a "Makefile", and Makefiles were pretty complex and vary a lot from one OS to another, and since Makefile.in was a source file it had to be edited manually. Most of "Makefile.in" was the same regardless of what program you were building, and programmers found it cumbersome. The solution to that was "automake". It automatically creates "Makefile.in" from another new source file, called "Makefile.am". By 1996, the standard build process had four steps (two for users doing an install and two more for people adding new features) and the steps were: configure.in -. \ STEP 0-A. autoconf \ `-> configure Makefile.am -. \ STEP 0-B. automake \ `-> Makefile.in Makefile.in -. \ STEP 1. configure \ `-> Makefile Makefile and -. sources \ STEP 2. make \ `-> binary Over the next couple years, "configure.in" got bigger and included lots of code to test for lots of different types of libraries, drivers, operating systems, etc. Eventually "configure.in" became the biggest and hardest-to-maintain file, just like "Makefile.in" had been. More recent versions of "autoconf" have solved this by allowing for the use of a "macros" file called "aclocal.m4". The "macros" are written in a language called "m4", and they contain the rules for performing all sorts of different operating-system tests. As far as the build process is concerned, these can be treated as part of step 0-A, except that you don't ever have to worry about changing the contents of "aclocal.m4": configure.in aclocal.m4 -. \ STEP 0-A. autoconf \ `-> configure STEP 0-B. (automake step, same as above) STEP 1. (configure step, same as above) STEP 2. (make step, same as above) Around the same time it also became common to use a tool called "aclocal" to generate "aclocal.m4", from a directory of macros files called "macros". This added a fifth step to the full build process: configure.in macros/*.m4 -. \ STEP 0-A. aclocal -I macros \ `-> aclocal.m4 configure.in aclocal.m4 -. \ STEP 0-B. autoconf \ `-> configure STEP 0-C. (automake step, same as above) STEP 1. (configure step, same as above) STEP 2. (make step, same as above) Complete list of files and the order in which they are built: ORIGINAL FILES the file: configure.in is created from: typed in by hand the file: src/gnut.c is created from: typed in by hand the file: src/gnut.h is created from: typed in by hand the file: src/anything.c (any ".c" not listed below) is created from: typed in by hand the file: src/anything.h (any ".h" not listed below) is created from: typed in by hand AUTO_GENERATED FILES the file: config.h.in is created from: acconfig.h configure.in acconfig.h by: autoheader the file: config.h is created from: config.h.in by: ./configure References: http://sources.redhat.com/autobook/autobook/autobook_toc.html http://sources.redhat.com/autobook/autobook/autobook_15.html If those links are all dead, do a search-engine search for something like: "automake autoconf HOWTO" "autoconf tutorial" "Makefile configure build aclocal" Those are just suggestions. You need to try different combinations of jargon-words like those shown here until you find a good page that contains the type of info you need.