Difference between revisions of "Initializing Documentation Build Environment"
m (→Initializing Documentation Build Environment) |
(→CMake: Rerun for new images) |
||
| Line 55: | Line 55: | ||
:: 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]]. | :: 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 | + | '''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. | ||
;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. | ;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. | ||
Revision as of 00:39, 3 August 2022
This page describes the first setup of an build environment for the GnuCash documentation.
Contents
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.
As mentioned in Documentation_Improvement#Initial_Steps we suggest starting contributors to use the following directory structure to work in:
$HOME/
code/
gnucash-docs/
src
build
$HOME/coderepresents a starting directory in which you will group all your coding or documentation work. You're free to choose this as you see fit. If you choose a different base path, remember to replace $HOME/code with your base path everywhere in the commands you'll find below.
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 directorygit 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>
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: 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.
