C++ Application

Contents

Usage
Build variants
Tasks
Dependency management
Conventions

The C++ Application Plugin provides the tasks, configurations and conventions for a building Cpp application.

Usage

Example 1. Applying the C++ Application Plugin

build.gradle

plugins {
   id 'dev.nokee.cpp-application'
}

build.gradle.kts

plugins {
   id("dev.nokee.cpp-application")
}

Build variants

The C++ Application Plugin understands the following dimensions. Read the introduction to build variants for more information.

Operating system family - defaults to the build host: The operating system family expresses which environment the application targets. The supported operating system family are Windows, Linux, and macOS.

Machine architecture - defaults to the build host: The machine architecture expresses which architecture the application targets. The supported architecture are Intel instruction set for both 32 and 64 bit often referred as x86 and x86-64.

Both dimensions are configured together as part of the target machine. It expresses which machines the application expects to run. Nokee uses the target machine to decide which toolchain to choose based on availability on the host machine.

The target machine can be configured as follows:

Example 2. Configure application target machines

build.gradle

application {
    targetMachines = [
        machines.linux.x86_64,
        machines.windows.x86, machines.windows.x86_64,
        machines.macOS.x86_64
    ]
}

build.gradle.kts

application {
    targetMachines.set(listOf(machines.linux.x86_64,
        machines.windows.x86, machines.windows.x86_64,
        machines.macOS.x86_64))
}

Tasks

The following diagram shows the relationships between tasks added by this plugin.

Figure 1. C++ Application Plugin default task graph

Variant-dependent Tasks

The C++ Application Plugin creates tasks based on the variants of the application component. Read the introduction to build variants for more information. The following diagram shows the relationship between variant-dependent tasks.

Figure 2. C++ Application Plugin variant-dependent task graph

compileVariantCpp (e.g. compileWindowsCpp and compileLinuxCpp) - CppCompile: Depends on: All tasks that contribute source files to the compilation
: Compiles Cpp source files using the selected compiler.
objectsVariant (e.g. objectsWindows and objectsLinux) - Task (lifecycle): Depends on: compileVariantCpp
: Aggregates tasks that compile the source files to object files for the specific variant of this application.
linkVariant (e.g. linkWindows and linkLinux) - LinkExecutable: Depends on: All tasks which contribute to the link executable, including linkVariant and createVariant tasks from projects that are resolved via project dependencies
: Links executable from compiled object files using the selected linker.
executableVariant (e.g. executableWindows and executableLinux) - Task (lifecycle): Depends on: linkVariant
: Aggregates tasks that creates the executable binary for the specific variant of this application.
assembleVariant (e.g. assembleWindows and assembleLinux) - Task (lifecycle): Depends on: linkVariant

Aggregates tasks that assemble the specific variant of this application.

Lifecycle Tasks

The C++ Application Plugin attaches some of its tasks to the standard lifecycle tasks documented in the Base Plugin chapter - which the C++ Application Plugin applies automatically:

assemble - Task (lifecycle): Depends on: link task for the current host, if present
: Aggregate task that assembles the variant of the application for the current host (if present) in the project. This task is added by the Base Plugin.
check - Task (lifecycle): Aggregate task that performs verification tasks, such as running the tests. Some plugins add their own verification task to check. This task is added by the Base Plugin.
build - Task (lifecycle): Depends on: check, assemble
: Aggregate tasks that perform a full build of the project. This task is added by the Base Plugin.
clean - Delete: Deletes the build directory and everything in it, i.e. the path specified by the Project.getBuildDir() project property. This task is added by the Base Plugin.

Dependency management

Just like the tasks created by the C++ Application Plugin, multiple configurations are created based on the variants of the application component. Read the introduction to build variants for more information. The following graph describes the configurations added by the C++ Application Plugin:

Figure 3. C++ Application Plugin configurations

The configurations in white are the ones a user should use to declare dependencies
The configurations in pink, also known as consumable denoted by (C), are the ones used when a component runs against the library
The configurations in blue, also known as resolvable denoted by (R), are internal to the component, for its own use

The following configurations are used to declare dependencies:

implementation: Used for declaring implementation dependencies for all variants of the main component. This is where you should declare dependencies of any variants.
variantImplementation (e.g. windowsImplementation and linuxImplementation) extends implementation: Used for declaring implementation dependencies for a specific variant of the main component. This is where you should declare dependencies of the specific variant.

The following configurations are used by downstream consumers that depend on the application component:

variantRuntimeElements (e.g. windowsRuntimeElements and linuxRuntimeElements) extends variantImplementation: Used for executing the application. This configuration is meant to be used by consumers, to retrieve all the elements necessary to run the application.

The following configurations are used by the application itself:

variantHeaderSearchPaths (e.g. windowsHeaderSearchPaths and linuxHeaderSearchPaths) extends variantImplementation: Used for compiling the application. This configuration contains the compile include roots of the application and is therefore used when invoking the Cpp compiler to compile it.
variantLinkLibraries (e.g. windowsLinkLibraries and linuxLinkLibraries) extends variantImplementation: Used for linking the application. This configuration contains the libraries of the application and is therefore used when invoking the Cpp linker to link it.
variantRuntimeLibraries (e.g. windowsRuntimeLibraries and linuxRuntimeLibraries) extends variantImplementation: Used for executing the application. This configuration contains the runtime libraries of the application.

Conventions

The C++ Application Plugin adds conventions for sources and tasks, shown below.

Project layout

The C++ Application Plugin assumes the project layout shown below. None of these directories need to exist or have anything in them. The C++ Application Plugin will compile whatever it finds and ignore anything missing.

src/main/cpp: C++ source with extension of .cp, .cpp, .c++, .cc, or .cxx
src/main/headers: Headers - headers needed to compile the application

Compile Task

The C++ Application Plugin adds a CppCompile instance for each variant of the application component to build (e.g. compileWindowsCpp and compileLinuxCpp). Read the introduction to build variants for more information. Some of the most common configuration options are shown below.

compilerArgs	[]
headerSearchPaths	`configurations.variantHeaderSearchPaths` + `${project.projectDir}/src/main/headers`
toolChain	automatically selected based on target machine

Link Task

The C++ Application Plugin adds a LinkExecutable instance for each variant of the application — e.g. linkWindows and linkLinux. Read the introduction to build variants for more information. Some of the most common configuration options are shown below.

linkedFile	`$buildDir/exe/main/variant/baseName` (*nix) or `$buildDir\exe\main\variant\baseName.exe` (Windows)
linkerArgs	[]
toolChain	automatically selected based on target machine