CMake Addressing

From GnuCash
Revision as of 04:06, 3 November 2018 by Fell (talk | contribs) (fix link appearance)
(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)
Jump to: navigation, search

The cmake command sytax most relevant for building Gnucash is

cmake [<options>] <path-to-source>

More detailed information on CMake can be obtained from the Cmake documentation.

The <options> switches relevant to building GnuCash are detailed in build options. As well, other cmake switches are discussed in the CMake documentation linked above, but these are not generally needed to build GnuCash.

CMake does not allow in source builds, i.e. where the compiled files and Makefiles are built within the source tree structure, for projects building using CMake. It requires a separate build directory in which files generated by the build are placed. CMake generates files for the autotools make program (and other build systems e.g. Ninja). This simplifies rebuilding as the contents of the build directory can simply be deleted and rebuilt and the contents of the source directory are not altered by the cmake and build process.

The build directory can be located as desired within the users directory structure and there are no restrictions on the name of the directory. Only the build directory needs to be retained if you subsequently want to uninstall the version of GnuCash you have built using the make uninstall command as the install_manifest.txt file and the Makefiles used to uninstall Gnucash are located within the build directory. For this reason it is probably wise to label the build directory with the application name and version if you place the build directory outside the source directory structure. E.g. "build-gnucash-3.x" to distinguish it from other applications/projects built with CMake.

If you, as a practice, retain the sources of applications you build on your system, then you could locate the build directory within the top level source directory. If you download the tarball this will have a name like "gnucash-3.x". If you use git clone to obtain the sources from the GnuCash page on githubthe top level source directory will be named "gnucash". Another gnucash directory also exists under this top level directory named "gnucash-3.x" (or "gnucash") - be careful do not reference this sub-directory instead of the top level directory in any of the following or as the <path-to-source> of the cmake command.

Note:- x is one of {0, 1, 2,...}, i.e. the minor version number which should be substituted for <x> in any commands.

Note:- Problems have been experienced when the build directory was located under the top level source directory(gnucash-3.<x> for the intltools library used in the GnuCash documentation but not currently in the GnuCash program.

The <path-to-source>, i.e. to the "gnucash-3.x" or "gnucash" top level directory in the cmake command can be either:

  • an absolute path to this directory; or it may be
  • a relative path from the build directory to the "gnucash-3.0" or "gnucash" directory which contains the top levelCMakeLists.txt file.

Three possible scenarios are illustrated below:

Sources in Downloads and Build directory in another user directory ApplicationBuilds in User's home directory

                         $HOME                                                               
                           |                                                                                            
      -------------------------------------------------... 
      |                                            |                                                    
  Downloads                                  ApplicationBuilds                                                        
      |                                            |                                                  
  gnucash-3.x                                build-gnucash-3.x                                             
      |
     ---------------------
    |                     |
  CMakeLists.txt     rest of sources                                                                                     
                                                                             
                                                                        

Relative ../../Downloads/gnucash-3.x

Absolute $HOME/Downloads/gnucash-3.x


Sources and build directory in the same parent directory ApplicationBuilds

                          $HOME
                            |
                    ApplicationBuilds
                            |
                  ---------------------- 
                 |                     |
            gnucash-3.x       build-gnucash-3.x
                 | 
        -------------------
        |                 |
    CMakeLists.txt    rest-of-sources

Relative ../gnucash-3.x

Absolute $HOME/APPlicationBuilds/gnucash-3.x


Build directory in the top level Sources directory under a parent ApplicationBuilds directory

                           $HOME
                             |
                     ApplicationBuilds
                             |
                        gnucash-3.x
                             |
            -------------------------------------
            |                  |                 |
     CMakeLists.txt    rest-of-sources      build-gnucash-3.x

Relative' .. or../

Absolute $HOME/ApplicationBuilds/gnucash-3.x