Difference between revisions of "Build Tools"

From GnuCash
Jump to: navigation, search
(→‎Autotools: explain autogen.sh)
(→‎Autotools (deprecated): dropped by gnucash)
 
(25 intermediate revisions by 5 users not shown)
Line 1: Line 1:
−
__NOTOC__
+
 
 +
{| class="wikitable" style="margin: auto;"
 +
! scope="row"|Languages
 +
| [[de/{{PAGENAME:Gnucash}}|Deutsch]]
 +
| [[He/{{PAGENAME:כלי_בניה}}|עִברִית]]
 +
|}
 
The GnuCash project uses several different tools to build the program, the docs, and OS specific packages.
 
The GnuCash project uses several different tools to build the program, the docs, and OS specific packages.
  
Line 6: Line 11:
  
 
=== Make ===
 
=== Make ===
−
[https://en.wikipedia.org/wiki/Make_(software) Make] is a ''build automation tool'' that builds executable programs and libraries from source code by reading files called '''Makefiles''' which specify how to derive the target program. Though integrated development environments and language-specific compiler features can also be used to manage a build process, Make remains widely used, especially in Unix and Unix-like operating systems.  
+
[https://en.wikipedia.org/wiki/Make_(software) Make] is a ''build automation tool'' that builds targets from source by interpreting recipe files called ''Makefiles'' which specify how to transform the source file(s) into the target file(s). Many "Integrated Development Environments" or "IDEs" use <code>make</code> (or its Microsoft cousin <code>nmake</code>) to perform the build. Makefiles can be written by hand (as is the case for '''gnucash-htdocs.git''') or generated by [[#Autotools|Autotools]] or [[#CMake|CMake]]. Make can be invoked recursively to build complex programs and use file timestamps to only recompile files and libraries where a dependency has been changed. Makefiles ususally specify a number of targets of the build which may be supplied as arguments when make is called to perform specific actions to produce specific outputs.
−
 
 
−
It is directly used in '''gnucash-htdocs''', indirectly by [[#Autotools|Autotools]] and optionally by [[#CMake|CMake]].
 
  
 
=== Ninja ===
 
=== Ninja ===
 
[https://en.wikipedia.org/wiki/Ninja_(build_system) Ninja] is a small build system with a focus on speed. It is designed to have its input files generated by a higher-level build system, and it is designed to run builds as fast as possible.
 
[https://en.wikipedia.org/wiki/Ninja_(build_system) Ninja] is a small build system with a focus on speed. It is designed to have its input files generated by a higher-level build system, and it is designed to run builds as fast as possible.
 
;Note: The commands change then from <code>make [target]</code> to <code>ninja [target]</code>.
 
;Note: The commands change then from <code>make [target]</code> to <code>ninja [target]</code>.
 +
;Note: Some Linux distributions name the command <code>ninja-build</code> to distinguish it from another program called <code>ninja</code>.
 +
A comparison of CMake with the make utility is available [https://ninja-build.org/manual.html#_comparison_to_make here]
  
−
You can use it in [[#CMake|CMake]].
+
[[#CMake|CMake]] is commonly used to configure <code>ninja</code> build files: To do so pass <code>-G Ninja</code> among the <code>cmake</code> arguments.
  
 
== Tool Chains ==
 
== Tool Chains ==
−
In addition, GnuCash uses different ''tool chains'' to control the basic tools mentioned above. The program makes use of the '''CMake''' tool chain, while the documentation uses the '''Autotools''' tool chain. The website is compiled directly using [[#Make|Make]].
+
In addition, GnuCash uses different ''tool chains'' to control the basic tools mentioned above. The program makes use of the '''CMake''' as the base of its tool chain, while the user documentation uses the '''Autotools''' as the base of the tool chain. The website is compiled directly using [[#Make|Make]]. The API documentation is created from the source code using [[#Make|Make]] or [[#Ninja|Ninja]], depending on how the source code build system is configured.
  
 
=== CMake ===
 
=== CMake ===
−
To build the '''program''', we use [https://en.wikipedia.org/wiki/CMake CMake].It is a cross-platform free and open-source software application for managing the build process of software using a compiler-independent method. It supports directory hierarchies and applications that depend on multiple libraries. It is used in conjunction with native build environments such as make, Apple's Xcode, and Microsoft Visual Studio. It has minimal dependencies, requiring only a C++ compiler on its own build system.  
+
To set up or configure the '''program''' build system, we use [https://en.wikipedia.org/wiki/CMake CMake]. It should also be used for the '''Gnucash-docs'''.
 +
 
 +
It is a cross-platform free and open-source software application for managing the build process of software using a compiler-independent method. It supports directory hierarchies and applications that depend on multiple libraries. It is used in conjunction with native build environments such as make, Apple's Xcode, and Microsoft Visual Studio. It has minimal dependencies, requiring only a C++ compiler on its own build system. At present, CMake is primarily used to configure the build system by creating the input files for either the '''make'''  or the '''ninja''' build programs which compile and link the program and its libraries. These utilities also control installation of the program and libraries.
 +
See [[CMake#GnuCash Configuration Variables]].
 +
 
 +
=== Autotools (no longer used by us, but several of our dependencies) ===
 +
 
 +
We used to rely on the [https://en.wikipedia.org/wiki/GNU_Build_System GNU Build System] to set up or configure the '''Gnucash-docs''' build system. This is also often referred to as "autotools". We dropped it in Gnucash 4.7!
  
−
=== Autotools ===
+
It's a complex and capable system for configuring and building a wide range of projects on a wide range of platforms. [https://autotools.io/index.html The Autotools Mythbuster] provides an excellent tutorial and reference for those wishing to learn about creating and building projects using the system.
  
−
To build the '''Gnucash-docs''', we use Autotools, which consists of several parts, of which 2 are important:
+
For those who simply need to build the documentation from source, the following three commands will suffice:
 +
#<code>autogen.sh</code>: Checks that all required parts of the build system are installed, then builds the <code>configure</code> program from its source, <code>configure.ac</code> and the intermediate Makefiles <code>Makefile.in</code> from their source <code>Makefile.am</code>. You'll run <code>autogen.sh</code> after you first clone <code>gnucash-docs.git</code>, any time you edit a <code>Makefile.am</code> or <code>configure.ac</code>, and any time you pull commits with changes to those files. Since it does no harm to run it unnecessarily we recommend that you run it after any <code>git pull</code>.
 +
#(not required, but suggested)<Syntaxhighlight lang="sh">
 +
mkdir .build
 +
cd .build</Syntaxhighlight>
 +
#;Note: <tt>configure</tt> and <tt>make</tt> commands are run from this ${BUILDDIR} while sources are edited in the parental ${SOURCEDIR}.
 +
#<code>configure</code>: This shell script, generated by <code>autogen.sh</code> as described above, examines your system and its arguments to convert the intermediate <code>Makefile.in<code> to <code>Makefile</code> that the <code>make</code> command will use to actually generate the documentation product files. One can get a listing of the arguments and environment variables that any particular <code>configure</code> understands by running <code>configure --help</code>.
 +
#<code>make</code>: Using <code>Makefile</code> as a template, <code>make</code> runs the various programs and scripts needed to perform the build. Its arguments are the targets to be built; there are two special targets, <code>make check</code> runs tests to ensure that the project has been built correctly and <code>make install</code> moves the build products to the locations from which they may be used.
  
−
# [https://en.wikipedia.org/wiki/Autoconf Autoconf] is a tool for producing '''configure''' scripts for building, installing and packaging software on computer systems where a [https://en.wikipedia.org/wiki/Bourne_shell Bourne shell] is available.
+
'''Return to:
−
# [https://en.wikipedia.org/wiki/Automake Automake] automatically generates one or more '''Makefile.in''' from files called '''Makefile.am'''. Each Makefile.am contains, among other things, useful variable definitions for the compiled software, such as compiler and linker flags, dependencies and their versions, etc. The generated Makefile.ins are portable and compliant with the Makefile conventions in the GNU Coding Standards, and may be used by configure scripts to generate a working Makefile.
 
  
−
So there remain 3 basic steps:
+
[[Building |Building GnuCash]]
−
# After checking out of the repository run <code>./autogen.sh</code>.
 
−
#:[https://github.com/Gnucash/gnucash-docs/blob/maint/autogen.sh autogen.sh] checks for the existence of autotools and (probably other build tools like intltool) and prepares your directory to use them. ''After you  updated'' at least one of the in the file mentioned tools, you should rerun it.
 
−
#* Decide, which build directory to use and run the following steps in your build dir.
 
−
# After you
 
−
#* installed ''updates'' of not in autogen.sh mentioned tools or used libraries or
 
−
#* modified ''makefile.am'' or ''configure.ac''
 
−
#: run <code>configure [options]</code>.
 
−
#:;Tip: <code>configure --help</code> will give you the full list of possible options.
 
−
# Finally after your edits run  <code>make <target></code>. Some common targets are <tt>all</tt>, <tt>check</tt>, <tt>install</tt>.
 
  
−
[[Category:Development]]
+
[[Category:Development]] [[Category:Building]] [[Category:Tools]]

Latest revision as of 19:38, 20 October 2021

Languages Deutsch עִברִית

The GnuCash project uses several different tools to build the program, the docs, and OS specific packages.

Basic Tools

These control the build process at a low level.

Make

Make is a build automation tool that builds targets from source by interpreting recipe files called Makefiles which specify how to transform the source file(s) into the target file(s). Many "Integrated Development Environments" or "IDEs" use make (or its Microsoft cousin nmake) to perform the build. Makefiles can be written by hand (as is the case for gnucash-htdocs.git) or generated by Autotools or CMake. Make can be invoked recursively to build complex programs and use file timestamps to only recompile files and libraries where a dependency has been changed. Makefiles ususally specify a number of targets of the build which may be supplied as arguments when make is called to perform specific actions to produce specific outputs.

Ninja

Ninja is a small build system with a focus on speed. It is designed to have its input files generated by a higher-level build system, and it is designed to run builds as fast as possible.

Note
The commands change then from make [target] to ninja [target].
Note
Some Linux distributions name the command ninja-build to distinguish it from another program called ninja.

A comparison of CMake with the make utility is available here

CMake is commonly used to configure ninja build files: To do so pass -G Ninja among the cmake arguments.

Tool Chains

In addition, GnuCash uses different tool chains to control the basic tools mentioned above. The program makes use of the CMake as the base of its tool chain, while the user documentation uses the Autotools as the base of the tool chain. The website is compiled directly using Make. The API documentation is created from the source code using Make or Ninja, depending on how the source code build system is configured.

CMake

To set up or configure the program build system, we use CMake. It should also be used for the Gnucash-docs.

It is a cross-platform free and open-source software application for managing the build process of software using a compiler-independent method. It supports directory hierarchies and applications that depend on multiple libraries. It is used in conjunction with native build environments such as make, Apple's Xcode, and Microsoft Visual Studio. It has minimal dependencies, requiring only a C++ compiler on its own build system. At present, CMake is primarily used to configure the build system by creating the input files for either the make or the ninja build programs which compile and link the program and its libraries. These utilities also control installation of the program and libraries. See CMake#GnuCash Configuration Variables.

Autotools (no longer used by us, but several of our dependencies)

We used to rely on the GNU Build System to set up or configure the Gnucash-docs build system. This is also often referred to as "autotools". We dropped it in Gnucash 4.7!

It's a complex and capable system for configuring and building a wide range of projects on a wide range of platforms. The Autotools Mythbuster provides an excellent tutorial and reference for those wishing to learn about creating and building projects using the system.

For those who simply need to build the documentation from source, the following three commands will suffice:

  1. autogen.sh: Checks that all required parts of the build system are installed, then builds the configure program from its source, configure.ac and the intermediate Makefiles Makefile.in from their source Makefile.am. You'll run autogen.sh after you first clone gnucash-docs.git, any time you edit a Makefile.am or configure.ac, and any time you pull commits with changes to those files. Since it does no harm to run it unnecessarily we recommend that you run it after any git pull.
  2. (not required, but suggested)
    mkdir .build
cd .build
    Note
    configure and make commands are run from this ${BUILDDIR} while sources are edited in the parental ${SOURCEDIR}.
  3. configure: This shell script, generated by autogen.sh as described above, examines your system and its arguments to convert the intermediate Makefile.in<code> to <code>Makefile that the make command will use to actually generate the documentation product files. One can get a listing of the arguments and environment variables that any particular configure understands by running configure --help.
  4. make: Using Makefile as a template, make runs the various programs and scripts needed to perform the build. Its arguments are the targets to be built; there are two special targets, make check runs tests to ensure that the project has been built correctly and make install moves the build products to the locations from which they may be used.

Return to:

Building GnuCash

Retrieved from "https://code.gnucash.org/wiki/index.php?title=Build_Tools&oldid=20342"