anchor.diff:  [[cpp:cached_compilation]]
   == Cached Compilation
   
  -Gradle uses the inputs to a compilation task to calculate a build cache key. This key uniquely identifies the output of the compilation task. When the <<build_cache.adoc#build_cache,build cache>> is enabled, Gradle will first check for a match of the build cache key in a local or remote cache. When there is a hit, Gradle extracts the compilation output into the expected location. 
  +Gradle uses the inputs to a compilation task to calculate a build cache key. This key uniquely identifies the output of the compilation task. When the <<build_cache.adoc#build_cache,build cache>> is enabled, Gradle will first check for a match of the build cache key in a local or remote cache. When there is a hit, Gradle extracts the compilation output into the expected location.
   
   The build cache key takes into consideration:
   
  
positive.code: * Any macros or compiler arguments
  * Contents of the source files
  * Contents of the header files
  * Transitive headers _used_ by the source or header files 
  * Version of Gradle 
  
  [[cpp:building_an_application]]
  == Building an application
  
  Apply the `cpp-application` plugin. 
  You can configure a link:{javadocPath}/org/gradle/language/cpp/CppApplication.html[CppApplication] in a `application` block.
  
  By default, when building a C++ application, the project name will be used as the name of the executable. For Windows, `.exe` will be added.
  
  https://github.com/gradle/native-samples/tree/master/cpp/application[See a sample].
  
  [[cpp:building_a_library]]
  == Building a library
  
  Apply the `cpp-library` plugin. 
  You can configure a link:{javadocPath}/org/gradle/language/cpp/CppLibrary.html[CppLibrary] in a `library` block. 
  
  By default, when building a C++ library, the project name will be used as the name of the library. Depending on the operating system, Gradle will add `.so`, `.dylib` or `.dll` for shared libraries or `.a` or `.lib` for static libraries. Gradle will assume you only want a shared library unless otherwise configured.
  
  https://github.com/gradle/native-samples/tree/master/cpp/simple-library[See a sample]. 
  
  If you only want static libraries, https://github.com/gradle/native-samples/tree/master/cpp/static-library[you can do that too].
  
  [[cpp:cpp_sources]]
  == C++ source layout
  
  By default, Gradle assumes a C++ library or application's sources are in `src/main/cpp`. 
  
  For a library, Gradle assumes its public headers are in `src/main/public`. Header files can be mixed into `src/main/cpp`, but these headers will be treated as private and not exposed to downstream consumers.
  
  Gradle assumes C\++ source files end in `.cpp`, `.c++` or `.cc`.
  
  [[cpp:declaring_dependencies]]
  == Declaring dependencies
  
  Dependencies can be declared in a similar way to other Gradle plugins, like Java, with the main difference being that the `dependencies` block is inside the `application` or `library` block.
  
  C++ applications only have `implementation` level dependencies.
  
  C++ libraries have `api` and `implementation` dependencies.
  
  Dependencies that are `implementation` only are not shared with downstream consumers. `api` dependencies form a part of the public API for a library. 
  
  Gradle automatically knows when to use the headers, link time or runtime usage of a dependency.
  
  [[cpp:project_dependencies]]
  === Project Dependencies
  
  Project dependencies are just like project dependencies in Java projects.  Gradle will export public header paths to downstream consumers and build libraries when required.
  
  https://github.com/gradle/native-samples/tree/master/cpp/transitive-dependencies[See a sample].
  
  [[cpp:external_dependencies]]
  === External Dependencies
  
  External dependencies are like external dependencies in Java projects.  Gradle will automatically fetch a dependency's headers and link/runtime files. The compile and link tasks will be configured to search for headers or libraries in Gradle's dependency cache.
  
  https://github.com/gradle/native-samples/tree/master/cpp/binary-dependencies[See a sample].
  
  [[cpp:publishing]]
  === Publishing 
  
  [NOTE]
  ====
  
  The Gradle metadata format is unstable and likely to change in incompatible ways. This will cause previously published artifacts to no longer be resolved properly. We will announce when this format is stable.
  
  ====
  
  For C++ applications, Gradle will publish the executable.
  
  For C++ libraries, Gradle will publish a header zip and any supporting binaries (shared or static).
  
  Gradle also publishes additional information about the artifacts (a "Gradle metadata" file) that will be used when resolving dependencies.  Gradle needs the additional metadata to select the appropriate variant (e.g., macOS vs Windows).
  
  https://github.com/gradle/native-samples/tree/master/cpp/simple-library[See a sample].
  
  [[cpp:variants]]
  == Configure for different targets
  
  From a C++ library or application, Gradle generates what we call a binary.  This binary is a variant of a component which has been assigned a particular build type (e.g., debug) and target machine (e.g., 32-bit Windows). Only binaries that may be built on the current host are generated by Gradle.
  
  You can configure https://github.com/gradle/native-samples/tree/master/cpp/operating-system-specific-dependencies[variant specific things], such as dependencies. 
  
  [[cpp:build_type]]
  === Debug and Release
  
  Gradle creates two build types:
  
  * Debug - variants of this type are debuggable and not optimized
  * Release - variant of this type are debuggable and optimized
  
  Under the covers, Gradle passes the appropriate compiler arguments for these build types.
  
  Debugging symbols are extracted and stored in a separate file for the release build type, if necessary. 
  
  [[cpp:target_machine]]
  === Target Machine
  
  Gradle assumes the C++ application or library only targets the current host unless told otherwise. When building for multiple target machines, you need to declare this in the build configuration so the published metadata is created correctly.
  
  https://github.com/gradle/native-samples/tree/master/cpp/multiple-target-machines[See a sample].
  
  [[cpp:ide]]
  == IDE integration
  
  Gradle provides plugins for Visual Studio and Xcode. 
  
  When used with the C\++ plugins, Gradle will generate metadata files used by these IDEs. As much as possible, we've tried to make the IDE delegate to Gradle when compiling and linking C++ applications and libraries.
  
  JetBrains maintains a separate integration with CLion.
  
  https://github.com/gradle/native-samples/tree/master/cpp[Try generating a project with one of our samples!]
  
  [[cpp:unit_test]]
  == Unit Testing support
  
  Unit testing support is very limited right now. Gradle makes no assumptions about the type of unit testing framework being used. Gradle automatically links the test executable with the object files produced for the development binary.  If the binary is an executable, Gradle will relocate the `main` symbol so you can test code in an application without conflicting with the test executable's `main` symbol.
  
  In the future, Gradle make come with support out-of-the-box for a particular testing framework or make it easier to integrate your own.
  
  https://github.com/gradle/native-samples/tree/master/cpp/library-with-tests[See a sample].
  
  [[cpp:tool-chain-support]]
  == Tool chain support
  
