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

[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