Difference between revisions of "Initializing Documentation Build Environment"

Revision as of 01:01, 3 May 2019

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

Note

sudo apt-get install libtool

may work if libtoolize is not available.

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 Test Documentation in Linux.

If your build directory is a subdirectory of your repository

../configure [--with-mobi]

Otherwise (depending on where your repository is)

/home/$USER/code/gnucash-docs/configure [--with-mobi]

or use a relative path to run your repository configure script

cd /home/$USER/code/gnucash-docs/
./configure [--with-mobi]

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.

Note: The configure command may issue a WARNING complaining that fop was not found and that you will not be able to generate PDF files. This step is optional and not required for editing the documentation, though a test build of PDFs should be performed and checked before pushing changes to code. See Other Documentation Formats section of the Documentation Release Process page for more information.