JEGP CMake Modules

CMake modules that abstract common functionality in the JEGP libraries.

Variables

This repository reserves CMake identifiers and filenames in binary directories that begin with JEGP_ and _JEGP_ regardless of case or equal to the name of a JEGP CMake module.

Variables that Change Behavior

• JEGP_CPPFRONT_INCLUDE_DIRECTORIES: List of preprocessor include file search directories for Cpp1 source files generated by cppfront.

• JEGP_CPPFRONT_BUILD_DIR: Diretory where cppfront generates sources.

• JEGP_CXX_HEADER_FILE_EXTENSIONS: List of extensions for C++ header files.

• JEGP_CXX_MODULES_BINARY_PARENT_DIR: Parent binary directory of the modules built for the current configuration. Currently required to enable use of imported modules.

• JEGP_CXX_MODULES_SYSTEM_CACHE: Cache path of the system's C++ modules.

• JEGP_CXX2_COMPILER: The full path to the compiler for Cpp2.

• JEGP_<PROJECT-NAME>_NAME_PREFIX: Prefix of names added by some of these modules. When not defined, ${PROJECT_NAME}_ is prefixed. Base name refers to the unprefixed added name.

• JEGP_STANDARDESE_SOURCES_GIT_REPOSITORY, JEGP_STANDARDESE_SOURCES_GIT_TAG: Default to values corresponding to https://github.com/JohelEGP/draft/tree/standardese_sources_base.

Variables for Languages

• JEGP_CXX2_FLAGS: Cpp2 flags. The semantics are those of CMAKE_<LANG>_FLAGS.

Modules

Documentations Modules

JEGPAddStandardeseSources

This module defines the following function.

jegp_add_standardese_sources(<name>
                             [EXCLUDE_FROM_ALL]
                             LIBRARIES <source>...
                             [APPENDICES <source>...]
                             [EXTENSIONS <source>...]
                             [CHECKED <condition>]
                             [PDF
                              [EXCLUDE_FROM_MAIN]
                              PATH <pdf_path>]
                             [HTML
                              [EXCLUDE_FROM_MAIN]
                              PATH <html_path>
                              [SECTION_FILE_STYLE <sectionfilestyle>]
                              [LATEX_REGEX_REPLACE [<match-regex> <replace-expr>]...]
                              [HTML_REGEX_REPLACE [<match-regex> <replace-expr>]...]])

This function adds the external project <name>. <name> processes, as specified below, all given <source>, which are stems existing in ${CMAKE_CURRENT_SOURCE_DIR}. If <pdf_path> or <html_path> is specified, from the processed sources, <name> respectively

• outputs C++ Working Draft-like PDF or HTML documentations, and
• adds step target <name>-pdf or <name>-html that drives the output.

The C++ Standard Draft Sources has scripts to check the input sources and output of building the PDF. The <condition> defaults to FALSE and determines, via if, whether the scripts are used.

EXCLUDE_FROM_ALL specifies the argument of the EXCLUDE_FROM_ALL keyword to <name>. EXCLUDE_FROM_MAIN specifies the argument of the EXCLUDE_FROM_MAIN keyword to the respective step target.

When specifying the HTML keyword, the variable JEGP_CXXDRAFT_HTMLGEN_GIT_REPOSITORY should be set to a local checkout of https://github.com/JohelEGP/cxxdraft-htmlgen/tree/standardese_sources_base (or https://github.com/Eelis/cxxdraft-htmlgen if modules aren't indexed). The stack commands will be used in that checkout. The <sectionfilestyle> is forwarded to cxxdraft-htmlgen.

Process

<name> configures C++ Standard Draft Sources via the patched fork specified by the JEGP_STANDARDESE_SOURCES_GIT_REPOSITORY and JEGP_STANDARDESE_SOURCES_GIT_TAG variables.
Recommended practice: For faster processing, set the variable to a local shallow clone.

# 1a. Clone <https://github.com/JohelEGP/draft/>.
git clone "https://github.com/JohelEGP/draft/" --branch=standardese_sources_base
# 1b. Alternatively, shallow clone directly if this is a one-shot (e.g., in CI).
git clone "https://github.com/JohelEGP/draft/" --branch=standardese_sources_base standardese_sources_base --depth=1
# 1c. Alternatively, in an existing repository of `gh:cplusplus/draft`,
#    add the remote and checkout the branch.
git remote add JohelEGP "https://github.com/JohelEGP/draft/"
git checkout -b standardese_sources_base JohelEGP/standardese_sources_base
# 2. Do a shallow clone (after 1a and 1c).
git clone file://`pwd`/draft/ --branch=standardese_sources_base standardese_sources_base --depth=1
# 3. Configure with:
cmake ... -DJEGP_STANDARDESE_SOURCES_GIT_REPOSITORY=file://`pwd`/standardese_sources_base

