[GNC-dev] CMake build system for gnucash-docs

[Geert Janssens]

I forgot to mention  the new cmake build system for gnucash-docs even works 
with ninja on Windows though it doesn't seem to affect build times much.

Geert


Op zaterdag 7 september 2019 15:42:37 CEST schreef Geert Janssens:
> With my last set of commits I believe the CMake build system for
> gnucash-docs now matches the autotools build system (modulo the
> scrollkeeper info that's not used by gnome's help system any more).
> 
> To use it:
> - clone gnucash-docs and check out the maint branch
> - make a build directory somewhere and cd into it
> - run:
>   cmake -DCMAKE_INSTALL_PREFIX=<path-to-install-location> \
>         <path-to-checked-out-source-dir>
> 
> That configures the build system. Note you can leave out the
> CMAKE_INSTALL_PREFIX if you don't intend to install the documentation. It's
> normally not needed unless you are a software packager as the build will
> replicate the installation locations in the build directory.
> 
> On all platforms except Windows the build system will enable these document
> formats by default:
> * html: a set of html documents (used by the gnucash website)
> * epub
> * pdf
> * ghelp: the documentation format and installation locations for use with
>          the gnome help system
> On Windows, by default only the chm format is enabled (the Windows native
> help format).
> 
> You can control which formats to enable/disable by setting the following
> flags on the cmake command line:
> -DWITH_HTML
> -DWITH_EPUB
> -DWITH_MOBI
> -DWITH_PDF
> -DWITH_GHELP
> -DWITH_CHM
> 
> For example
>  cmake -DWITH_PDF=OFF -DWITH_MOBI=ON <path-to-checked-out-source-dir>
> will configure the build system without pdf support and with mobipocket
> support.
> 
> Acutally generating the documentation involves running "make" or "ninja" (if
> you had passed "-G Ninja" to the cmake command).
> There is no default target, which means just running "make" or "ninja" will
> do nothing.
> 
> Instead you have to specify which document to build in which language and
> which document format. There are more generic targets to build a document in
> a given format for all languages and even more generic targets to build all
> documents in all languages in a specific document format as well.
> 
> To see all available targets, the easiest is to run
>   make help (or ninja-help)
> 
> A few examples
> * to build the gnucash guide as html in German
>   make de-gnucash-guide-html
> 
> * to build all help documentation in pdf
>   make gnucash-help-pdf
> 
> * to build all documentation in epub
>   make epub
> 
> There is also a check target (and the subtargets <document>-check and
> <lang>- <document>-check) to run xmllint on the source files.
> 
> Specifically for document writers working on linux, the ghelp target (or one
> of the subtargets <document>-ghelp and <lang>-<document>-ghelp) will come
> in handy: these targets will install the document sources in the build
> directory in paths that can be used to test the documentation with yelp.
> More specifically, the documentation will be installed under
> <builddir>/share/gnome/help/<docname>/<lang>/
> 
> By adding <builddir>/share to the XDG_DATA_DIRS environment variable yelp
> will pick up the copy of the documentation that's installed there. For
> example to open your version of the German language gnucash-help on the
> command line:
> 
> LANG=de XDG_DATA_DIRS=<builddir>/share:$XDG_DATA_DIRS yelp
> ghelp:gnucash-help
> 
> A few other targets that are less relevant unless you're a packager:
> * install: this is only implemented for ghelp (to be included in linux
> distribution packages) and chm (to be included in the Windows installer).
> Note if both the ghelp and the chm targets are configured, install will
> install both. This can be avoided by setting environment variable
> "CMAKE_INSTALL_COMPONENT" to one of "ghelp" or "chm". As the chm and ghelp
> targets are normally not enabled together by default this is usually not
> necessary.
> * uninstall: does the opposite of install
> * dist, distcheck: two targets for the release manager
> 
> Please test and give feedback.
> 
> Regards,
> 
> Geert
>