Building C++ applications and libraries

The C++ plugins provide:

Unlike the software model native plugins, the new C++ plugins rely on a familiar DSL and configuration model.

When the C++ plugin is applied to the project, Gradle registers an extension for the type of project (application or library). All configuration is done through this extension or the tasks registered by the plugin.

Apply the cpp-application plugin. You can configure a CppApplication in a application block.

By default, when building a C++ application, the project name will be used as the name of the executable. For Windows, .exe will be added.

See a sample.

Apply the cpp-library plugin. You can configure a CppLibrary in a library block.

By default, when building a C++ library, the project name will be used as the name of the library. Depending on the operating system, Gradle will add .so, .dylib or .dll for shared libraries or .a or .lib for static libraries. Gradle will assume you only want a shared library unless otherwise configured.

See a sample.

If you only want static libraries, you can do that too.

By default, Gradle assumes a C++ library or application’s sources are in src/main/cpp.

For a library, Gradle assumes its public headers are in src/main/public. Header files can be mixed into src/main/cpp, but these headers will be treated as private and not exposed to downstream consumers.

Gradle assumes C++ source files end in .cpp, .c++ or .cc.

Dependencies can be declared in a similar way to other Gradle plugins, like Java, with the main difference being that the dependencies block is inside the application or library block.

C++ applications only have implementation level dependencies.

C++ libraries have api and implementation dependencies.

Dependencies that are implementation only are not shared with downstream consumers. api dependencies form a part of the public API for a library.

Gradle automatically knows when to use the headers, link time or runtime usage of a dependency.

From a C++ library or application, Gradle generates what we call a binary. This binary is a variant of a component which has been assigned a particular build type (e.g., debug) and target machine (e.g., 32-bit Windows). Only binaries that may be built on the current host are generated by Gradle.

You can configure variant specific things, such as dependencies.

Gradle provides plugins for Visual Studio and Xcode.

When used with the C++ plugins, Gradle will generate metadata files used by these IDEs. As much as possible, we’ve tried to make the IDE delegate to Gradle when compiling and linking C++ applications and libraries.

JetBrains maintains a separate integration with CLion.

Try generating a project with one of our samples!

Unit testing support is very limited right now. Gradle makes no assumptions about the type of unit testing framework being used. Gradle automatically links the test executable with the object files produced for the development binary. If the binary is an executable, Gradle will relocate the main symbol so you can test code in an application without conflicting with the test executable’s main symbol.

In the future, Gradle make come with support out-of-the-box for a particular testing framework or make it easier to integrate your own.

See a sample.

Before invoking the compiler, Gradle analyzes the dependencies between source and header files. When a file changes, Gradle uses this dependency information to select which files need to be recompiled. When macros or compiler arguments change, Gradle must recompile all source files.

Gradle tracks the contents of files, so changes to just the timestamp of a header file (i.e., touching a header file) will not cause Gradle to recompile the affected source files.

If Gradle is unable to determine the relationship between source files and header files, it will fall back to compiling everything to be safe.

Gradle uses a single build worker pool to concurrently compile and link C++ binaries by default. No special configuration is required to enable parallel compilation.

The worker pool size is determined by the number of available processors on the build machine (as reported to the build JVM). To explicitly set the number of workers use the --max-workers command-line option or org.gradle.workers.max system property. There is generally no need to change this setting from its default.

This build worker pool is shared across all tasks. This means that when using parallel project execution, the maximum number of concurrent compilation operations does not increase. For example, if the build machine has 4 processing cores and 10 projects are compiling in parallel, Gradle will only try to compile 4 files at a time and not 40.

Gradle uses the inputs to a compilation task to calculate a build cache key. This key uniquely identifies the output of the compilation task. When the build cache is enabled, Gradle will first check for a match of the build cache key in a local or remote cache. When there is a hit, Gradle extracts the compilation output into the expected location.

The build cache key takes into consideration:

Gradle offers the ability to execute the same build using different tool chains. When you build a native binary, Gradle will attempt to locate a tool chain installed on your machine that can build the binary.

The following tool chains are supported:

The C++ plugins come with a few caveats and limitations:

Issues specific to the C++ plugins and Gradle-Native related features are tracked on a separate repository. If you run into problems or have a feature request, please open an issue up over here.

If you’re interested in contributing to Gradle-Native development and the C++ plugins, please contact us through a GitHub issue.