Difference between revisions of "The Make Utility"

From GnuCash
Jump to: navigation, search
(→‎Generating documentation)
(help -> manual; …)
 
(One intermediate revision by the same user not shown)
Line 1: Line 1:
−
The [https://www.gnu.org/software/make/ make] utility is a tool which controls the generation of non-source files of a project from it's source files. In GnuCash it is used for the generation of the documentation and partially the website.
+
The [{{URL:Gnu}}software/make/ make] utility is a tool which controls the generation of non-source files of a project from it's source files. In GnuCash it is used for the generation of the documentation and partially the website.
 +
 
 +
[[Category:Documentation Development]]
  
 
==The Make Utility==
 
==The Make Utility==
−
 
 
In the ''make'' build system there are three important directories:
 
In the ''make'' build system there are three important directories:
−
* the source directory
+
* the '''source''' directory
−
* the build directory
+
* the '''build''' directory
−
* the installation directory (which can also be more than one directory all under a special directory called the prefix-directory)
+
* the '''installation''' directory (which can also be more than one directory all under a special directory called the prefix-directory)
  
−
The ''source'' directory is where your source files are. I.e. '''gnucash-docs''' (the clone of our github repository) with all its subdirectories on your system for documentation. If you want to make changes to the documentation source, you do this in the source directory structure, not the build directory structure.
+
The ''source'' directory is where your source files are. I.e. <tt>gnucash-docs</tt> —your local clone of our github repository— with all its subdirectories. If you want to make changes to the documentation source, you do this in the source directory structure, not the build directory structure.
  
 
The ''build'' directory is a directory used by the build system to store all files/objects that are generated by the build system. '''make''' is always executed in the build directory or a sub-directory of the build directory. Each make ''recipe'' results in at least one such file or object.
 
The ''build'' directory is a directory used by the build system to store all files/objects that are generated by the build system. '''make''' is always executed in the build directory or a sub-directory of the build directory. Each make ''recipe'' results in at least one such file or object.
Line 15: Line 16:
  
 
==Generating documentation==
 
==Generating documentation==
−
 
 
For the GnuCash documentation, the make command ''must'' be used with a ''target'' argument which determines which type(s) of the documentation are built. E.g. '''make html''' builds the html files which allow the documentation to be viewed in a web browser. (If no target is specified, make does nothing because the xml files are both the source and the target which yelp needs to display the documentation.)
 
For the GnuCash documentation, the make command ''must'' be used with a ''target'' argument which determines which type(s) of the documentation are built. E.g. '''make html''' builds the html files which allow the documentation to be viewed in a web browser. (If no target is specified, make does nothing because the xml files are both the source and the target which yelp needs to display the documentation.)
  
−
There are a few differences in how to use '''make''' depending on [https://wiki.gnucash.org/wiki/Initializing_Documentation_Build_Environment the build system] you have chosen - autotools or cmake. Both systems provide a common set of high-level targets. Those are the targets you can invoke directly in the top level build directory:<SyntaxHighlight lang="sh">
+
There are a few differences in how to use '''make''' depending on [[Initializing_Documentation_Build_Environment]] you have chosen - ''obsolete'' <tt>autotools</tt> or ''current'' <tt>cmake</tt>. Both systems provide a common set of high-level targets. Those are the targets you can invoke directly in the top level build directory:<SyntaxHighlight lang="sh">
 
make check                # use xmllint to validate xml files
 
make check                # use xmllint to validate xml files
 
make html                # generates all documentation in html format
 
make html                # generates all documentation in html format
Line 25: Line 25:
 
make epub                # generates all documentation in epub format
 
make epub                # generates all documentation in epub format
 
</SyntaxHighlight>
 
</SyntaxHighlight>
−
Each of these commands will generate all documentation (help and guide) in all available languages and in the requested format.
+
Each of these commands will generate all documents (manual and guide) in all available languages and in the requested format.
  
 
Note there are additional installation dependencies required for building the pdf and mobi formats.
 
Note there are additional installation dependencies required for building the pdf and mobi formats.
−
See [https://wiki.gnucash.org/wiki/Documentation_Release_Process#Other_documentation_formats].
+
See [[Documentation_Release_Process#Other_documentation_formats]].
  
 
As it can take quite some time to build all the  documentation the build system also provides ways to build only parts
 
As it can take quite some time to build all the  documentation the build system also provides ways to build only parts
−
of the documentation. How to do that differs between the two supported build systems:
+
of the documentation. How to do that depends on the build system:
  
−
===Autotools===
+
===Cmake===
−
 
+
In the case of cmake all make commands have to be executed in the ''top-level'' '''build directory'''.<ref>Before with autotools one could use the same targets explained above in subdirectories as well to build only part of the documentation. Some examples:<SyntaxHighlight lang="sh">
−
With autotools one could use the same targets explained above in subdirectories as well to build only part of the documentation. Some examples:<SyntaxHighlight lang="sh">
 
 
(cd guide && make html)  # generates the Concepts and Tutorial guide in all supported languages in html format
 
(cd guide && make html)  # generates the Concepts and Tutorial guide in all supported languages in html format
−
(cd help/de && make pdf) # generates the help document in German in pdf format
+
(cd help/de && make pdf) # generates the manual in German in pdf format
 
</SyntaxHighlight>
 
</SyntaxHighlight>
−
 
+
;Note: In the times of autotools support the order of component and language was inverted and the manual was named <q>help</q>.</ref>
−
===Cmake===
+
To allow to '''build only parts''' of the documentation, cmake offers additional targets of the forms
−
 
+
:;<language>-<component>-<target>
−
In the case of cmake all make commands have to be executed in the top-level build directory. To allow to build only parts of the
+
::generate ''target'' for ''component'' {manual|guide} in ''language''.
−
documentation, cmake offers additional targets of the forms
+
:;<component>-<target>
−
 
+
::generate ''target'' for ''component'' in all supported languages.
−
<code><language>-<document-name>-<target>
 
−
<document-name>-<target></code>
 
−
 
 
−
The first format will generate ''target'' for ''document-name'' in ''language''.
 
−
The second format will generate ''target'' for ''document-name'' in all supported languages.
 
−
 
 
 
Some examples will make this clearer:<SyntaxHighlight lang="sh">
 
Some examples will make this clearer:<SyntaxHighlight lang="sh">
−
make C-gnucash-guide-html  # generates the Concepts and Tutorial guide in English in html format
+
make C-gnucash-guide-html  # generates the english Tutorial and Concepts guide in html format
−
make de-gnucash-help-pdf  # generates the help document in German in pdf format
+
make de-gnucash-manual-pdf  # generates the german manual in pdf format
−
make gnucash-help-check    # run a xmllint check on all the help documents in all supported languages
+
make gnucash-manual-check    # run the xmllint check on the manual in all supported languages
 
</SyntaxHighlight>
 
</SyntaxHighlight>
  
−
A full list of available targets can be retrieved with<SyntaxHighlight lang="sh">
+
A full list of available targets can be retrieved with <SyntaxHighlight lang="sh">
 
make help
 
make help
 
</SyntaxHighlight>
 
</SyntaxHighlight>
Line 68: Line 61:
  
 
===Installing make===
 
===Installing make===
−
 
 
;Linux: <code>make</code> is usually already installed as part of the default installation packages.
 
;Linux: <code>make</code> is usually already installed as part of the default installation packages.
−
;macOS: <code>make</code> and <code>git</code> are provided by either Xcode or the Xcode '''command-line tools'''. To update the documentation, it is not necessary to install the full Xcode package which is currently a download of over 4 GBs. On OS X 10.8 and later the system should offer to install just the '''command line tools''' when you issue a command that they supply; <tt>make</tt> or <tt>git</tt> issued in Terminal should do it. If that doesn't work try <tt>xcode-select --install</tt>; if that also fails you'll need to download the appropriate command-line tools package from [https://developer.apple.com/download/more/ Apple\'s developer website] where you'll need to sign in with your Apple ID and agree to some terms and conditions if you haven't already set up a developer account.
+
;{{mac}}: <code>make</code> and <code>git</code> are provided by either <tt>Xcode</tt> or the <tt>Xcode command-line tools</tt>. To update the documentation, it is not necessary to install the full Xcode package which is currently a download of over 4 GBs.
 +
:;On OS X 10.8 and later: the system should offer to install just the '''command line tools''' when you issue a command that they supply; <SyntaxHighlight lang="sh">make
 +
# or
 +
git</SyntaxHighlight> issued in Terminal should do it. If that doesn't work try <SyntaxHighlight lang="sh">
 +
xcode-select --install
 +
</SyntaxHighlight> If that also fails you'll need to download the appropriate command-line tools package from [https://developer.apple.com/download/more/ Apple's developer website] where you'll need to sign in with your Apple ID and agree to some terms and conditions if you haven't already set up a developer account.
 
;Windows: It is probably possible but complicated to update the documentation in Windows. [[Building_on_Windows|Building on Windows]] may help. It may be easier to install Linux in a virtual machine like VirtualBox instead.
 
;Windows: It is probably possible but complicated to update the documentation in Windows. [[Building_on_Windows|Building on Windows]] may help. It may be easier to install Linux in a virtual machine like VirtualBox instead.
−
 
+
----
−
[[Category:Documentation Development]]
 

Latest revision as of 13:10, 26 April 2023

The make utility is a tool which controls the generation of non-source files of a project from it's source files. In GnuCash it is used for the generation of the documentation and partially the website.

The Make Utility

In the make build system there are three important directories:

  • the source directory
  • the build directory
  • the installation directory (which can also be more than one directory all under a special directory called the prefix-directory)

The source directory is where your source files are. I.e. gnucash-docs —your local clone of our github repository— with all its subdirectories. If you want to make changes to the documentation source, you do this in the source directory structure, not the build directory structure.

The build directory is a directory used by the build system to store all files/objects that are generated by the build system. make is always executed in the build directory or a sub-directory of the build directory. Each make recipe results in at least one such file or object.

The installation directory is the location where the generated objects should finally end up when using make install.

Generating documentation

For the GnuCash documentation, the make command must be used with a target argument which determines which type(s) of the documentation are built. E.g. make html builds the html files which allow the documentation to be viewed in a web browser. (If no target is specified, make does nothing because the xml files are both the source and the target which yelp needs to display the documentation.)

There are a few differences in how to use make depending on Initializing_Documentation_Build_Environment you have chosen - obsolete autotools or current cmake. Both systems provide a common set of high-level targets. Those are the targets you can invoke directly in the top level build directory:
make check                # use xmllint to validate xml files
make html                 # generates all documentation in html format
make pdf                  # generates all documentation in pdf format
make mobi                 # generates all documentation in mobi format
make epub                 # generates all documentation in epub format

Each of these commands will generate all documents (manual and guide) in all available languages and in the requested format.

Note there are additional installation dependencies required for building the pdf and mobi formats. See Documentation_Release_Process#Other_documentation_formats.

As it can take quite some time to build all the documentation the build system also provides ways to build only parts of the documentation. How to do that depends on the build system:

Cmake

In the case of cmake all make commands have to be executed in the top-level build directory.[1] To allow to build only parts of the documentation, cmake offers additional targets of the forms

<language>-<component>-<target>
generate target for component {manual|guide} in language.
<component>-<target>
generate target for component in all supported languages.
Some examples will make this clearer:
make C-gnucash-guide-html  # generates the english Tutorial and Concepts guide in html format
make de-gnucash-manual-pdf   # generates the german manual in pdf format
make gnucash-manual-check    # run the xmllint check on the manual in all supported languages
A full list of available targets can be retrieved with 
make help

Installing documentation

To install the built documentation where it can be used for testing the interaction with GnuCash programs: 
make install
Note
See Test Documentation in Linux.

Installing make

Linux
make is usually already installed as part of the default installation packages.
macOS
make and git are provided by either Xcode or the Xcode command-line tools. To update the documentation, it is not necessary to install the full Xcode package which is currently a download of over 4 GBs.
On OS X 10.8 and later
the system should offer to install just the command line tools when you issue a command that they supply; 
make
# or
git
issued in Terminal should do it. If that doesn't work try 
xcode-select --install
If that also fails you'll need to download the appropriate command-line tools package from Apple's developer website where you'll need to sign in with your Apple ID and agree to some terms and conditions if you haven't already set up a developer account.
Windows
It is probably possible but complicated to update the documentation in Windows. Building on Windows may help. It may be easier to install Linux in a virtual machine like VirtualBox instead.
  1. ↑ Before with autotools one could use the same targets explained above in subdirectories as well to build only part of the documentation. Some examples:
    (cd guide && make html)  # generates the Concepts and Tutorial guide in all supported languages in html format
(cd help/de && make pdf) # generates the manual in German in pdf format
    Note
    In the times of autotools support the order of component and language was inverted and the manual was named help.
Retrieved from "https://wiki.gnucash.org/wiki/index.php?title=The_Make_Utility&oldid=21672"