Initializing Documentation Build Environment

After installing your version control system, cloning the repository, and installing the make utility, you should initialize the build environment.

Generate configure Script

This step checks that various make utilities (autoconf, libtoolize & automake) are installed and builds the configure script and the Makefile.in files from the configure.ac and Makefile.am files. Makefile.in files are pseudo Makefile's used by the configure script with lots of variables that still need final setting.

 cd /home/$USER/code/gnucash-docs
 ./autogen.sh   # autogen.sh is *always* run in the top-level *source* directory

autogen.sh is platform independent and is used to initiate the whole build system for a given project.

The first time autogen.sh is run, it may complain about missing packages autoconf, libtoolize or automake. You can usually install the generic packages of the same name using your distribution's package manager. You'll probably also need to install xsltproc. For example, in Ubuntu:

 sudo apt-get install autoconf libtoolize automake xsltproc

As a rule of thumb, autogen.sh should be run

the first time you want to initialize the build system and sometimes after
- any of the packages listed in the sudo apt command above are updated or
- changes are made in configure.ac or Makefile.am files. Frequently those changes are auto detected though.

Running autogen.sh when it's not necessary doesn't do harm but it will make the next build take longer.

Make a Build Directory Structure and the Makefiles

Create a build directory structure to keep the built documentation files separate from the repository directories. This page assumes the build directory is called build and is a subdirectory of the repository but that does not have to be so. It can be called whatever suits you, and even be wherever it suits you. Some people create it as a subdirectory to the source directory. Others have it in a completely different location, say to have all builds together under one directory. That is a matter of preference.

 cd /home/$USER/code/gnucash-docs
 mkdir build    # only needed if not previously created
 cd build       # configure must be run from the "build" directory

Note: If you intend to test invoking help from GnuCash programs, you should add the --prefix=... option to the configure command below now to save having to rerun it later. See #Step 11 Test Documentation in Linux.

If your build directory is a subdirectory of your repository

 ../configure

Otherwise (depending on where your repository is)

 /home/$USER/code/gnucash-docs/configure   # or use a relative path to run your repository configure script

The ../configure command above will recreate the gnucash-docs directory structure under the current directory (build) but without the source files. It then looks up the installation location for all tools and libraries used and creates the required Makefiles from the Makefile.in files. It can enable or disable certain options in the Makefiles based on its findings. configure can also take extra command line options that can alter what it will include in the Makefiles. You can see these options by running configure --help. Most of them are not relevant for us, except for the few we invented ourselves like --with-mobi.

configure must be run right after autogen.sh. Running it when not really required has no negative side-effect other than that the next build may take longer because more objects will be rebuilt.

Initializing Documentation Build Environment