CMake utility functions

Apart from the C++ and Wolfram Language APIs, LLU offers a range of CMake utility functions to automate common steps in building LibraryLink paclets with CMake. While it is not at all required to use CMake in a project that links to LLU, it is definitely convenient, as LLU is specifically tailored to be used by other CMake projects.

When you install LLU, a cmake directory is created in the installation directory, with the following contents:

.
└── cmake
    └── LLU
        ├── Wolfram
        │   ├── Common.cmake
        │   ├── CVSUtilities.cmake
        │   └── PacletUtilities.cmake
        ├── FindWolframLanguage.cmake
        ├── FindWolframLibrary.cmake
        ├── FindWSTP.cmake
        ├── LLUConfig.cmake
        ├── LLUConfigVersion.cmake
        └── LLUTargets.cmake

Most of these files are used internally by LLU or by CMake in order to get information about LLU installation when you link to it from your project. However, in the Wolfram subdirectory you will find two files (highlighted) with general purpose utilities which are documented below.

Tip

Check out the Demo paclet to see how some of these utilities can be used in a project.

Common

cmake/LLU/Wolfram/Common.cmake contains a number of small CMake functions and macros that automate common tasks when writing cross-platform CMake code. Not all of them will be useful in every project so feel free to choose whatever suits your needs.

set_machine_flags

Syntax:

set_machine_flags(<target>)

Depending on the machine architecture and operating system this function sets correct “machine flag” for given target:

• on Windows it sets /MACHINE:XX link flag

• on Linux and MacOS it sets -mXX flag for compilation and linking

Additionally, on 32-bit platforms it also defines MINT_32 macro to indicate to the Wolfram Library to use 32-bit machine integers.

set_windows_static_runtime

Syntax:

set_windows_static_runtime()

Forces static runtime on Windows and does nothing on other platforms. See https://gitlab.kitware.com/cmake/community/wikis/FAQ#dynamic-replace for details.

set_min_windows_version

Syntax:

set_min_windows_version(<target> <version>)

Adds compile definitions to the specified target to set minimum supported Windows version. Does nothing on other platforms. Supported values of <version> include: 7, 8, 8.1 and 10.

set_default_compile_options

Syntax:

set_default_compile_options(<target> <optimization>)

Sets default paclet compile options including warning level and optimization. On Windows, also sets /EHsc. A call to this function may be used as a starting point and new compile options can be added with consecutive calls to target_compile_options().

install_dependency_files

Syntax:

install_dependency_files(<paclet_name> <dependency_target> [lib1, lib2, ...])

Copies dependency libraries into paclet layout if the library type is SHARED (always copies on Windows). Optional arguments are the libraries to copy (defaults to main target file plus its dependencies).

Arguments:

<paclet_name>

name of the paclet (i.e. name of the paclet’s layout root directory)

<dependency_target>

CMake target corresponding to a dependency of the paclet

lib1, lib2, ...

[optional] absolute paths to dynamic libraries on which the paclet depends and which should be copied to the paclet’s layout. If not provided, this information will be deduces from the <dependency_target>.

Paclet Utilities

cmake/LLU/Wolfram/PacletUtilities.cmake contains CMake functions for installing and packaging projects into proper paclets.

install_paclet_files

Syntax:

install_paclet_files(
        TARGET <target>
        [LLU_LOCATION path]
        [PACLET_NAME name]
        [PACLET_FILES_LOCATION path2]
        [INSTALL_TO_LAYOUT])

Configures the CMake install target for a paclet. The only required argument is TARGET which should be followed by the main paclet target (that defines the shared library). The install target configured with this function will copy the directory passed as PACLET_FILES_LOCATION into the location stored in CMAKE_INSTALL_PREFIX. It will also place the PacletInfo.wl in the appropriate location in the paclet and put the shared library under LibraryResources/<system_id>.

Arguments:

TARGET

name of the main target in the paclet’s CMakeLists.txt

LLU_LOCATION

path to LLU installation. This is needed because every paclet that uses the Wolfram Language part of the LLU API needs a copy of LibraryLinkUtilities.wl which is stored in the share folder of LLU installation.

PACLET_NAME

[optional] if the name of the paclet is different than the name of the main paclet target, pass it here

PACLET_FILES_LOCATION

[optional] location of the Wolfram Language source files in the paclet, by default it is assumed as ${CMAKE_CURRENT_SOURCE_DIR}/PACLET_NAME

INSTALL_TO_LAYOUT

[optional] a flag indicating whether the complete paclet layout (what the install target produces) should be also copied to the SystemFiles/Links directory of current Wolfram Language installation (the one used for paclet configuration)

---

add_paclet_target

Syntax:

add_paclet_target(<target>
        NAME name
        [VERIFY]
        [INSTALL]
        [TEST_FILE file]
)

Create a target that produces a proper .paclet file for the project. It takes a paclet layout, produced by the install target, packs it into a .paclet file, optionally verifies contents, installs to the user paclet directory and run tests.

Warning

For this function to work, install target must be built beforehand and wolframscript from Wolfram Language v12.1 or later must be available.

Arguments:

<target>

name for the new target, can be anything

NAME

name of the paclet, it must match the name of the paclet’s layout root directory

VERIFY

[optional] verify contents of the newly created .paclet file

INSTALL

[optional] install .paclet file to the user paclet directory, see PacletInstall for details

TEST_FILE

[optional] provide a path to a test file, if your paclet has one. There is no magic here, CMake will simply ask wolframscript to evaluate the file you provided. What will actually happen fully depends on the contents of your test file.