This guide demonstrates how to create a minimalist C++ executable using Gradle’s cpp plugin.

What you’ll need

Layout

The first step is to create a folder for the new project and add a Gradle Wrapper to the project.

$ mkdir cpp-executable
$ cd cpp-executable
$ gradle wrapper (1)

:wrapper

BUILD SUCCESSFUL
1 This allows a version of Gradle to be locked to a project and henceforth you can use ./gradlew instead of gradle.

Create a minimalist build.gradle file with the following content:

build.gradle
apply plugin : 'cpp-application' (1)

application {
    baseName = "greeting" (2)
}
1 C++ projects are enabled via the cpp-application plugin
2 Change the application binary names, the base name defaults to the project name

Add source code

By convention, C++ projects in Gradle will follow a more contemporary layout. This can be troublesome for you if you are used to building C++ code with build tools that do not use a convention-over-configuration approach. Rest assured that Gradle is very configurable in this regard and should you need to migrate a C++ project to Gradle you can consult the C++ sources section of the User Guide.

The executable component is called main. By convention, Gradle will look in src/main/cpp for source files and non-exported header files. Create this folder

$ mkdir -p src/main/cpp

and place a main.cpp and a greeting.hpp within.

src/main/cpp/main.cpp
#include "greeting.h" (1)

#include <iostream>  (2)

int main(int argc, char** argv) {
  std::cout << greeting << std::endl;
  return 0;
}
1 Non-exported headers will be searched for relative to the specified C++ source folders. (In this case src/main/cpp).
2 The standard C++ headers wil be located via the compiler toolchain that Gradle uses
src/main/cpp/greeting.h
#ifndef GREETING_H_
#define GREETING_H_

namespace {
  const char * greeting = "Hello, World";
}

#endif  // GREETING_H_

Build your project

To build your project you can simply do ./gradlew assemble as per usual:

$ ./gradlew assemble

:compileDebugCpp (1)
:linkDebug (2)
:assemble

BUILD SUCCESSFUL
1 To keep things tidy on the console, Gradle does not display compiler output. If you need to ever diagnose a compilation issue, the output from the compiler is stored in build/tmp/compileDebugCpp/output.txt.
2 In a similar fashion the output from the linker is written to build/tmp/linkDebug/output.txt

Look inside the build folder and you will notice the appearance of a exe folder. By convention Gradle will place all executables 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 main (or main.exe under Windows).

Now run your newly built executable.

$ ./build/exe/main/debug/greeting

Hello World

Congratulations! You have just built a C++ executable with Gradle.

Summary

You have created an C++ project that can be used as a foundation for something more substantial. In the process you saw:

  • How to create a build script for C++ executables.

  • Where to add source code by convention.

  • How to build the executable without building the full project.

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/building-cpp-executables and we’ll get back to you.