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

[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

Op maandag 2 september 2019 19:29:00 CEST schreef Geert Janssens:
> Over the weekend I spent a few cycles to port the gnucash-docs autotools
> build system to cmake.
> 
> Most of it is done and can be played with by checking out the current maint
> branch on gnucash-docs.
> The main missing elements are:
> - generating the Windows specific chm files
> - uninstall rules
> - omf/scrollkeeper/rarian support
> 
> The last one is easy: I don't intend to add this. It was there because old
> versions of yelp (<2.23) required it. No platform we care about still uses
> that old yelp version so omf is obsolete.
> 
> The other two will follow hopefully somewhere next week.
> 
> Other than that there are a few important changes between the autotools
> system and the cmake system. The most important one is that autotools
> provided a fully self-contained Makefile in each document directory. Cmake
> on the other hand works with a single top-level makefile (or ninja ruleset
> if you prefer).
> 
> That is, with autotools you could
> cd guide/C
> make html
> And that would build you the html version of the English guide
> 
> This is not possible in cmake. However I have tried to provide equivalent
> targets instead wherever possible. So to achieve the above you can instead
> do make C-gnucash-guide-html
> 
> The targets are always named
> <language>-<document>-<type>
> 
> So similarly you will find
> de-gnucash-help-pdf
> pt-gnucash-help-epub
> ja-gnucash-guide-mobi
> 
> and so on.
> 
> Entering
> make help
> will provide a list of available targets to choose from.
> 
> This gets even more complicated when attempting to install. There is only
> one global install target (inherit to cmake). However one can restrict what
> to install by setting environment variable CMAKE_INSTALL_COMPONENT to one
> of the targets mentioned above (at least one for which install is
> implemented/makes sense). So for example
> 
> CMAKE_INSTALL_COMPONENT=C-gnucash-guide-html make install
> 
> That will only install the English guide in html format. Currently this will
> work for xml and html targets. The pdf, epub and mobi targets don't have
> install rules. And I'm even considering dropping them for html. It doesn't
> make much sense to have an install rule for html as it's not something a
> packager will want to install on their system. They should use the xml
> target instead.
> 
> The last tidbit I'm still considering for improvement is to replicate the
> install paths in the build directory, much like we do for the gnucash build
> system as well. That is, instead of storing the pdf file in
> <builddir>/guide/C
> store it in
> <builddir>/share/gnucash-docs/C
> 
> There are a few additional notes in https://github.com/Gnucash/gnucash-docs/
> blob/maint/CMakeNotes.txt
> 
> Feedback is welcome.
> 
> Regards,
> 
> Geert
> 
> 
> _______________________________________________
> gnucash-devel mailing list
> gnucash-devel at gnucash.org
> https://lists.gnucash.org/mailman/listinfo/gnucash-devel