Chapter 54. C++ Support

A C++ project may define a number of source sets, each of which may contain source files and header files. By default, a named CppSourceSet contains .cpp and .c source files in src/${name}/cpp, and header files in src/${name}/headers.

cpp {
    sourceSets {
        exe {}
        lib {}
    }
}

For a library named 'main', files in src/main/headers are considered the “public” or “exported” headers. Header files that should not be exported (but are used internally) should be placed inside the src/main/cpp directory (though be aware that such header files should always be referenced in a manner relative to the file including them).

While the cpp plugin defines these default locations for each CppSourceSet, it is possible to extend or override these defaults to allow for a different project layout.

A C++ project defines a set of Executable and Library components, each of which Gradle maps to a number of NativeBinary outputs. Each executable or library is associated with a particular CppSourceSet, which contains C++ source files as well as header files.

To build either a static or shared native library binary, a Library component is added to the libraries container and associated with a CppSourceSet. Each library component can produce at least one SharedLibraryBinary and at least one StaticLibraryBinary.

libraries {
    hello {
        source cpp.sourceSets.lib
    }
}

To build an executable binary, an Executable component is added to the executables container and associated with a CppSourceSet.

Each executable component added can produce at least one ExecutableBinary. If the executable requires a library for compiling and/or linking, then that library can be provided directly to a binary.

executables {
    main {
        source cpp.sourceSets.exe
        binaries.all {
            // Each executable binary produced uses the 'hello' shared library binary
            lib libraries.hello.shared
        }
    }
}

Alternatively, the library dependency can be specified at the level of the the CppSourceSet associated with an executable component:

cpp.sourceSets.exe.lib libraries.hello

All build scripts DSLs, model elements and tasks used to manage C++ projects are added by the cpp plugin.

apply plugin: 'cpp'

The cpp plugin allows you to configure any number of libraries and executables for your project. However, at times it is more convenient to use either the cpp-lib or cpp-exe plugins that sit on top of the cpp plugin and pre-configure the project to build a single native library or executable respectively.

apply plugin: "cpp-exe"

apply plugin: "cpp-lib"

The cpp-exe plugin configures the project to build a single executable named main, and the cpp-lib plugin configures the project to build a shared and static version of a single library named main.

In both cases, a single source set (src/main) containing C++ sources is assumed to exist.

For each NativeBinary that can be produced by a build, the cpp plugin creates a single lifecycle task that can be used to create that binary, together with a set of sub-tasks that do the actual work of compiling, linking or assembling the binary.

Each binary to be produced is associated with a set of compiler and linker settings, which include command-line arguments as well as macro definitions. These settings can be applied to all binaries, an individual binary, or selectively to a group of binaries based on some criteria.

binaries.all {
    // Define a preprocessor macro for every binary
    define "NDEBUG"

    // Define toolchain-specific compiler and linker options
    if (toolChain == toolChains.gcc) {
        compilerArgs "-O2", "-fno-access-control"
        linkerArgs "-S"
    }
    if (toolChain == toolChains.visualCpp) {
        compilerArgs "/Z7"
        linkerArgs "/DEBUG"
    }
}

Each binary is associated with a particular ToolChain, allowing settings to be targeted based on this value.

It is easy to apply settings to all binaries of a particular type:

// For any shared library binaries built with Visual C++, define the DLL_EXPORT macro
binaries.withType(SharedLibraryBinary) {
    if (toolChain == toolChains.visualCpp) {
        define "DLL_EXPORT"
    }
}

Furthermore, it is possible to specify settings that apply to all binaries produces for a particular executable or library component:

executables {
    main {
        binaries.all {
            // Define a preprocessor macro
            define "NDEBUG"
            // Add some additional compiler arguments
            if (toolChain == toolChains.gcc) {
                compilerArgs "-fno-access-control", "-fconserve-space"
            }
        }
    }
}

The above example will apply the supplied configuration to all executable binaries built.

Similarly, settings can be specified to target binaries for a component that are of a particular type: eg all shared libraries for the main library component.

libraries {
    main {
        binaries.withType(SharedLibraryBinary) {
            // Define a preprocessor macro that only applies to shared libraries
            define "DLL_EXPORT"
        }
    }
}

For each executable binary produced, the cpp plugin provides an install${binary.name} task, which creates a development install of the executable, along with the shared libraries it requires. This allows you to run the executable without needing to install the shared libraries in their final locations.

Dependencies for C++ projects are binary libraries that export header files. The header files are used during compilation, with the compiled binary dependency being used during the linking.

cpp {
    sourceSets {
        main {
            dependency group: "some-org", name: "some-lib", version: "1.0"
        }
    }
}

project(":lib") {
    apply plugin: "cpp-lib"
}

project(":exe") {
    apply plugin: "cpp-exe"
    evaluationDependsOn(":lib")

    cpp {
        sourceSets {
            main {
                lib project(":lib").libraries.main
            }
        }
    }
}

The cpp-exe and cpp-lib plugins configure their respective output binaries to be publishable as part of the archives configuration. To publish, simply configure the uploadArchives task as per usual.

group = "some-org"
archivesBaseName = "some-lib"
version = 1.0

uploadArchives {
    repositories {
        mavenDeployer {
            repository(url: uri("${buildDir}/repo"))
        }
    }
}

The cpp-exe plugin publishes a single artifact with extension “exe”. The cpp-lib plugin publishes two artifacts; one with classifier “headers” and extension “zip”, and one with classifier “so” and extension “so” (which is the format used when consuming dependencies).