You can open this sample inside an IDE using the IntelliJ native importer or Eclipse Buildship.

This guide demonstrates how to create a C++ library with Gradle using gradle init. You can follow the guide step-by-step to create a new project from scratch or download the complete sample project using the links above.

The C++ Library Plugin is not compatible with the configuration cache.

What you’ll build

You’ll generate a C++ library that follows Gradle’s conventions.

What you’ll need

Create a project folder

Gradle comes with a built-in task, called init, that initializes a new Gradle project in an empty folder. The init task uses the (also built-in) wrapper task to create a Gradle wrapper script, gradlew.

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

$ mkdir demo
$ cd demo

Run the init task

From inside the new project directory, run the init task using the following command in a terminal: gradle init. When prompted, select the 2: library project type and 5: C++ as implementation language. Next you can choose the DSL for writing buildscripts - 1 : Groovy or 2: Kotlin. For the other questions, press enter to use the default values.

The output will look like this:

$ gradle init

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

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

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

Project name (default: demo):


BUILD SUCCESSFUL
2 actionable tasks: 2 executed

The init task generates the new project with the following structure:

├── gradle (1)
│   ├── libs.versions.toml (2)
│   └── wrapper
│       ├── gradle-wrapper.jar
│       └── gradle-wrapper.properties
├── gradlew (3)
├── gradlew.bat (3)
├── settings.gradle.kts (4)
└── lib
    ├── build.gradle.kts (5)
    └── src
        ├── main
        │   └── cpp (6)
        │   │   └── hello.cpp
        │   └── headers
        │       └── app.h
        └── test
            └── cpp (7)
                └── hello_test.cpp
├── gradle (1)
│   ├── libs.versions.toml (2)
│   └── wrapper
│       ├── gradle-wrapper.jar
│       └── gradle-wrapper.properties
├── gradlew (3)
├── gradlew.bat (3)
├── settings.gradle (4)
└── lib
    ├── build.gradle (5)
    └── src
        ├── main
        │   └── cpp (6)
        │   │   └── hello.cpp
        │   └── headers
        │       └── app.h
        └── test
            └── cpp (7)
                └── hello_test.cpp
1 Generated folder for wrapper files
2 Generated version catalog
3 Gradle wrapper start scripts
4 Settings file to define build name and subprojects
5 Build script of lib project
6 Default C++ source folder
7 Default C++ test source folder

You now have the project setup to build a C++ library.

Review the project files

The settings.gradle(.kts) file has two interesting lines:

settings.gradle.kts
rootProject.name = "demo"
include("lib")
settings.gradle
rootProject.name = 'demo'
include('lib')

  • rootProject.name assigns a name to the build, which overrides the default behavior of naming the build after the directory it’s in. It’s recommended to set a fixed name as the folder might change if the project is shared - e.g. as root of a Git repository.

  • include("lib") defines that the build consists of one subproject called lib that contains the actual code and build logic. More subprojects can be added by additional include(…​) statements.

Our build contains one subproject called lib that represents the C++ library we are building. It is configured in the lib/build.gradle(.kts) file:

lib/build.gradle.kts
plugins {
    `cpp-library` (1)
    `cpp-unit-test` (2)
}

library {
    targetMachines.add(machines.linux.x86_64) (3)
}
lib/build.gradle
plugins {
    id 'cpp-library' (1)
    id 'cpp-unit-test' (2)
}

library {
    targetMachines.add(machines.linux.x86_64) (3)
}
1 Apply the cpp-library plugin to add support for building C++ libraries
2 Apply the cpp-unit-test plugin to add support for building and running C++ test executables
3 Set the target operating system and architecture for this library

The file src/main/cpp/hello.cpp is shown here:

Generated src/main/cpp/hello.cpp
/*
 * This source file was generated by the Gradle 'init' task
 */

#include <iostream>
#include <stdlib.h>
#include "demo.h"

std::string demo::Greeter::greeting() {
    return std::string("Hello, World!");
}

The generated test, src/test/cpp/hello.cpp is shown next:

Generated src/test/cpp/hello_test.cpp
/*
 * This source file was generated by the Gradle 'init' task
 */

#include "demo.h"
#include <cassert>

int main() {
    demo::Greeter greeter;
    assert(greeter.greeting().compare("Hello, World!") == 0);
    return 0;
}

The generated test class has a single C++ executable test. The test instantiates the Hello class, invokes a method on it, and checks that it returns the expected value.

Build the library

$ ./gradlew build

BUILD SUCCESSFUL in 0s
4 actionable tasks: 4 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 integrates 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.

Publish a Build Scan

The best way to learn more about what your build is doing behind the scenes, is to publish a build scan. To do so, just run Gradle with the --scan flag.

$ ./gradlew build --scan

BUILD SUCCESSFUL in 0s
4 actionable tasks: 4 executed

Publishing a build scan to scans.gradle.com requires accepting the Gradle Terms of Service defined at https://gradle.com/terms-of-service.
Do you accept these terms? [yes, no] yes

Gradle Terms of Service accepted.

Publishing build scan...
https://gradle.com/s/5u4w3gxeurtd2

Click the link and explore which tasks where executed, which dependencies where downloaded and many more details!

Summary

That’s it! You’ve now successfully configured and built a C++ library project with Gradle. You’ve learned how to:

  • Initialize a project that produces a C++ library

  • Build the library, which includes running its tests

Next Steps