<commit_before>// Copyright 2018 the original author or authors.
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
//      http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.

[[building_cpp_projects]]
= Building C++ projects

Gradle uses a convention-over-configuration approach to building native projects.
If you are coming from another native build system, those concepts may be overwhelming at first but serve the purpose to simplify the whole build script authoring.
It borrows several conventions from Apache Maven.
In particular, it uses the same default directory pattern for source files and headers.

We will look at C\++ projects in detail in this chapter, but most of the topics apply to other supported native languages as well.
If you don’t have much experience with building native projects with Gradle, take a look at the C++ tutorials for step-by-step instructions on how to build various types of basic C++ projects as well as some common use case.

The C++ plugins covered in this chapter were https://blog.gradle.org/introducing-the-new-cpp-plugins[introduced in 2018] and we recommend users to use those plugins over <<native_software.adoc#native_binaries,the older Native plugins>>.

== Introduction

The simplest build script for a C\++ project applies the C++ application plugin or the C++ library plugin and optionally sets the project version:


.Applying the C++ Plugin
====
include::sample[dir="userguide/cpp/basic/groovy",files="build.gradle[tags=apply-cpp-plugin]"]
include::sample[dir="userguide/cpp/basic/kotlin",files="build.gradle.kts[tags=apply-cpp-plugin]"]
====

By applying any of C++ plugin, you get a whole host of features:

 * A `compileDebugCpp` and `compileReleaseCpp` tasks that compiles the C++ source files under _src/main/cpp_ for the well-known debug and release build type respectively.
 * A `linkDebug` and `linkRelease` tasks that links the compiled C++ object files into an executable for applications or shared library for libraries with shared linkage for the well-known debug and release build type respectively.
 * A `createDebug` and `createRelease` tasks that assemble the compiled C++ object files into a static library for libraries with shared linkage for the well-known debug and release build type respectively

This isn’t sufficient to build any non-trivial C++ project - at the very least, you’ll probably have some file dependencies.
But it means that your build script only needs the information that is specific to _your_ project.

// TODO: Add base plugin link
The C++ plugins also integrate the above tasks into the standard Lifecycle Base Plugin lifecycle tasks:

 * `linkDebug` is attached to `assemble`

The rest of the chapter explains the different avenues for customizing the build to your requirements. You will also see later how to adjust the build specifically for libraries and applications.

== Build variants
Gradle is able to build a number of different native binary variants.
They can be differentiated on build type footnote:[For example, debug or release], platform footnote:[For example, Windows x86 or macOS x86-64] and linkage footnote:[For example, shared or static linkage] (library-only).
For each of these 'variant dimensions', tasks, binaries and configuration are created.
<commit_msg>Improve introducing build variant section in user manual<commit_after>// Copyright 2018 the original author or authors.
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
//      http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.

[[building_cpp_projects]]
= Building C++ projects

Gradle uses a convention-over-configuration approach to building native projects.
If you are coming from another native build system, those concepts may be overwhelming at first but serve the purpose to simplify the whole build script authoring.
It borrows several conventions from Apache Maven.
In particular, it uses the same default directory pattern for source files and headers.

We will look at C\++ projects in detail in this chapter, but most of the topics apply to other supported native languages as well.
If you don’t have much experience with building native projects with Gradle, take a look at the C++ tutorials for step-by-step instructions on how to build various types of basic C++ projects as well as some common use case.

The C++ plugins covered in this chapter were https://blog.gradle.org/introducing-the-new-cpp-plugins[introduced in 2018] and we recommend users to use those plugins over <<native_software.adoc#native_binaries,the older Native plugins>>.

== Introduction

The simplest build script for a C\++ project applies the C++ application plugin or the C++ library plugin and optionally sets the project version:

.Applying the C++ Plugin
====
include::sample[dir="userguide/cpp/basic/groovy",files="build.gradle[tags=apply-cpp-plugin]"]
include::sample[dir="userguide/cpp/basic/kotlin",files="build.gradle.kts[tags=apply-cpp-plugin]"]
====

By applying any of C++ plugin, you get a whole host of features:

 * A `compileDebugCpp` and `compileReleaseCpp` tasks that compiles the C++ source files under _src/main/cpp_ for the well-known debug and release build type respectively.
 * A `linkDebug` and `linkRelease` tasks that links the compiled C++ object files into an executable for applications or shared library for libraries with shared linkage for the well-known debug and release build type respectively.
 * A `createDebug` and `createRelease` tasks that assemble the compiled C++ object files into a static library for libraries with shared linkage for the well-known debug and release build type respectively

This isn’t sufficient to build any non-trivial C++ project - at the very least, you’ll probably have some file dependencies.
But it means that your build script only needs the information that is specific to _your_ project.

// TODO: Add base plugin link
The C++ plugins also integrate the above tasks into the standard Lifecycle Base Plugin lifecycle tasks:

 * `linkDebug` is attached to `assemble`

The rest of the chapter explains the different avenues for customizing the build to your requirements. You will also see later how to adjust the build specifically for libraries and applications.

== Introducing build variants

Native projects can typically produce several different binaries, such as debug or release ones, or ones that target particular platforms and processor architectures.
Gradle manages this through the concepts of _dimensions_ and _variants_.

A dimension is simply a category, where each dimension is orthogonal to the rest.
For example, the "build type" dimension is a category that includes debug and release builds.
The "architecture" dimension covers processor architectures like x86_64 and PowerPC.

A variant is a combination of values for these dimensions, consisting of exactly one value for each dimension.
So based on the dimensions just mentioned, you might have a "debug x86_64" or a "release PowerPC" variant.

Gradle has built-in support for several dimensions and several values within each dimension.
You can find a list of them in the <<plugin_reference.adoc#native_languages,native plugin reference chapter>>.

{'fraction_non_alphanumeric': 0.06208947825009295, 'fraction_numerical': 0.004709381583839385, 'mean_word_length': 4.727466288147623, 'pattern_counts': {'":': 0, '<': 9, '<?xml version=': 0, '>': 9, 'https://': 2, 'lorem ipsum': 0, 'www.': 2, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '2652008', 'n_tokens_mistral': 1964, 'n_tokens_neox': 1870, 'n_words': 1113}