The Make Utility

The make utility is a tool which controls the generation of non-source files of a project from it's source files. In GnuCash it is used for the generation of the documentation and partially the website.

The Make Utility

In the make build system there are three important directories:

• the source directory
• the build directory
• the installation directory (which can also be more than one directory all under a special directory called the prefix-directory)

The source directory is where your source files are. I.e. gnucash-docs (the clone of our github repository) with all its subdirectories on your system for documentation. If you want to make changes to the documentation source, you do this in the source directory structure, not the build directory structure.

The build directory is a directory used by the build system to store all files/objects that are generated by the build system. make is always executed in the build directory or a sub-directory of the build directory. Each make recipe results in at least one such file or object.

The installation directory is the location where the generated objects should finally end up when using make install.

For the GnuCash documentation, the make command must be used with a target argument which determines which type(s) of the documentation are built. E.g. make html builds the html files which allow the documentation to be viewed in a web browser. (If no target is specified, make does nothing because the xml files are both the source and the target which yelp needs to display the documentation.) What make actually does is specified in the contents of make files. These are files called Makefile (or Makefile.am) and exist in multiple directories of the documentation repository. What they do depends on which directory is current when the make command is executed. In general, the lower down the build directory tree, the more specific the scope. By changing the current directory, make can build:

• Both the Help & Guide
• Either the Help or Guide
• Just the Help or Guide for a specific language

As building the documentation can take a while, it is best to only build what is needed for your changes.

Typical targets of the make target command used for the documentation are:

make check                # use xmllint to validate xml files
make html                 # use xsltproc to build the html (web browser) documentation
make pdf                  # use xsltproc and fop to build the pdf documentation
make mobi                 # use xsltproc to build the mobi documentation
make epub                 # use xsltproc to build the mobi documentation

There are additional installation dependencies required for building the pdf and mobi formats. See [1].

To install the built documentation where it can be used for testing the interaction with GnuCash programs:

make install

Note

See Test Documentation in Linux.

Installing make

Linux

make is usually already installed as part of the default installation packages.

macOS

make and git are provided by either Xcode or the Xcode command-line tools. To update the documentation, it is not necessary to install the full Xcode package which is currently a download of over 4 GBs. On OS X 10.8 and later the system should offer to install just the command line tools when you issue a command that they supply; make or git issued in Terminal should do it. If that doesn't work try xcode-select --install; if that also fails you'll need to download the appropriate command-line tools package from Apple\'s developer website where you'll need to sign in with your Apple ID and agree to some terms and conditions if you haven't already set up a developer account.

Windows

It is probably possible but complicated to update the documentation in Windows. Building on Windows may help. It may be easier to install Linux in a virtual machine like VirtualBox instead.