Difference between revisions of "Initializing Documentation Build Environment"

From GnuCash
Jump to: navigation, search
m (Generate configure Script)
(Initializing Documentation Build Environment: use <SyntaxHighlight ...>; add Category)
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.
  cd /home/$USER/code/gnucash-docs
+
<SyntaxHighlight lang="sh">
  ./autogen.sh  # autogen.sh is *always* run in the top-level *source* directory
+
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:
  sudo apt-get install autoconf libtoolize automake xsltproc   
+
<SyntaxHighlight lang="sh">
 +
sudo apt-get install autoconf libtoolize automake xsltproc   
 +
</SyntaxHighlight>
 
    
 
    
  Note: sudo apt-get install libtool may work if libtoolize is not available.
+
;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
Line 20: Line 27:
 
===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.
  cd /home/$USER/code/gnucash-docs
+
<SyntaxHighlight lang="sh">
  mkdir build    # only needed if not previously created
+
cd /home/$USER/code/gnucash-docs
  cd build      # configure must be run from the "build" directory
+
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 [[#Step 11 Test Documentation in Linux]].
 
'''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 [[#Step 11 Test Documentation in Linux]].
  
 
If your build directory is a subdirectory of your repository
 
If your build directory is a subdirectory of your repository
  ../configure
+
<SyntaxHighlight lang="sh">
 +
../configure [--with-mobi]
 +
</SyntaxHighlight>
 
Otherwise (depending on where your repository is)
 
Otherwise (depending on where your repository is)
  /home/$USER/code/gnucash-docs/configure   # or use a relative path to run your repository configure script
+
<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 Developement]]

Revision as of 23:52, 5 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 #Step 11 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.