All given <source> are copied to alongside a copy of the sources of the patched fork's clone. The copies of macros.tex and back.tex have the respective contents of macros_extensions.tex and bibliography.tex inserted if they are specified via the EXTENSIONS keyword. The copies of config.tex, preface.tex, std.tex, and check-source.sh have these variables substituted as if by configure_file's @ONLY mode.

Variable	Meaning
pdf_title	Title of the PDF.
page_license	License or copyright of the documentations.
first_library_chapter	Stable label of the first library chapter.
last_library_chapter	Stable label of the last library chapter.

Variable	Default string value
pdf_subject	${PROJECT_NAME}
pdf_creator	The user.name of Git's configuration.
document_number_header	Ref
document_number	\unspec
previous_document_number	\unspec
release_date	\today
reply_to_header	Reply at
reply_to	\url{${PROJECT_HOMEPAGE_URL}}
cover_title	${pdf_title}
cover_footer	Same as the C++ WD.
check_comment_alignment	false

The following variables apply to the HTML output.

HTML variables	Default string value
cover_footer_html	Same as the C++ WD.

Additionally, std.tex is configured to input all library and appendix <source> in the input order. check-source.sh is similarly configured for all library <source>.

After copying and configuring, if specified, the check script for the sources is run.

<name>-pdf builds the PDF. If successfully built and checked (if required), it is copied to <pdf_path> relative to ${CMAKE_CURRENT_BINARY_DIR}.

<name>-html builds the HTML. If successfully built, it is copied to <html_path> relative to ${CMAKE_CURRENT_BINARY_DIR}.

To build the HTML, the sources are copied back to ${CMAKE_CURRENT_SOURCE_DIR}/source.
Recommended practice: Add ${CMAKE_CURRENT_SOURCE_DIR}/source to .gitignore.

LATEX_REGEX_REPLACE and HTML_REGEX_REPLACE specify string(REGEX REPLACE) operations respectively applied to the LaTeX sources and HTML sources.
Recommended practice:

• Use when cxxdraft-htmlgen doesn't know how to transform a LaTeX construct to HTML.
• Be aware of how CMake lists work. Here are some tips for some use cases:
  • To match ;, use . if that suffices.
  • To replace with ;, use the html entity &#x003B instead.
  • To replace with [ and ] across arguments, respectively use &#x005B and &#x005D instead.

[ Example:

jegp_add_standardese_sources(
  name
  LIBRARIES "..."
  HTML PATH "..."
       # Transform the LaTeX command `\href` to HTML.
       LATEX_REGEX_REPLACE [[\\href{([^}]+)}{([^}]+)};HREF(\1)(\2)]]
       HTML_REGEX_REPLACE [[HREF\(([^)]+)\)\(([^)]+)\);<a href="\1">\2</a>]])

-- end example ]

C++ modules support

The linked forks include C++ modules support:

