Use Module for D
This module provides functions for D to complement core CMake functions.
add_d_conditions(
[TARGETS <target1> [<target2> ...] ]
[VERSION <ident1> [<ident2> ...] ]
[DEBUG <ident1> [<ident2> ...] ]
)
This command adds the specified identifiers to D’s version/debug flags. These are used to control conditional compilation similar to (but distinct from) C’s -Dfoo=bar flags. If any targets are specified, the identifiers will only be added for those targets. Otherwise, they follow usual CMake scope rules.
These conditions are added to COMPILE_OPTIONS for targets or COMPILE_OPTIONS if no target is specified. This allows an executable target to link to a library target that required version flags, with the executable automatically picking up the version flags so that the D compiler can generate code correctly.
add_d_unittests(<unittest_target>
TARGET <target>
[PARAMETERS <param_string1> [<param_string2> ...] ]
[SOURCES <extra_source1> [<extra_source2> ...] ]
)
Adds a unittest target. The executable target will be named <unittest_target>, so that you can add additional flags or link libraries to it as needed.
The set of sources, flags and libraries used for <unittest_target> is determined by those on the provided <target>. At least two test targets are added, called <unittest_target>_build and <unittest_target>_run, which build and run the target respectively.
By providing strings to PARAMETERS, you can specify that the <unittest_target> should be run with said flags. Each set of flags must be its own string, so if you want multiple flags on a single test call, you need to write them as follows:
add_d_unittests(test_example
TARGET example
PARAMETERS
"--run-test 1 --quiet"
"--run-test 2 --quiet"
"--run-test 3 --quiet"
)
This will produce three tests which call test_example, once for each of the sets of parameters. Without the double-quotes, this would be interpreted as 9 tests which call test_example.
All test running targets are name <unittest_target>_run_<num> where <num> is an integer that begins at zero, and increments for each test added within this command. No attempt to pad the number with leading zeroes is made.
SOURCES allows you to specify additional source files needed to build <unittest_target>, if any. You may instead wish to add a library containing these sources, and link <unittest_target> to it using target_link_libraries().
Note: the executable target will be generated as long as this function is called, but the test targets will only be enabled if testing is enabled (for example, by calling enable_testing()). Tests will also not be generated when cross compiling.
add_ddoc(<doc_target>
TARGETS <target> [<target2> ...]
[EXCLUDE_FROM_ALL]
[OUTPUT_DIRECTORY <dir>]
[PACKAGE_SEPARATOR <sep>]
[MACROS <macro_file1> [<macro_file2> ...] ]
[ASSETS <asset_file1> [<asset_file2> ...] ]
[SOURCES <extra_source1> [<extra_source2> ...] ]
[VERSION <ident1> [<ident2> ...] ]
[EXCLUDE_SOURCES <source1> [<source2> ...] ]
[EXCLUDE_MODULES <regex>]
)
Adds a Ddoc generating target (named <doc_target>) for the specified targets. Compiler parameters and initial source list are derived from <target>. A Ddoc file containing a MODULES macro is automatically generated and used based on the modules include in the target.
Additional targets, if specified, will be generated as part of the same documentation target. That is, all D modules from each listed target will be included in the same generated MODULES macro file. from the default target.
By default, add_ddoc adds <doc_target> to the default build. This can be prevented by specifying EXCLUDE_FROM_ALL. Note that if EXCLUDE_FROM_ALL is set, the documentation cannot be installed. It is recommended to configure this such that it is an option for the user whether or not to generate (and install) documentation.
The output directory can be specified via OUTPUT_DIRECTORY. The default output directory, if that parameter is omitted, is ${PROJECT_BINARY_DIR}/ddoc.
The separator used in the names of the generated files can be specified via PACKAGE_SEPARATOR. If left unspecified, it defaults to a period. For example, given a module pkg.sub.mod (in file pkg/sub/mod.d), The default is to generate a pkg.sub.mod.html file. Providing a PACKAGE_SEPARATOR of “/” would put the same file in pkg/sub/mod.html. This also determines the names used in the generated MODULES macro file. This should be set to the same thing your other Ddoc macros expect.
With the MACROS flag, additional macro files can be specified to define more macros. This is useful, for instance, to generate Ddoc using bootDoc: simply point to the bootdoc.ddoc and settings.ddoc files. These files must have an extension of “ddoc”. Remember that a macro file containing a definition of MODULES is automatically generated and used.
Asset files and directories can be specified via ASSETS. The files will be copied to the OUTPUT_DIRECTORY as is, from where they can be installed easily. These files can then be used by the generated Ddoc. For instance, you might add JavaScript, CSS and images with this.
If needed, additional sources may be processed alongside the targets’ sources by providing the SOURCES argument. This is primarily useful if you have a D source that only contains documentation, and that you do not include in any of your targets’ sources. These sources will take on the same flags as the first specified target.
Additional conditional compilation flags may be passed to via VERSION. This works by calling add_d_conditions(VERSION ...), and thus will apply to every D compiler call by add_ddoc.
If desired, modules can be excluded from Ddoc generation, either by giving sources manually to EXCLUDE_SOURCES, or a regular expression against module names provided to EXCLUDE_MODULES. The module names here are the canonical form before the separator is modified.
add_d_headers(
TARGETS <target> [<target2> ...]
[OUTPUT_DIRECTORY <dir>]
)
Adds rules responsible for generating D headers from the sources of all the specified targets. These rules are added to the targets themselves as a post-build step. When using this, remember that this is not always a bug-free process. For instance, DMD v2.065 does not properly handle “auto” functions, instead dropping the return type all together. Older versions of D will leave implementations intact. These are also not appropriate for documentation, as all comments are stripped. Use add_ddoc for creating documentation.
The output directory can be specified via OUTPUT_DIRECTORY. If not specified, it defaults to ${PROJECT_BINARY_DIR}/import.
d_enforce_property(
[TARGETS <target1> [<target2> ...] ]
)
Instructs the D compiler to enforce D’s property semantics. This is (currently) disabled by default in D, and makes it so that methods annotated with @property are the only methods that can be used as properties.
As with add_d_conditions, this appends to COMPILE_OPTIONS for targets and COMPILE_OPTIONS if no targets are specified. As such, linking to a library target that uses property enforcement will automatically instruct the linking target to also use property enforcement.
This may cause compilation to fail on versions of D older than 2.057, due to a bug in Phobos, D’s standard library.