# Building C++ Applications Sample

version 9.0.0

- Groovy DSL

- Kotlin DSL

| You can open this sample in an IDE that supports Gradle.

This guide demonstrates how to create a C++ application 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.

## What you’ll build

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

## What you’ll need

- A text editor or IDE - for example IntelliJ IDEA

- A Java Development Kit (JDK), version 8 or higher - for example AdoptOpenJDK

- The latest Gradle distribution

- An installed C++ compiler. See which C++ tool chains are supported by Gradle.

## 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 `1: application` project type and `5: C++` as the implementation language. Next you can choose the DSL for writing buildscripts - `1 : Kotlin` or `2: Groovy`. For the other questions, press enter to use the default values.

The output will look like this:

    $ gradle init

    Select type of build to generate:
      1: Application
      2: Library
      3: Gradle plugin
      4: Basic (build structure only)
    Enter selection (default: Application) [1..4] 1

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

    Project name (default: demo):

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

    Generate build using new APIs and behavior (some features may change in the next minor release)? (default: no) [yes, no]

    BUILD SUCCESSFUL
    1 actionable task: 1 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)
    └── app
        ├── build.gradle.kts (5)
        └── src
            ├── main
            │   └── cpp (6)
            │   │   └── app.cpp
            │   └── headers
            │       └── app.h
            └── test
                └── cpp (7)
                    └── app_test.cpp

    ├── gradle (1)
    │   ├── libs.versions.toml (2)
    │   └── wrapper
    │       ├── gradle-wrapper.jar
    │       └── gradle-wrapper.properties
    ├── gradlew (3)
    ├── gradlew.bat (3)
    ├── settings.gradle (4)
    └── app
        ├── build.gradle (5)
        └── src
            ├── main
            │   └── cpp (6)
            │   │   └── app.cpp
            │   └── headers
            │       └── app.h
            └── test
                └── cpp (7)
                    └── app_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 `app` project
6 | Default C++ source folder
7 | Default C++ test source folder

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

## Review the project files

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

settings.gradle.kts

    rootProject.name = "demo"
    include("app")

settings.gradle

    rootProject.name = 'demo'
    include('app')

- `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("app")` defines that the build consists of one subproject called `app` that contains the actual code and build logic. More subprojects can be added by additional `include(…​)` statements.

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

app/build.gradle.kts

    plugins {
        `cpp-application` (1)
        `cpp-unit-test` (2)
    }

    application { (3)
        targetMachines.add(machines.linux.x86_64)
    }

app/build.gradle

    plugins {
        id 'cpp-application' (1)
        id 'cpp-unit-test' (2)
    }

    application { (3)
        targetMachines.add(machines.linux.x86_64)
    }

1 | Apply the cpp-application plugin to add support for building C++ executables
2 | Apply the cpp-unit-test plugin to add support for building and running C++ test executables

The file `src/main/cpp/app.cpp` is shown here:

Generated src/main/cpp/app.cpp

    /*
     * This source file was generated by the Gradle 'init' task
     */

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

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

    int main () {
        demo::Greeter greeter;
        std::cout << greeter.greeting() << std::endl;
        return 0;
    }

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

Generated src/test/cpp/app_test.cpp

    /*
     * This source file was generated by the Gradle 'init' task
     */

    #include "app.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 `Greeter` class, invokes a method on it, and checks that it returns the expected value.

## Build the application

    $ ./gradlew build

    BUILD SUCCESSFUL in 0s
    7 actionable tasks: 7 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, and runs the tests. It also packages the main and test applications for distribution on other systems. The `installDebug` and `installTest` tasks, which both run as part of `build`, copy the executable and generates a shell script for executing the application. The following shows the content of the `build/install` folder:

    ./app/build/install
    ├── main
    │   └── debug
    │       ├── app      (1)
    │       └── lib
    │           └── app  (2)
    └── test
        ├── appTest      (1)
        └── lib
            └── appTest  (3)

1 | The script for executing the application variant
2 | The main executable binary (debug variant)
3 | The test executable binary

| When a build has dependencies, the dependent libraries are also copied into the installation folder. The shell scripts properly configure the library path so the package can be relocated.

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

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

## Run the application

Look inside the `build` folder and you will notice the appearance of an `exe` folder. By convention, Gradle will place all applications in subfolders named according to the component name. In this case, you will find your assembled executable in `build/exe/main/debug` and it will be called `app` (or `app.exe` under Windows).

Now run your newly built executable.

    $ ./app/build/exe/main/debug/app
    Hello, World!

## 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
    7 actionable tasks: 7 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++ application project with Gradle. You’ve learned how to:

- Initialize a project that produces a C++ application

- Build, bundle and run the application

## Next steps

To learn more about how you can further customize C++ application projects, check out the user manual chapter on Building C++ projects.