CMake plugin¶

Description¶

The cmake plugin is used for generating, building and installing software using the CMake build generator system.

Mandatory settings¶

There are no mandatory settings for this plugin, though it is recommended to configure the mode setting explicitly.

Optional settings¶

The configuration of the make plugin may contain the following settings:

Settings for all modes¶

patterns: A list of patterns to apply on the command line. See Patterns (5).

enviroment: A list of environment variables that should be set before the commands are executed. See Environment (5).

command-line: Additional command line parameters to pass as a list of separate arguments. By default no additional arguments are added.

working-dir: The working directory of the command. Can be an absolute path are a relative one w.r.t. the path to the considered configuration file. Commands that should be executed relative to the current working dir can use the {EH_WORKING_DIR} pattern.

mode

Set the mode of the CMake call for the specific command. Default: generate.

Supported modes are:

Generate: For generating a build directory based on the CMake configuration in the source. This is often callend the configure or build init step.
Build: Build the generated project
Install: Install the generated project

build-dir: The path to the build directory. This is either an absolute path are a path relative to the location of this file. Default: . (the directory of the exec-helper configuration).

Settings for the generate mode¶

source-dir: The directory containing the root CMakeLists.txt file of the sources. Default: . (the directory of the exec-helper configuration).

generator: The generator to use for generating the build directory. See the CMake documentation on which generators are supported for your platform and the value(s) to explicitly set them. Default: the default one for your system and environment. See the CMake documentation on the details.

defines: A map of the build generator settings for configuring the generator.

Settings for the build mode¶

target: The specific CMake target to build. Default: the default target. See the CMake documentation for more details.

config: The configuration for multi-configuration tools. Default: the default configuration. See the CMake documentation for more details.

Settings for the install mode¶

config: The configuration for multi-configuration tools. Default: the default configuration. See the CMake documentation for more details.

prefix: Override the configured prefix set during the generate mode. Default: the default installation prefix. See the CMake documentation for more details.

component: Limit installation to the given component. Default: all installation targets.

Example¶

Configuration¶

commands:                       # Define the commands that can be run
    example: Run the cmake example
    clean: Clean the build
    run: Run the files that were built

patterns:                       # Define the patterns that can be used
    CMAKE_TARGET:               # Define the CMAKE_TARGET pattern.
        default-values:         # Only define the default value
            - hello
            - world

example:
    - build                     # Use the cmake plugin when running the 'example' command
    - run

build:
    - generate
    - build-only
    - install

generate: cmake
build-only: cmake
install: cmake

clean:                          # Use the cmake plugin when running the 'clean' command
    - cmake

run:
    - command-line-command

cmake:
    environment:                # Define additional environment variables
        WORLD: "world!"
    patterns:               # The patterns that are used by the cmake plugin
        - CMAKE_TARGET
    source-dir: .           # Set the source dir for all cmake targets that do not further specialize this
    build-dir: build        # Set the build dir for all cmake targets that do not further specialize this

    generate:               # Specific settings for the 'generate' command
        mode: generate      # Set the mode
        defines:            # Set some defines
            CMAKE_BUILD_MODE: RelWithDebInfo
        command-line:           # Define additional command line arguments
            - -Wno-dev          # An example argument passed to cmake

    build-only:             # Specific settings for the 'build-only' command
        mode: build         # Set the mode

    install:                # Specific settings for the 'install' command
        mode: install       # Set the mode
        prefix: /tmp        # Set the prefix
        component: runtime  # Limit to installing 'runtime' components

    clean:
        mode: build
        target: clean

command-line-command:
    patterns:
        - CMAKE_TARGET
    command-line:
        - build/{CMAKE_TARGET}

Additional files¶

In order for the above example to work, the following file hierarchy needs to be created in the directory:

CMakeLists.txt:

cmake_minimum_required(VERSION 3.0)
project(cmake-example CXX)

set(CMAKE_CXX_STANDARD 11)
set(CMAKE_CXX_STANDARD_REQUIRED ON)
set(CMAKE_CXX_EXTENSIONS OFF)

add_executable(hello src/hello.cpp)
add_executable(world src/world.cpp)
install(TARGETS hello world DESTINATION bin COMPONENT runtime)

hello.cpp:

#include <cstdlib>
#include <iostream>

auto main() -> int {
    std::cout << "Hello" << std::endl;
    return EXIT_SUCCESS;
}

world.cpp:

#include <cstdlib>
#include <iostream>

auto main() -> int {
    std::cout << "World!" << std::endl;
    return EXIT_SUCCESS;
}

Usage¶

Save the example to an exec-helper configuration file and execute in the same directory:

eh example