Chapter 40. C++ Support

The Gradle C++ support is experimental and in very early stages of development so should not be considered stable.

The C++ plugins add support for building software comprised of C++ source code, and managing the process of building “native” software in general. While many excellent build tools exist for this space of software development, Gradle brings the dependency management practices more traditionally found in the JVM development space to C++ developers.

Currently, support is restricted to building with the g++ (i.e. the C++ focussed frontend to GCC) compiler/linker. Furthermore, there is no direct support for creating multiple variants of the same binary (e.g. 32 bit vs. 64 bit) and there is no direct support for cross platform source configuration (à la autoconf) at this time. Support for different compiler chains, managing multiple variants and cross platform source configuration will be added over time, making Gradle a fully capable build tool for C++ (and other “native” language) projects.

40.1. Usage

The build scripts DSLs, model elements and tasks used to manage C++ projects are added by the cpp plugin. However, it is typically more convenient to use either the cpp-lib or cpp-exe plugins that sit on top of the cpp plugin to preconfigure the project to build either a shared library or executable binary respectively.

Example 40.1. Using the 'cpp-exe' plugin

build.gradle

apply plugin: "cpp-exe"

Example 40.2. Using the 'cpp-lib' plugin

build.gradle

apply plugin: "cpp-lib"

The cpp-exe plugin configures the project to build a single executable (at $buildDir/binaries/main) and the cpp-lib plugin configures the project to build a single shared library (at $buildDir/binaries/main.so).

40.2. Source code locations

Both plugins configure the project to look for .cpp source files in src/main/cpp and use the src/main/headers directory as a header include root. For a library, the header 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).

40.3. Compiling

For both the cpp-lib and cpp-exe plugins, you can run the compileMain task.

As previously stated, the C++ support is currently based on the g++ tool which must be installed and on the PATH for the Gradle process.

Arbitrary arguments can be provided to g++ by using the following syntax:

Example 40.3. Supplying arbitrary args to gpp

build.gradle

executables {
    main {
        spec {
            args "-fno-access-control", "-fconserve-space"
        }
    }
}

The above example applies to the cpp-exe plugin, to supply arguments for the cpp-lib plugin replace “executables” with “libraries”.

40.4. Dependencies

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.

40.4.1. External Dependencies

External dependencies (i.e. from a repository, not a subproject) must be specified using the following syntax:

Example 40.4. Declaring dependencies

build.gradle

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

Each dependency must be specified with the dependency method as above and must be declared as part of the source set. The group, name and version arguments must be supplied.

For each declared dependency, two actual dependencies are created. One with the classifer “headers” and extension “zip” which is a zip file of the exported headers, and another with the classifier “so” and extension “so” which is the compiled library binary to link against (which is supplied as a direct input to the g++ link operation).

40.4.2. Project Dependencies

The notation for project dependencies is slightly different.

Example 40.5. Declaring project dependencies

build.gradle

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

project(":exe") {
    apply plugin: "cpp-exe"
    cpp {
        sourceSets {
            main {
                libs << project(":lib").libraries.main
            }
        }
    }
}

40.5. Publishing

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.

Example 40.6. Uploading exe or lib

build.gradle

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).

Currently, there is no support for publishing the dependencies of artifacts in POM or Ivy files. Future versions will support this.