Difference between revisions of "Initializing Documentation Build Environment"
(Clarify that a PDF check is needed before final merge.) |
(Amend for cmake support) |
||
| Line 1: | Line 1: | ||
==Initializing Documentation Build Environment== | ==Initializing Documentation Build Environment== | ||
After installing your [[Git|version control system]], cloning the repository, and installing the [[The_Make_Utility|make utility]], you should initialize the build environment. | After installing your [[Git|version control system]], cloning the repository, and installing the [[The_Make_Utility|make utility]], you should initialize the build environment. | ||
| + | |||
| + | ;Note: Starting from the 3.x series of gnucash the documentation supports two build systems [[Autotools]] or [[CMake]]. Autotools support will be dropped at some point so if you are setting up a new build environment you're encouraged to use CMake. Where the command to work with these separate build systems differ this will be indicated in the information below. | ||
| + | |||
===Generate configure Script=== | ===Generate configure Script=== | ||
| + | ;(Autotools only): This step is only required for autotools. It's not needed (and can't be done) for cmake. | ||
| + | |||
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. | 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. | ||
<SyntaxHighlight lang="sh"> | <SyntaxHighlight lang="sh"> | ||
| Line 33: | Line 38: | ||
</SyntaxHighlight> | </SyntaxHighlight> | ||
| − | + | ====Autotools==== | |
| + | ;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 | If your build directory is a subdirectory of your repository | ||
| Line 43: | Line 49: | ||
/home/$USER/code/gnucash-docs/configure [--with-mobi] | /home/$USER/code/gnucash-docs/configure [--with-mobi] | ||
</SyntaxHighlight> | </SyntaxHighlight> | ||
| − | or | + | |
| + | 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 '''Makefile'''s 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 [[Documentation_Release_Process#Other_documentation_formats|Other Documentation Formats]] section of the Documentation Release Process page for more information. | ||
| + | |||
| + | ====CMake==== | ||
| + | If your build directory is a subdirectory of your repository | ||
| + | <SyntaxHighlight lang="sh"> | ||
| + | cmake -G"Unix Makefiles" [-DWITH_MOBI=On] .. | ||
| + | </SyntaxHighlight> | ||
| + | Otherwise (depending on where your repository is) | ||
<SyntaxHighlight lang="sh"> | <SyntaxHighlight lang="sh"> | ||
| − | + | cmake -G"Unix Makefiles" [-DWITH_MOBI=On] /home/$USER/code/gnucash-docs | |
| − | |||
</SyntaxHighlight> | </SyntaxHighlight> | ||
| − | The '' | + | The ''cmake'' command above will recreate the gnucash-docs directory structure under the current directory (build) but without the source files. It then checks whether it can find all the tools and libraries required for successfully generating the documentation and creates the required '''Makefile'''s to drive the build system. It can enable or disable certain options in the Makefiles based on its findings. |
| + | |||
| + | ''cmake'' can also take extra command line options that can alter what it will include in the Makefiles. They are passed in the form '''-D<option-name>=<option-value>'''. The most relevant ones for our documentation build system are: | ||
| + | * '''WITH_GHELP''' Enable build rules for gnome help document format (default value: OFF) | ||
| + | * '''WITH_HTML''' Enable build rules for html document format (default value: OFF) | ||
| + | * '''WITH_PDF''' Enable build rules for pdf document format (default value: OFF) | ||
| + | * '''WITH_EPUB''' Enable build rules for epub document format (default value: OFF) | ||
| + | * '''WITH_CHM''' Enable build rules for chm document format (default value: ON) | ||
| + | * '''WITH_MOBI''' Enable build rules for Mobipocket document format (default value: OFF) | ||
| + | * '''CMAKE_INSTALL_PREFIX''' Defines the final location where the documentation will be installed (default value: /usr/local/bin). If you intend to test invoking help from GnuCash programs, you should set this path now to save you from having to rerun cmake later. See [[Test Documentation in Linux]]. | ||
| − | ''' | + | '''cmake''' typically has to be run only once to set up your build environment. Rerunning it again later has no negative side-effect. And you may want to rerun it to change one of the options mentioned above. |
| − | + | ;Note: cmake will emit errors if some of the build requirement are not met. You have to resolve these errors and rerun cmake before proceeding to the next step. In addition it may also issue WARNINGs, like the warning the fop is not found and that you will not be able to generate PDF files. Warnings suggest some parts are missing preventing some optional build steps from running. The pdf generation step is such an optional one. It's not required for editing the documentation, though a test build of PDFs should be performed and checked before pushing changes to code. See [[Documentation_Release_Process#Other_documentation_formats|Other Documentation Formats]] section of the Documentation Release Process page for more information. | |
[[Category:Documentation Development]] | [[Category:Documentation Development]] | ||
Revision as of 10:55, 28 April 2020
Contents
Initializing Documentation Build Environment
After installing your version control system, cloning the repository, and installing the make utility, you should initialize the build environment.
- Note
- Starting from the 3.x series of gnucash the documentation supports two build systems Autotools or CMake. Autotools support will be dropped at some point so if you are setting up a new build environment you're encouraged to use CMake. Where the command to work with these separate build systems differ this will be indicated in the information below.
Generate configure Script
- (Autotools only)
- This step is only required for autotools. It's not needed (and can't be done) for cmake.
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
Autotools
- 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]
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.
CMake
If your build directory is a subdirectory of your repository
cmake -G"Unix Makefiles" [-DWITH_MOBI=On] ..
Otherwise (depending on where your repository is)
cmake -G"Unix Makefiles" [-DWITH_MOBI=On] /home/$USER/code/gnucash-docs
The cmake command above will recreate the gnucash-docs directory structure under the current directory (build) but without the source files. It then checks whether it can find all the tools and libraries required for successfully generating the documentation and creates the required Makefiles to drive the build system. It can enable or disable certain options in the Makefiles based on its findings.
cmake can also take extra command line options that can alter what it will include in the Makefiles. They are passed in the form -D<option-name>=<option-value>. The most relevant ones for our documentation build system are:
- WITH_GHELP Enable build rules for gnome help document format (default value: OFF)
- WITH_HTML Enable build rules for html document format (default value: OFF)
- WITH_PDF Enable build rules for pdf document format (default value: OFF)
- WITH_EPUB Enable build rules for epub document format (default value: OFF)
- WITH_CHM Enable build rules for chm document format (default value: ON)
- WITH_MOBI Enable build rules for Mobipocket document format (default value: OFF)
- CMAKE_INSTALL_PREFIX Defines the final location where the documentation will be installed (default value: /usr/local/bin). If you intend to test invoking help from GnuCash programs, you should set this path now to save you from having to rerun cmake later. See Test Documentation in Linux.
cmake typically has to be run only once to set up your build environment. Rerunning it again later has no negative side-effect. And you may want to rerun it to change one of the options mentioned above.
- Note
- cmake will emit errors if some of the build requirement are not met. You have to resolve these errors and rerun cmake before proceeding to the next step. In addition it may also issue WARNINGs, like the warning the fop is not found and that you will not be able to generate PDF files. Warnings suggest some parts are missing preventing some optional build steps from running. The pdf generation step is such an optional one. It's 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.