negative.code: 
  When the C++ plugin is applied to the project, Gradle registers an extension for the type of project (application or library). All configuration is done through this extension or the tasks registered by the plugin.
  
  [NOTE]
  ====
  
  Please be aware that the DSL and APIs may change in later Gradle versions as we add new features with respect to our <<feature_lifecycle.adoc#feature_lifecycle,incubating feature lifecycle>>.
  
  ====
  
  [[cpp:building_an_application]]
  == Building an application
  
  Apply the `cpp-application` plugin. 
  You can configure a link:{javadocPath}/org/gradle/language/cpp/CppApplication.html[CppApplication] in a `application` block.
  
  By default, when building a C++ application, the project name will be used as the name of the executable. For Windows, `.exe` will be added.
  
  https://github.com/gradle/native-samples/tree/master/cpp/application[See a sample].
  
  [[cpp:building_a_library]]
  == Building a library
  
  Apply the `cpp-library` plugin. 
  You can configure a link:{javadocPath}/org/gradle/language/cpp/CppLibrary.html[CppLibrary] in a `library` block. 
  
  By default, when building a C++ library, the project name will be used as the name of the library. Depending on the operating system, Gradle will add `.so`, `.dylib` or `.dll` for shared libraries or `.a` or `.lib` for static libraries. Gradle will assume you only want a shared library unless otherwise configured.
  
  https://github.com/gradle/native-samples/tree/master/cpp/simple-library[See a sample]. 
  
  If you only want static libraries, https://github.com/gradle/native-samples/tree/master/cpp/static-library[you can do that too].
  
  [[cpp:cpp_sources]]
  == C++ source layout
  
  By default, Gradle assumes a C++ library or application's sources are in `src/main/cpp`. 
  
  For a library, Gradle assumes its public headers are in `src/main/public`. Header files can be mixed into `src/main/cpp`, but these headers will be treated as private and not exposed to downstream consumers.
  
  Gradle assumes C\++ source files end in `.cpp`, `.c++` or `.cc`.
  
  [[cpp:declaring_dependencies]]
  == Declaring dependencies
  
  Dependencies can be declared in a similar way to other Gradle plugins, like Java, with the main difference being that the `dependencies` block is inside the `application` or `library` block.
  
  C++ applications only have `implementation` level dependencies.
  
  C++ libraries have `api` and `implementation` dependencies.
  
  Dependencies that are `implementation` only are not shared with downstream consumers. `api` dependencies form a part of the public API for a library. 
  
  Gradle automatically knows when to use the headers, link time or runtime usage of a dependency.
  
  [[cpp:project_dependencies]]
  === Project Dependencies
  
  Project dependencies are just like project dependencies in Java projects.  Gradle will export public header paths to downstream consumers and build libraries when required.
  
  https://github.com/gradle/native-samples/tree/master/cpp/transitive-dependencies[See a sample].
  
  [[cpp:external_dependencies]]
  === External Dependencies
  
  External dependencies are like external dependencies in Java projects.  Gradle will automatically fetch a dependency's headers and link/runtime files. The compile and link tasks will be configured to search for headers or libraries in Gradle's dependency cache.
  
  https://github.com/gradle/native-samples/tree/master/cpp/binary-dependencies[See a sample].
  
  [[cpp:publishing]]
  === Publishing 
  
  [NOTE]
  ====
  
  The Gradle metadata format is unstable and likely to change in incompatible ways. This will cause previously published artifacts to no longer be resolved properly. We will announce when this format is stable.
  
  ====
  
  For C++ applications, Gradle will publish the executable.
  
  For C++ libraries, Gradle will publish a header zip and any supporting binaries (shared or static).
  
  Gradle also publishes additional information about the artifacts (a "Gradle metadata" file) that will be used when resolving dependencies.  Gradle needs the additional metadata to select the appropriate variant (e.g., macOS vs Windows).
  
  https://github.com/gradle/native-samples/tree/master/cpp/simple-library[See a sample].
  
  [[cpp:variants]]
  == Configure for different targets
  
  From a C++ library or application, Gradle generates what we call a binary.  This binary is a variant of a component which has been assigned a particular build type (e.g., debug) and target machine (e.g., 32-bit Windows). Only binaries that may be built on the current host are generated by Gradle.
  
  You can configure https://github.com/gradle/native-samples/tree/master/cpp/operating-system-specific-dependencies[variant specific things], such as dependencies. 
  
  [[cpp:build_type]]
  === Debug and Release
  
  Gradle creates two build types:
  
  * Debug - variants of this type are debuggable and not optimized
  * Release - variant of this type are debuggable and optimized
  
  Under the covers, Gradle passes the appropriate compiler arguments for these build types.
  
  Debugging symbols are extracted and stored in a separate file for the release build type, if necessary. 
  
  [[cpp:target_machine]]
  === Target Machine
  
  Gradle assumes the C++ application or library only targets the current host unless told otherwise. When building for multiple target machines, you need to declare this in the build configuration so the published metadata is created correctly.
  
  https://github.com/gradle/native-samples/tree/master/cpp/multiple-target-machines[See a sample].
  
  [[cpp:ide]]
  == IDE integration
  
  Gradle provides plugins for Visual Studio and Xcode. 
  
  When used with the C\++ plugins, Gradle will generate metadata files used by these IDEs. As much as possible, we've tried to make the IDE delegate to Gradle when compiling and linking C++ applications and libraries.
  
  JetBrains maintains a separate integration with CLion.
  
  https://github.com/gradle/native-samples/tree/master/cpp[Try generating a project with one of our samples!]
  
  [[cpp:unit_test]]
  == Unit Testing support
  
  Unit testing support is very limited right now. Gradle makes no assumptions about the type of unit testing framework being used. Gradle automatically links the test executable with the object files produced for the development binary.  If the binary is an executable, Gradle will relocate the `main` symbol so you can test code in an application without conflicting with the test executable's `main` symbol.
  
  In the future, Gradle make come with support out-of-the-box for a particular testing framework or make it easier to integrate your own.
  
  https://github.com/gradle/native-samples/tree/master/cpp/library-with-tests[See a sample].
  
  [[cpp:incremental_compilation]]
  == Incremental Compilation
  
  