This guide demonstrates how to use Gradle’s Build Init plugin to produce a C++ library that follows Gradle conventions.

What you’ll need

Check the user manual

Gradle ships with the Build Init plugin, which provides an easy way to generate projects of various types using the init task. This task will also execute the wrapper task to create a Gradle wrapper script, gradlew.

Setup

The first step is to create a folder for the new project and change directory into it.

$ mkdir building-cpp-libraries
$ cd building-cpp-libraries

Run the init task

From inside the new project directory, run the init task and select the application project type and the C++ language when prompted. For the other questions, press enter to use the default values.

$ gradle init
> Task :wrapper

Select type of project to generate:
  1: basic
  2: application
  3: library
  4: Gradle plugin
Enter selection (default: basic) [1..4] 3

Select implementation language:
  1: C++
  2: Groovy
  3: Java
  4: Kotlin
  5: Scala
  6: Swift
Enter selection (default: Java) [1..6] 1

Select build script DSL:
  1: Groovy
  2: Kotlin
Enter selection (default: Groovy) [1..2]

Project name (default: building-cpp-libraries):


> Task :init
Get more help with your project: https://docs.gradle.org/5.5.1/userguide/building_cpp_projects.html

BUILD SUCCESSFUL
2 actionable tasks: 2 executed

If you prefer the Kotlin DSL, you can select kotlin for the build script DSL.

The init task runs the wrapper task first, which generates the gradlew and gradlew.bat wrapper scripts. Then it creates the new project with the following structure:

├── build.gradle
├── gradle  (1)
│   └── wrapper
│       ├── gradle-wrapper.jar
│       └── gradle-wrapper.properties
├── gradlew
├── gradlew.bat
├── settings.gradle
└── src
    ├── main
    │   ├── cpp     (2)
    │   │   └── hello.cpp
    │   └── public  (3)
    │       └── building-cpp-libraries.h
    └── test        (4)
        └── cpp
            └── hello_test.cpp
├── build.gradle.kts
├── gradle  (1)
│   └── wrapper
│       ├── gradle-wrapper.jar
│       └── gradle-wrapper.properties
├── gradlew
├── gradlew.bat
├── settings.gradle.kts
└── src
    ├── main
    │   ├── cpp     (2)
    │   │   └── hello.cpp
    │   └── public  (3)
    │       └── building-cpp-libraries.h
    └── test        (4)
        └── cpp
            └── hello_test.cpp
1 Generated folder for wrapper files
2 Default C++ source folder
3 Default exported C++ header folder
4 Default C++ test folder
The Gradle source layout convention can be customized to fit any source layout. See the customizing C++ source section of the User Manual as well as the custom source layout sample for a demonstration.

Review the generated project files

The settings.gradle file is heavily commented, but has only one active line:

settings.gradle
/*
 * This file was generated by the Gradle 'init' task.
 *
 * The settings file is used to specify which projects to include in your build.
 *
 * Detailed information about configuring a multi-project build in Gradle can be found
 * in the user manual at https://docs.gradle.org/5.3/userguide/multi_project_builds.html
 */

rootProject.name = 'building-cpp-libraries'
settings.gradle.kts
/*
 * This file was generated by the Gradle 'init' task.
 *
 * The settings file is used to specify which projects to include in your build.
 *
 * Detailed information about configuring a multi-project build in Gradle can be found
 * in the user manual at https://docs.gradle.org/5.3/userguide/multi_project_builds.html
 */

rootProject.name = "building-cpp-libraries"

This sets the name of the root project to "building-cpp-libraries", which overrides the default behavior of naming the project after the directory it’s in.

The generated build.gradle file also has many comments. The active portion is reproduced here:

build.gradle
/*
 * This file was generated by the Gradle 'init' task.
 *
 * This generated file contains a sample CPP project to get you started.
 */

plugins {
    // Apply the cpp-library plugin to add support for building CPP libraries
    id 'cpp-library'

    // Apply the cpp-unit-test plugin to add support for building and running CPP test executables
    id 'cpp-unit-test'
}

// Set the target operating system and architecture for this library
library {
    targetMachines.add(machines.macOS.x86_64)
}
build.gradle.kts
/*
 * This file was generated by the Gradle 'init' task.
 *
 * This generated file contains a sample CPP project to get you started.
 */

plugins {
    // Apply the cpp-library plugin to add support for building CPP libraries
    `cpp-library`

    // Apply the cpp-unit-test plugin to add support for building and running CPP test executables
    `cpp-unit-test`
}

// Set the target operating system and architecture for this library
library {
    targetMachines.add(machines.macOS.x86_64)
}

The build file adds the cpp-library and cpp-unit-test plugins:

  • The cpp-library plugin automatically generates a library component configurable via the library extension DSL.

  • The cpp-unit-test plugin automatically generates an executable component that depends on the library. It also adds a new verification task that assembles and tests the binary. The unit test component configurable via the unitTest extension DSL.

The generated test file has a single test using the standard library assert function. The test instantiates the Greeter class, invokes the greeting() method, and checks that the returned value is equals to the expected string.

The cpp-unit-test plugin can also be used to test your library binaries using Google Test as demonstrated in the simple library sample.

Execute the build

$ ./gradlew build
> Task :compileTestCpp
> Task :compileDebugCpp
> Task :linkTest
> Task :linkDebug
> Task :assemble
> Task :installTest
> Task :runTest
> Task :test
> Task :check
> Task :build

BUILD SUCCESSFUL
6 actionable tasks: 6 executed
The first time you run the wrapper script, gradlew, there may be a delay while that version of gradle is downloaded and stored locally in your ~/.gradle/wrapper/dists folder.

The build task compiles the C++ sources, links the object files into a shared library, and runs the tests. To build a static library, please refer to the static library sample.

Dependencies on other projects isn’t covered in this guide. To learn more about this subject, have a look at the transitive dependency sample for a demonstration.
Publishing libraries to Maven repositories is outside the scope of this guide. To learn more about this subject, have a look at the simple library sample for a demonstration.
Gradle integrate with several IDEs: Visual Studio, Xcode and Clion. To learn more, have a look at their respective linked documentation to configure those IDE integration in your project.

Summary

You have created a C++ library with unit tests. In doing so, you saw:

  • How to generate a C++ libraries

  • How the generate build file and sample C++ files are structured

  • How to run the build with it’s tests

Next Steps

Help improve this guide

Have feedback or a question? Found a typo? Like all Gradle guides, help is just a GitHub issue away. Please add an issue or pull request to gradle/guides and we’ll get back to you.