Difference between revisions of "Initializing Documentation Build Environment"

From GnuCash
Jump to: navigation, search
(Make a Build Directory Structure and the Makefiles: added a note with a link about the fop warning)
(Update branches)
 
(18 intermediate revisions by 4 users not shown)
Line 1: Line 1:
 +
[[Category:Documentation Development]]
 +
This page describes the first setup of an build environment for the GnuCash documentation.
 +
 
==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.
+
 
===Generate configure Script===
+
After installing your [[Git|version control system]] and installing a build tool like [[The_Make_Utility|make utility]] or [[Build Tools#Ninja|Ninja]], you should initialize the build environment.
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.
+
 
 +
;Attention: Since GnuCash 4.7 only [[CMake]]—which was introduced in GnuCash 3.0—is supported. Before the documentation supported also [[Autotools]]. See the [https://wiki.gnucash.org/wiki/index.php?title=Initializing_Documentation_Build_Environment&oldid=16246 archived version from 2020] in case you need that.
 +
:;Note:CMake offers the choice (<tt>-G</tt> like generator) between many [https://cmake.org/cmake/help/v3.17/manual/cmake-generators.7.html#manual:cmake-generators(7) different build tools] for the command line or [[:Category:IDE|IDE]]s. To keep it simple, we use <tt>make</tt> aka "Unix Makefiles" in the examples of this page.
 +
 
 +
===Creating the base directory structure===
 +
 
 +
To work on the documentation we'll need two base directories:
 +
* a directory to contain the documentation sources, we'll name ''src'' throughout this page, though you're free to name it as you like. Note you don't have to create this directory manually, it will be created while obtaining the documentation sources.
 +
* a directory to hold the documentation that will be generated from the sources. We'll call this directory ''build''. This one has to be create manually.
 +
 
 +
To avoid potential issues while sending your future changes for inclusion to the GnuCash project it's strongly advised to keep the ''build'' directory '''outside''' of the ''src'' directory. This page will suggest and consistently use the following directory structure:
 +
 
 
<SyntaxHighlight lang="sh">
 
<SyntaxHighlight lang="sh">
cd /home/$USER/code/gnucash-docs
+
<base>/
./autogen.sh  # autogen.sh is *always* run in the top-level *source* directory
+
    gnucash-docs/
 +
        src
 +
        build
 
</SyntaxHighlight>
 
</SyntaxHighlight>
'''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:
+
<base> can be any path in your file system you can write to. Throughout this page we will be using '''$HOME/code''', that is a directory named code in your home directory. So the above will become
 +
 
 
<SyntaxHighlight lang="sh">
 
<SyntaxHighlight lang="sh">
sudo apt-get install autoconf libtoolize automake xsltproc 
+
$HOME/
 +
    code/
 +
        gnucash-docs/
 +
            src
 +
            build
 
</SyntaxHighlight>
 
</SyntaxHighlight>
 
 
;Note: <SyntaxHighlight lang="sh">
 
sudo apt-get install libtool
 
</SyntaxHighlight>
 
:may work if libtoolize is not available.
 
  
As a rule of thumb, autogen.sh should be run
+
;Note: There is a reason we inisist on keeping your ''build'' directory outside of your ''src'' directory. If you don't, all of the build artefacts will be seen by git in your source directory. In that case you have to be extra careful not to include these build artefacts in the patches or PRs you create later on. If you understand this and know for yourself how to avoid this (like by setting the proper exclude rules for git) you can ignore this advice. Otherwise, please stick to this rule.
* the first time you want to initialize the build system and sometimes after
+
 
** any of the packages listed in the <tt>sudo apt</tt> command above are updated or
+
 
** changes are made in <tt>configure.ac</tt> or <tt>Makefile.am</tt> files. Frequently those changes are auto detected though.
+
===Cloning the documentation repository===
Running autogen.sh when it's not necessary doesn't do harm but it will make the next build take longer.
+
You'll need a local copy the source files for the documentation to work. These can be be downloaded from the internet via a tool called [[git]]. That process is commonly called '''cloning'''. You can find more background on cloning repositories in [[git]].
 +
 
 +
However of our purpose the following command will suffice to clone the documentation sources into the ''src'' directory <SyntaxHighlight lang="sh">git clone https://github.com/Gnucash/gnucash-docs $HOME/code/gnucash-docs/src</SyntaxHighlight>  
  
 
===Make a Build Directory Structure and the Makefiles===
 
===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.
+
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 sibling directory next to the repository directory 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.
 
<SyntaxHighlight lang="sh">
 
<SyntaxHighlight lang="sh">
cd /home/$USER/code/gnucash-docs
+
cd $HOME/code/gnucash-docs
 
mkdir build    # only needed if not previously created
 
mkdir build    # only needed if not previously created
 
cd build      # configure must be run from the "build" directory
 
cd build      # configure must be run from the "build" directory
 
</SyntaxHighlight>
 
</SyntaxHighlight>
 
+
====CMake====
'''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 you followed our suggested directory layout
 
 
If your build directory is a subdirectory of your repository
 
 
<SyntaxHighlight lang="sh">
 
<SyntaxHighlight lang="sh">
../configure [--with-mobi]
+
cmake -G"Unix Makefiles" [-DWITH_MOBI=On] ../src
 
</SyntaxHighlight>
 
</SyntaxHighlight>
 
Otherwise (depending on where your repository is)
 
Otherwise (depending on where your repository is)
 
<SyntaxHighlight lang="sh">
 
<SyntaxHighlight lang="sh">
/home/$USER/code/gnucash-docs/configure [--with-mobi]
+
cmake -G"Unix Makefiles" [-DWITH_MOBI=On] <path-to-your-source-repository>
 +
</SyntaxHighlight> If you want to use the faster ninja replace <tt>-G"Unix Makefiles"</tt> by <tt>-GNinja</tt>. In later commands you will have to replace <tt>make</tt> then by <tt>ninja</tt>.
 +
:;Complexer Example: Sources below $HOME/git with a worktree per branch and on the traget side for both tool chains: <SyntaxHighlight lang="sh">
 +
$WS=~/eclipse-workspace/gnucash-docs/ninja
 +
md -p $WS
 +
cd $WS
 +
cmake -G"Eclipse CDT4 - Ninja" -D_ECLIPSE_VERSION=4.26 -DWITH_MOBI=On -S ~/git/gnucash-docs/stable/ -B stable
 +
# import that path in eclipse as project
 
</SyntaxHighlight>
 
</SyntaxHighlight>
or use a relative path to run your repository configure script
+
::On demand repeat <tt>cmake …</tt> for future;
<SyntaxHighlight lang="sh">
+
::Repeat the whole for make;
cd /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 '''Makefile'''s to drive the build system. It can enable or disable certain options in the Makefiles based on its findings.
./configure [--with-mobi]
 
</SyntaxHighlight>
 
 
 
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.
+
''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_XDGHELP: Enable build rules for gnome help document format (default value: ON)
 +
:;WITH_HTML: Enable build rules for html document format (default value: ON)
 +
:;WITH_PDF: Enable build rules for pdf document format (default value: ON)
 +
:;WITH_EPUB: Enable build rules for epub document format (default value: ON)
 +
:;WITH_CHM: Enable build rules for chm document format (''Only available under Windows'', default value: OFF)
 +
:;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]].
  
'''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. See [[Documentation_Release_Process#Other_documentation_formats|Other Documentation Formats]] section of the Documentation Release Process page for more information.
+
'''cmake''' typically has to be run ''only once'' to set up your build environment—as long as you do not add, move, or remove files.
 +
*To rerun it ''without changing its options'' run <syntaxhighlight lang="sh">cmake .</syntaxhighlight>
 +
*And you may want to rerun it to change one or more of the options mentioned above.
  
[[Category:Documentation Development]]
+
;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.

Latest revision as of 23:22, 24 October 2023

This page describes the first setup of an build environment for the GnuCash documentation.

Initializing Documentation Build Environment

After installing your version control system and installing a build tool like make utility or Ninja, you should initialize the build environment.

Attention
Since GnuCash 4.7 only CMake—which was introduced in GnuCash 3.0—is supported. Before the documentation supported also Autotools. See the archived version from 2020 in case you need that.
Note
CMake offers the choice (-G like generator) between many different build tools for the command line or IDEs. To keep it simple, we use make aka "Unix Makefiles" in the examples of this page.

Creating the base directory structure

To work on the documentation we'll need two base directories:

  • a directory to contain the documentation sources, we'll name src throughout this page, though you're free to name it as you like. Note you don't have to create this directory manually, it will be created while obtaining the documentation sources.
  • a directory to hold the documentation that will be generated from the sources. We'll call this directory build. This one has to be create manually.

To avoid potential issues while sending your future changes for inclusion to the GnuCash project it's strongly advised to keep the build directory outside of the src directory. This page will suggest and consistently use the following directory structure:

<base>/
    gnucash-docs/
        src
        build

<base> can be any path in your file system you can write to. Throughout this page we will be using $HOME/code, that is a directory named code in your home directory. So the above will become

$HOME/
    code/
        gnucash-docs/
            src
            build
Note
There is a reason we inisist on keeping your build directory outside of your src directory. If you don't, all of the build artefacts will be seen by git in your source directory. In that case you have to be extra careful not to include these build artefacts in the patches or PRs you create later on. If you understand this and know for yourself how to avoid this (like by setting the proper exclude rules for git) you can ignore this advice. Otherwise, please stick to this rule.


Cloning the documentation repository

You'll need a local copy the source files for the documentation to work. These can be be downloaded from the internet via a tool called git. That process is commonly called cloning. You can find more background on cloning repositories in git.

However of our purpose the following command will suffice to clone the documentation sources into the src directory
git clone https://github.com/Gnucash/gnucash-docs $HOME/code/gnucash-docs/src

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 sibling directory next to the repository directory 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/code/gnucash-docs
mkdir build    # only needed if not previously created
cd build       # configure must be run from the "build" directory

CMake

If you followed our suggested directory layout

cmake -G"Unix Makefiles" [-DWITH_MOBI=On] ../src

Otherwise (depending on where your repository is)

cmake -G"Unix Makefiles" [-DWITH_MOBI=On] <path-to-your-source-repository>
If you want to use the faster ninja replace -G"Unix Makefiles" by -GNinja. In later commands you will have to replace make then by ninja.
Complexer Example
Sources below $HOME/git with a worktree per branch and on the traget side for both tool chains:
$WS=~/eclipse-workspace/gnucash-docs/ninja
md -p $WS
cd $WS
cmake -G"Eclipse CDT4 - Ninja" -D_ECLIPSE_VERSION=4.26 -DWITH_MOBI=On -S ~/git/gnucash-docs/stable/ -B stable
# import that path in eclipse as project
On demand repeat cmake … for future;
Repeat the whole for make;

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_XDGHELP
Enable build rules for gnome help document format (default value: ON)
WITH_HTML
Enable build rules for html document format (default value: ON)
WITH_PDF
Enable build rules for pdf document format (default value: ON)
WITH_EPUB
Enable build rules for epub document format (default value: ON)
WITH_CHM
Enable build rules for chm document format (Only available under Windows, default value: OFF)
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—as long as you do not add, move, or remove files.

  • To rerun it without changing its options run
    cmake .
    
  • And you may want to rerun it to change one or more 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.