Difference between revisions of "Initializing Documentation Build Environment"
m (→Initializing Documentation Build Environment) |
m (→Make a Build Directory Structure and the Makefiles: typo) |
||
| (4 intermediate revisions by 3 users not shown) | |||
| Line 3: | Line 3: | ||
===Generate configure Script=== | ===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. | 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"> | |
| − | + | cd /home/$USER/code/gnucash-docs | |
| + | ./autogen.sh # autogen.sh is *always* run in the top-level *source* directory | ||
| + | </SyntaxHighlight> | ||
'''autogen.sh''' is platform independent and is used to initiate the whole build system for a given project. | '''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: | 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: | ||
| − | + | <SyntaxHighlight lang="sh"> | |
| + | sudo apt-get install autoconf libtoolize automake xsltproc | ||
| + | </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 | As a rule of thumb, autogen.sh should be run | ||
| − | * the first time you want to initialize the build system and sometimes | + | * 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. |
Running autogen.sh when it's not necessary doesn't do harm but it will make the next build take longer. | 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=== | ===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 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. | ||
| − | + | <SyntaxHighlight lang="sh"> | |
| − | + | cd /home/$USER/code/gnucash-docs | |
| − | + | mkdir build # only needed if not previously created | |
| + | cd build # configure must be run from the "build" directory | ||
| + | </SyntaxHighlight> | ||
| − | '''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 [[ | + | '''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 | ||
| − | + | <SyntaxHighlight lang="sh"> | |
| + | ../configure [--with-mobi] | ||
| + | </SyntaxHighlight> | ||
Otherwise (depending on where your repository is) | Otherwise (depending on where your repository is) | ||
| − | + | <SyntaxHighlight lang="sh"> | |
| + | /home/$USER/code/gnucash-docs/configure [--with-mobi] | ||
| + | </SyntaxHighlight> | ||
| + | or use a relative path to run your repository configure script | ||
| + | <SyntaxHighlight lang="sh"> | ||
| + | cd /home/$USER/code/gnucash-docs/ | ||
| + | ./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'''. | 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. | '''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. | ||
| + | |||
| + | [[Category:Documentation Development]] | ||
Revision as of 00:51, 6 December 2018
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.
