Chapter 54. Building native binaries

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.

C++ language support is provided by means of the 'cpp' plugin.

apply plugin: 'cpp'

C++ sources to be included in a native binary are provided via a CppSourceSet, which defines a set of C++ source files and optionally a set of exported header files (for a library). By default, for any named component the CppSourceSet contains .cpp source files in src/${name}/cpp, and header files in src/${name}/headers.

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.

sources {
    main {
        cpp {
            source {
                srcDir "src/source"
                include "**/*.cpp"
            }
        }
    }
}

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

C language support is provided by means of the 'c' plugin.

apply plugin: 'c'

C sources to be included in a native binary are provided via a CSourceSet, which defines a set of C source files and optionally a set of exported header files (for a library). By default, for any named component the CSourceSet contains .c source files in src/${name}/c, and header files in src/${name}/headers.

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

sources {
    hello {
        c {
            source {
                srcDir "src/source"
                include "**/*.c"
            }
            exportedHeaders {
                srcDir "src/include"
            }
        }
    }
}

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/c directory (though be aware that such header files should always be referenced in a manner relative to the file including them).

Assembly language support is provided by means of the 'assembler' plugin.

apply plugin: 'assembler'

Assembler sources to be included in a native binary are provided via a AssemblerSourceSet, which defines a set of Assembler source files. By default, for any named component the AssemblerSourceSet contains .s source files under src/${name}/asm.

A set of sources may depend on header files provided by another binary component within the same project. A common example is a native executable component that uses functions provided by a separate native library component.

Such a library dependency can be easily provided to source set associated with the executable component:

sources {
    main {
        cpp {
            lib libraries.hello
        }
    }
}

Alternatively, a library dependency can be provided directly to the ExecutableBinary for the executable.

executables {
    main {
        binaries.all {
            // Each executable binary produced uses the 'hello' static library binary
            lib libraries.hello.static
        }
    }
}

For a component produced in a different Gradle project, the notation is similar.

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

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

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

The build type determines various non-functional aspects of a binary, such as whether debug information is included, or what optimisation level the binary is compiled with. Typical build types are 'debug' and 'release', but a project is free to define any set of build types.

buildTypes {
    debug {}
    release {}
}

For a build type, a Gradle project will typically define a set of compiler/linker flags per tool chain.

binaries.all {
    if (toolChain in Gcc && buildType == buildTypes.debug) {
        cppCompiler.args "-g"
    }
    if (toolChain in VisualCpp && buildType == buildTypes.debug) {
        cppCompiler.args '/Zi'
        cppCompiler.define 'DEBUG'
        linker.args '/DEBUG'
    }
}

If no build types are defined for a component, then all binaries are built with a single, default build type called 'debug'.

An executable or library can be built to run on different operating systems and cpu architectures, with a variant being produced for each target platform. Gradle defines each target OS/architecture combination as a Platform, and a project may be configured with different targetPlatforms.

targetPlatforms {
    x86 {
        architecture "x86"
    }
    x64 {
        architecture "x86_64"
    }
    itanium {
        architecture "ia-64"
    }
}

The core Gradle tool chains support the following architectures out of the box. There is not currently any core support for building for different operating systems.

Cross-compiling is possible with the Gcc and Clang tool chains, by programmatically adding support for additional target platforms. This is done using the PlatformConfigurableToolChain API. Each added TargetPlatformConfiguration defines support for a particular target platform, and supplies additional tool arguments that are required to target this platform.

If no target platforms are defined for a project, then all binaries are built to target a default platform which does not specify an architecture or operatingSystem, hence using the tool chain default.

Each component can have a set of named flavors, and a separate binary variant can be produced for each flavor. While the build type and target platform variant dimensions have a defined meaning in Gradle, each project is free to define any number of flavors and apply meaning to them in any way.

An example of component flavors might differentiate between 'demo', 'paid' and 'enterprise' editions of the component, where the same set of sources is used to produce binaries with different functions.

libraries {
    hello {
        flavors {
            english {}
            french {}
        }
        binaries.all {
            if (flavor == flavors.french) {
                cppCompiler.define "FRENCH"
            }
        }
        source sources.lib
    }
}

In the above example, a library is defined with a 'english' and 'french' flavor. When compiling the 'french' variant, a separate macro is defined which leads to a different binary being produced.

If no flavor is defined for a component, then a single default flavor named 'default' is used.

Within a single build it is possible to build the same component with different tool chains. To do so, the set of tool chains for a project must be explicitly configured, and a separate variant will be produced for each available tool chain. Attempting to build the variant for a tool chain that is not available on the current machine will result in an error.

toolChains {
    visualCpp(VisualCpp) {
        // Specify the installDir if Visual Studio cannot be located by default
        // installDir "C:/Apps/Microsoft Visual Studio 10.0"
    }
    gcc(Gcc) {
        // Uncomment to use a GCC install that is not in the PATH
        // path "/usr/bin/gcc"
    }
    clang(Clang)
}

The supported tool chain types are:

Each tool chain implementation allows for a certain degree of configuration (see the API documentation for more details).

When a set of build types, target platforms, flavors and tool chains is defined for a component, a NativeBinary model element is created for every possible combination of these. However, in many cases it is not possible to build a particular variant, perhaps because the tool chain for that variant is not available on the current machine, or the tool chain is not able to build for the specified target architecture.

If a binary variant cannot be built for any reason, then the NativeBinary associated with that variant will not be buildable. It is possible to use this property to create a task to generate all possible variants on a particular machine.

task buildAllExecutables {
    dependsOn binaries.withType(ExecutableBinary).matching {
        it.buildable
    }
}