• Commands parallel to the header commands.
  • Indexing commands and accompanying \printindex in back.tex.

    % index for library modules
    \newcommand{\libmodule}[1]{\indexmdl{#1}\tcode{#1}}
    \newcommand{\indexmodule}[1]{\index[moduleindex]{\idxmdl{#1}|idxbfpage}}
    \newcommand{\libmoduledef}[1]{\indexmodule{#1}\tcode{#1}}
    \newcommand{\libmodulerefx}[2]{\libmodule{#1}\iref{#2}}

  • modularlibsumtab, like libsumtab.

Project Modules

JEGPAddModule

This module defines the following functions.

jegp_add_module(<name>
                [IMPORTABLE_HEADER]
                [SOURCES <source>...]
                [COMPILE_OPTIONS <option>...]
                [LINK_LIBRARIES <library>...])

This function adds the object library ${name}. The meaning of the keywords other than IMPORTABLE_HEADER are the same as for jegp_add_test, except that PRIVATE is not implied. At last, it calls jegp_cpp_module with ${name} and forwards IMPORTABLE_HEADER.

jegp_cpp_module(<target>
                [IMPORTABLE_HEADER |
                 MODULE_INTERFACE_UNIT <source>])

This function enables the object library ${target} to compile as a C++ module (default) or importable header (when IMPORTABLE_HEADER is specified).

Limitations

• The generally supported CMAKE_CXX_COMPILER_IDs are Clang and GNU. The keyword IMPORTABLE_HEADER is supported with GNU.
• The generally supported CMAKE_GENERATORs are Ninja and Unix Makefiles. Ninja + GNU CMAKE_CXX_COMPILER_ID is blocked on ninja-build/ninja#1962, and the dependency scanner does not work with Ninja.
• Only single source file modules are supported. At the call of jegp_cpp_module, either MODULE_INTERFACE_UNIT should be specified, or the target's SOURCES property must have only one C++ source outside a generator expression, whichever must represent its module interface unit.
• Bundled is a regex-based module dependency scanner. Because it runs as a deferred call in CMAKE_SOURCE_DIR, imported modules need to be visible in this directory. Because it is bundled in this CMake module, for dependent projects that do not use this CMake module to benefit from it, the config file must include this CMake module.
• No support for installing the added target.

JEGPTargetLinkHeaderUnits

This module defines the following function.

jegp_target_link_header_units(<target> <header>...)

This function specifies header units to use when linking ${target} and/or its dependents.

Limitations

Only supported for GNU as the CMAKE_CXX_COMPILER_ID. And then, only for system headers.

JEGPCpp2

This module defines the following functions.

jegp_cpp2_target(<target>)

This function enables the target to compile its Cpp2 source files.

The target's SOURCES property is inspected for Cpp2 source files. Corresponding Cpp1 source files are generated and added as sources to the target.

jegp_cpp2_target_sources()

target_sources for Cpp2 source files.

For each argument that is a Cpp2 source file, sets up the generation of its Cpp1 source file under CMAKE_CURRENT_BINARY_DIR, and replaces it with the generated Cpp1 source file before finally forwarding to target_sources.

JEGPProjectModules

This module includes all project modules.

Test Modules

JEGPHeadersTest

This module defines the following function.

jegp_add_headers_test(<target>...
                      [PRIVATE_REGEXES <regex>...])

This function enforces SF.11 on the public headers of the targets. The headers are determined from the INTERFACE_INCLUDE_DIRECTORIES property of the targets and the JEGP_CXX_HEADER_FILE_EXTENSIONS variable, excluding headers that match any PRIVATE_REGEXES.

A target T with base name headers_test is added. When T builds, the public headers are self-contained. Invocations that share T append headers to the build of T.

[ Example:

add_library(mylib src/a.cpp)
target_include_directories(mylib PUBLIC src/)
jegp_add_headers_test(mylib PRIVATE_REGEXES "detail/;external/")

-- end example ]

JEGPAddHeaderTest

This module is deprecated in favor of CMAKE_VERIFY_INTERFACE_HEADER_SETS.

This module defines the following function.

jegp_add_header_test()

This function enforces SF.11 for the public headers of the JEGP library ${PROJECT_NAME}. It adds an executable target that builds when the headers are self-contained. Otherwise, a build error should give a clue about the problematic headers.

The target's base name is test_headers. ${PROJECT_NAME} is a PRIVATE linked library of the target. The public headers of ${PROJECT_NAME} are those ending in .hpp in the directory ${${PROJECT_NAME}_SOURCE_DIR}/include.

JEGPAddTest

This module defines the following function.

jegp_add_test(<name>
              [TYPE {EXECUTABLE | OBJECT_LIBRARY}]
              [SOURCES <source>...]
              [COMPILE_OPTIONS <option>...]
              [LINK_LIBRARIES <library>...])

This function adds the target ${name}.

• TYPE specifies the type of the added target and defaults to EXECUTABLE.
  [ Note: An OBJECT_LIBRARY target effectively serves as compile-time test. -- end note ]
• SOURCES specifies its source files in ${CMAKE_CURRENT_SOURCE_DIR}. Defaults to ${name}.cpp.
• COMPILE_OPTIONS specifies its PRIVATE compile options.
• LINK_LIBRARIES specifies its PRIVATE linked libraries.

JEGPBuildError

This module defines the following function.

jegp_add_build_error(<name>
                     [AS {TEST | BUILD_CHECK}]
                     [TYPE {OBJECT_LIBRARY | EXECUTABLE}]
                     [SOURCE <source>]
                     [COMPILE_OPTIONS <option>...]
                     [LINK_LIBRARIES <library>...])

This function permits checking that building the source fails with specified error messages. The check is done as a test by default; it can also be done at build-time, according to AS. The meaning of the other keywords can be inferred from jegp_add_test, except that TYPE defaults to OBJECT_LIBRARY.

The error message specifiers are in the source in their expected order of appearance in the build output. They match the regex *// *error(-regex)?: *([^\n]*) *. The build output contains or matches \2 depending on whether \1 matched. A copy of the source without the error message specifiers is built for the check.

Note: AS BUILD_CHECK has the limitations of CMAKE_EXPORT_COMPILE_COMMANDS.

JEGPTestUtilities

This module includes all test modules.