[feature] Enable or disable doxygen during build phase

[oceanofthelost]

A new option, ENABLE_BUILDING_DOCS, is added to cmake and defaults ON to preserve legacy behavior. Using ccmake, ENABLE_BUILDING_DOCS can be toggled ON or OFF allowing document generation only when needed.

Issue accomplishes one of the tasks in Issue #29.

[jtxa]

I though about prefixing every switch with SRecord_.
rationale: srecord itself is an LGPL3 library, which probably someone wants to integrate via CMake's FetchContent.
For that case it's better to have unique names. Better do a clean naming now, than rename everything in a few years.
I should do my planned CMake changes next to close that issue.

[jtxa]

As the CMake files are brand new, I want to ask the question, if the default ON is worth to keep.
My idea was, to dis/enable those documentations by default, for which the tooling is found (doxygen, website, PDF, ...).
And only if the user sets the switch, he can control the behavior explicitly.
The major question is, what should be the developer experience if not all tools are installed: Automatic configuration of what's possible or forcing either to install the doc tools or disable doc building manually?
What do you guys think?

[oceanofthelost]

I though about prefixing every switch with SRecord_. rationale: srecord itself is an LGPL3 library, which probably someone wants to integrate via CMake's FetchContent. For that case it's better to have unique names. Better do a clean naming now, than rename everything in a few years. I should do my planned CMake changes next to close that issue.

Will make this change, I did a survey of some other projects (primarily LLVM & Clang) and will use the naming convention SRECORD_ENABLE_XXX as this follows standard practice for module variable names and CMake variable naming practice (all caps).

[oceanofthelost]

I am for disabling documentation generation during debug build. I find for projects I work with I use debug when iterating a design and use release when finished and need the documentation.

• Set ENABLE_BUILDING_DOCS to default to OFF

I think it would be within cope to add a release and debug build option to this PR. I would base the builds off Professional CMAKE, Chapter 13.1.1. Single Configuration Generators. This would then allow having support for multiple build configurations in a separate directory.

[jtxa]

A question: do you really want to disable the documentation, or is it enough to remove the ALL for your use case?
How about such a default: the documentation targets are added if the tools are available, and only for Release build automatically by ALL.
If the User defines the ENABLE var, then either disable docs completely or REQUIRE it for all configuration and add it to ALL.
P.S. At the moment there is a hard-coded RELEASE in the top level file, that's also one of the topics which needs to be improved.

[jtxa]

Will make this change, I did a survey of some other projects (primarily LLVM & Clang) and will use the naming convention SRECORD_ENABLE_XXX as this follows standard practice for module variable names and CMake variable naming practice (all caps).

That's a common, but an old naming practice of CMake 2.x.
Modules shall use a prefix, that is written exactly as their name. See the manual for details, which was introduced with 3.0. The wording has been clarified in 3.20, like "must match exactly", co-authored by Craig.

For me it's like this:
The official tool name is SRecord (inside the docs). That's why I would prefer a project(SRecord ...), which automatically gives us variables like SRecord_VERSION, SRecord_SOURCE_DIR, ...
So it would be consistent to use SRecord_ENABLE_XXX

[oceanofthelost]

A question: do you really want to disable the documentation, or is it enough to remove the ALL for your use case? How about such a default: the documentation targets are added if the tools are available, and only for Release build automatically by ALL. If the User defines the ENABLE var, then either disable docs completely or REQUIRE it for all configuration and add it to ALL. P.S. At the moment there is a hard-coded RELEASE in the top level file, that's also one of the topics which needs to be improved.

Latest commit addresses this the behavior change. I created an internal variable in CMake, and am looking to see if this is the right way to accomplish what we want. Open to suggestions.

[sierrafoxtrot]

Will make this change, I did a survey of some other projects (primarily LLVM & Clang) and will use the naming convention SRECORD_ENABLE_XXX as this follows standard practice for module variable names and CMake variable naming practice (all caps).

That's a common, but an old naming practice of CMake 2.x. Modules shall use a prefix, that is written exactly as their name. See the manual for details, which was introduced with 3.0. The wording has been clarified in 3.20, like "must match exactly", co-authored by Craig.

For me it's like this: The official tool name is SRecord (inside the docs). That's why I would prefer a project(SRecord ...), which automatically gives us variables like SRecord_VERSION, SRecord_SOURCE_DIR, ... So it would be consistent to use SRecord_ENABLE_XXX

SRecord has always been the standard capitalisation so I agree. However, I can't ignore that it does look a little clunky. Should we consider all-caps to give SRECORD_ENABLE_XXX style variables? Is this more in keeping with other projects. I'd need to check if this has any side effects such as generated filenames but still. Thoughts gents?

[oceanofthelost]

Another option, which I feel is a nice middle ground, would be the following:

option(${PROJECT_NAME}_ENABLE_DOCUMENTATION "Enable building documentation" ON)

Here all options for SRecord would be based upon ${PROJECT_NAME}, which will evaluate to the project name in:

project(SRecord
        VERSION 1.65
        LANGUAGES C CXX
)

[jtxa]

I try to explain my rationale, which might be unnecessarily complex:
If you just want to build the software, in fact, it doesn't matter. Many projects just have a ENABLE_DOCUMENTATION. And that's totally OK.

But it's also library. And I see two ways to use it nowadays (AFAIK):

1. Create library with a corresponding Config Module. That should have a consistent naming between Module name and variables, just as the referenced CMake documentation says.
2. Use the repo directly via add_submodule, e.g. with the help of FetchContent or CPM.

As the module file in 1. needs to be generated by us, it can use any prefix, even different from the project. In fact, I believe we may not need to add any extra variables there on our own. Perhaps some like: gcrypt was used for the compiled library or not.
As the config module just provides the library (not the whole project or executables) it could also be perhaps libsrecord with variable names like this libsrecord_VERSION. The usage by project looks like this: find_package(libsrecord CONFIG)

For 2. we definitely need a prefix. And for consistency with 1. I suggest the same naming.

You might decide on naming later, when 1. or 2. is really supported. I did the suggestion now, to avoid naming changes. Until now, only ArchLinux seems to use the new version (see Repoolgy).

I'm no user if CMake aware libraries myself (on my job), but I can ask those questions on CMake's discourse and hope for some experts to answer.