第五十四章. 构建本机二进制文件

对于生成的每个可执行二进制文件，cpp 插件提供了 install${binary.name} 任务，该任务将创建可执行文件的开发安装，以及它所需要的共享库。 它允许你在不需要在其最终位置安装共享库的情况下运行可执行文件。
For each executable binary produced, the cpp plugin provides an install${binary.name} task, which creates a development install of the executable, along with the shared libraries it requires. This allows you to run the executable without needing to install the shared libraries in their final locations.

C++ 语言支持通过 'cpp' 插件提供。
C++ language support is provided by means of the 'cpp' plugin.

apply plugin: 'cpp'

把 C++ 源码包含到本机二进制文件中，是通过 CppSourceSet 来实现的，它定义了一组 C++ 源文件以及可选的一组导出的头文件（用于库）。默认情况下，对于任何命名的组件，CppSourceSet 包含了在 src/${name}/cpp 中的 .cpp 源文件，以及在 src/${name}/headers 中的头文件。
C++ sources to be included in a native binary are provided via a CppSourceSet, which defines a set of C++ source files and optionally a set of exported header files (for a library). By default, for any named component the CppSourceSet contains .cpp source files in src/${name}/cpp, and header files in src/${name}/headers.

当 cpp 插件为每个 CppSourceSet 定义了这些默认的位置时，可以扩展或重写这些默认值实现不同的项目布局。
While the cpp plugin defines these default locations for each CppSourceSet, it is possible to extend or override these defaults to allow for a different project layout.

sources {
    main {
        cpp {
            source {
                srcDir "src/source"
                include "**/*.cpp"
            }
        }
    }
}

对于名为“main”的库，src/main/headers 中的文件都被视为“public”或“exported”头。不应导出（但内部使用）的头文件应放在 src/main/cpp 目录内（不过请注意，应该始终以包含它们的文件的相对路径这样一种方式来引用这些头文件）。
For a library named 'main', files in src/main/headers are considered the “public” or “exported” headers. Header files that should not be exported (but are used internally) should be placed inside the src/main/cpp directory (though be aware that such header files should always be referenced in a manner relative to the file including them).

C 语言支持是通过 'c' 插件来提供的。
C language support is provided by means of the 'c' plugin.

apply plugin: 'c'

把 C 源码包含到本机二进制文件中，是通过 CSourceSet 来实现的，它定义了一组 C 源文件以及可选的一组导出的头文件（用于库）。默认情况下，对于任何命名的组件，CSourceSet 包含了在 src/${name}/c 中的 .c 源文件，以及在 src/${name}/headers 中的头文件。
C sources to be included in a native binary are provided via a CSourceSet, which defines a set of C source files and optionally a set of exported header files (for a library). By default, for any named component the CSourceSet contains .c source files in src/${name}/c, and header files in src/${name}/headers.

当 c 插件为每个 CSourceSet 定义了这些默认的位置时，可以扩展或重写这些默认值实现不同的项目布局。
While the c plugin defines these default locations for each CSourceSet, it is possible to extend or override these defaults to allow for a different project layout.

sources {
    hello {
        c {
            source {
                srcDir "src/source"
                include "**/*.c"
            }
            exportedHeaders {
                srcDir "src/include"
            }
        }
    }
}

对于名为“main”的库，src/main/headers 中的文件都被视为“public”或“exported”头。不应导出（但内部使用）的头文件应放在 src/main/c 目录内（不过请注意，应该始终以包含它们的文件的相对路径这样一种方式来引用这些头文件）。
For a library named 'main', files in src/main/headers are considered the “public” or “exported” headers. Header files that should not be exported (but are used internally) should be placed inside the src/main/c directory (though be aware that such header files should always be referenced in a manner relative to the file including them).

汇编语言的支持是通过 “assembler” 插件提供的。
Assembly language support is provided by means of the 'assembler' plugin.

apply plugin: 'assembler'

把汇编源码包含到本机二进制文件中，是通过 AssemblerSourceSet 来实现的，它定义了一组 Assembler 源文件。默认情况下，对于任何命名的组件，AssemblerSourceSet 包含了在 src/${name}/asm 中的 .s 源文件。
Assembler sources to be included in a native binary are provided via a AssemblerSourceSet, which defines a set of Assembler source files. By default, for any named component the AssemblerSourceSet contains .s source files under src/${name}/asm.

Objective-C 语言的支持是通过 'objective-c' 插件提供的。
Objective-C language support is provided by means of the 'objective-c' plugin.

apply plugin: 'objective-c'

把 Objective-C 源码包含到本机二进制文件中，是通过 ObjectiveCSourceSet 来实现的，它定义了一组 Objective-C 源文件。默认情况下，对于任何命名的组件，ObjectiveCSourceSet 包含了在 src/${name}/objectiveC 中的 .m 源文件。
Objective-C sources to be included in a native binary are provided via a ObjectiveCSourceSet, which defines a set of Objective-C source files. By default, for any named component the ObjectiveCSourceSet contains .m source files under src/${name}/objectiveC.

Objective-C++ 语言的支持是通过 'objective-cpp' 插件提供的。
Objective-C++ language support is provided by means of the 'objective-cpp' plugin.

apply plugin: 'objective-cpp'

把 Objective-C++ 源码包含到本机二进制文件中，是通过 ObjectiveCppSourceSet 来实现的，其定义了一组 Objective-C++ 源文件。默认情况下，对于任何命名的组件，ObjectiveCppSourceSet 包含了在 src/${name}/objectiveCpp 中的 .mm 源文件。
Objective-C++ sources to be included in a native binary are provided via a ObjectiveCppSourceSet, which defines a set of Objective-C++ source files. By default, for any named component the ObjectiveCppSourceSet contains .mm source files under src/${name}/objectiveCpp.

一组源可能依赖于同一项目中另一个二进制组件提供的头文件。一个常见的示例是，一个本机可执行组件使用了单独的本机库组件提供的功能。
A set of sources may depend on header files provided by another binary component within the same project. A common example is a native executable component that uses functions provided by a separate native library component.

这样的库依赖可以很方便地提供给与 executable 组件相关联的源集：
Such a library dependency can be easily provided to source set associated with the executable component:

sources {
    main {
        cpp {
            lib libraries.hello
        }
    }
}

另外，一个库依赖可以直接提供给 executable 的 ExecutableBinary。
Alternatively, a library dependency can be provided directly to the ExecutableBinary for the executable.

executables {
    main {
        binaries.all {
            // Each executable binary produced uses the 'hello' static library binary
            lib libraries.hello.static
        }
    }
}

对于在不同的 Gradle 项目产生的组件，表示方法是类似的。
For a component produced in a different Gradle project, the notation is similar.

project(":lib") {
    apply plugin: "cpp"
    libraries {
        main {}
    }
    // For any shared library binaries built with Visual C++, define the DLL_EXPORT macro
    binaries.withType(SharedLibraryBinary) {
        if (toolChain in VisualCpp) {
            cppCompiler.define "DLL_EXPORT"
        }
    }
}

project(":exe") {
    apply plugin: "cpp"

    executables {
        main {}
    }

    sources {
        main {
            cpp {
                lib project: ':lib', library: 'main'
            }
        }
    }
}

build type 决定了二进制文件的各种非功能性方面，例如是否包含调试信息，或使用什么样的优化级别来编译。典型的构建类型为“debug”和“release”，但项目可以自由定义任意的一组构建类型。
A build type determines various non-functional aspects of a binary, such as whether debug information is included, or what optimisation level the binary is compiled with. Typical build types are 'debug' and 'release', but a project is free to define any set of build types.

model {
    buildTypes {
        debug
        release
    }
}

如果在项目中未定义任何构建类型，那么会添加一个默认的“debug”构建类型。
If no build types are defined in a project, then a single, default build type called 'debug' is added.

对于一个构建类型，一个 Gradle 项目通常会为每个工具链定义一组编译器或链接器标志。
For a build type, a Gradle project will typically define a set of compiler/linker flags per tool chain.

binaries.all {
    if (toolChain in Gcc && buildType == buildTypes.debug) {
        cppCompiler.args "-g"
    }
    if (toolChain in VisualCpp && buildType == buildTypes.debug) {
        cppCompiler.args '/Zi'
        cppCompiler.define 'DEBUG'
        linker.args '/DEBUG'
    }
}

通过为每个平台生成一个变体，能够使可执行文件或库构建为可以运行在不同的操作系统及 CPU 架构上。Gradle 把每个操作系统/架构的组合定义为一个 Platform，并且一个项目可以定义任意多个平台。如果在项目中没有定义平台，则会添加一个默认的 'current' 平台。
An executable or library can be built to run on different operating systems and cpu architectures, with a variant being produced for each platform. Gradle defines each OS/architecture combination as a Platform, and a project may define any number of platforms. If no platforms are defined in a project, then a single, default platform 'current' is added.

model {
    platforms {
        x86 {
            architecture "x86"
        }
        x64 {
            architecture "x86_64"
        }
        itanium {
            architecture "ia-64"
        }
    }
}

对于给定的变体，Gradle 将尝试查找能够为目标平台构建的 ToolChain 。所有可用的工具链将按照定义的顺序进行查找。更多细节请参阅下面的工具链部分。
For a given variant, Gradle will attempt to find a ToolChain that is able to build for the target platform. Available tool chains are searched in the order defined. See the tool chain section below for more details.

每个组件都可以有一组命名的 flavor，并且可以为每种风格生成单独的二进制变体。虽然 build type 和 target platform 变体维度在 Gradle 中是有定义的含义的，但每个项目都可以自由地定义任意数量的风格，并以任意的方式对它们应用含义。
Each component can have a set of named flavors, and a separate binary variant can be produced for each flavor. While the build type and target platform variant dimensions have a defined meaning in Gradle, each project is free to define any number of flavors and apply meaning to them in any way.

有关组件风格的一个例子是，可以区分组件的“demo”，“paid”和“enterprise”版本，它们是用同样的源码来生成不同功能的二进制文件的。
An example of component flavors might differentiate between 'demo', 'paid' and 'enterprise' editions of the component, where the same set of sources is used to produce binaries with different functions.

model {
    flavors {
        english
        french
    }
}

libraries {
    hello {
        binaries.all {
            if (flavor == flavors.french) {
                cppCompiler.define "FRENCH"
            }
        }
        source sources.lib
    }
}

在上面的示例中，这个库定义了 'english' 和 'french' 两个风格。当编译 'french' 变体时，定义了一个单独的宏，使其生成不同的二进制文件。
In the example above, a library is defined with a 'english' and 'french' flavor. When compiling the 'french' variant, a separate macro is defined which leads to a different binary being produced.

如果一个组件没有定义任何的风格，那么会使用一个叫“default”的默认风格。
If no flavor is defined for a component, then a single default flavor named 'default' is used.

对于一个默认组件，Gradle 将尝试为项目定义的每个 buildType，platform 和 flavor 及它们的每一种组合创建本机二进制变体。通过指定 targetBuildTypes，targetPlatforms 或 targetFlavor的集合，是可以在项目的每个组件的基础上重写的。
For a default component, Gradle will attempt to create a native binary variant for each and every combination of buildType, platform and flavor defined for the project. It is possible to override this on a per-component basis, by specifying the set of targetBuildTypes, targetPlatforms and/or targetFlavors.

executables {
    main {
        targetPlatforms "x86", "x64"
    }
}

在这里你可以看到 TargetedNativeComponent.targetPlatforms() 方法被用于为 executables.main选择一组目标平台。
Here you can see that the TargetedNativeComponent.targetPlatforms() method is used to select the set of platforms to target for executables.main.

在选择 TargetedNativeComponent.targetBuildTypes() 和TargetedNativeComponent.targetFlavors()上也存在着类似的机制。
A similar mechanism exists for selecting TargetedNativeComponent.targetBuildTypes() and TargetedNativeComponent.targetFlavors().

当为一个组件定义了一组构建类型，目标平台及风格时，将会为它们的每种可能的组合创建一个 NativeBinary 模型元素。然而，在许多情况下无法构建特定的变体，可能的原因是没有可用于某个特定平台的构建的工具链。
When a set of build types, target platforms, and flavors is defined for a component, a NativeBinary model element is created for every possible combination of these. However, in many cases it is not possible to build a particular variant, perhaps because no tool chain is available to build for a particular platform.

如果一个二进制变体因为某种原因而不能构建，那么与之关联的 NativeBinary 将不再是 buildable。可以使用这个属性来创建一个任务，生成在特定机器上所有可能的变体。
If a binary variant cannot be built for any reason, then the NativeBinary associated with that variant will not be buildable. It is possible to use this property to create a task to generate all possible variants on a particular machine.

task buildAllExecutables {
    dependsOn binaries.withType(ExecutableBinary).matching {
        it.buildable
    }
}

支持的工具链类型有︰
The supported tool chain types are:

model {
    toolChains {
        visualCpp(VisualCpp) {
            // Specify the installDir if Visual Studio cannot be located by default
            // installDir "C:/Apps/Microsoft Visual Studio 10.0"
        }
        gcc(Gcc) {
            // Uncomment to use a GCC install that is not in the PATH
            // path "/usr/bin/gcc"
        }
        clang(Clang)
    }
}

每个工具链的实现都允许一定程度的配置（更多细节请参阅 API 文档）。
Each tool chain implementation allows for a certain degree of configuration (see the API documentation for more details).

我们没有必要也不可能指定应该用于构建的工具链。对于给定的变体，Gradle 将尝试查找能够为目标平台构建的 ToolChain 。可用的工具链是按定义的顺序来查找的。
It is not necessary or possible to specify the tool chain that should be used to build. For a given variant, Gradle will attempt to locate a ToolChain that is able to build for the target platform. Available tool chains are searched in the order defined.

核心 Gradle 工具链对以下的架构能够开箱即用。在每种情况中，工具链都将针对当前的操作系统。有关其他操作系统交叉编译的信息，请参阅下一节。
The core Gradle tool chains are able to target the following architectures out of the box. In each case, the tool chain will target the current operating system. See the next section for information on cross-compiling for other operating systems.

所以对于在 linux 上运行的 GCC，支持的目标平台为“linux/x86”和“linux/x86_64”；而对于在 Windows 上通过 Cygwin 运行的 GCC，支持的平台则为“windows/x86”和“windows/x86_64”。（Cygwin POSIX 运行时还不能模块为平台的一部分，但以后会实现。）
So for GCC running on linux, the supported target platforms are 'linux/x86' and 'linux/x86_64'. For GCC running on Windows via Cygwin, platforms 'windows/x86' and 'windows/x86_64' are supported. (The Cygwin POSIX runtime is not yet modelled as part of the platform, but will be in the future.)

如果没有为项目定义目标平台，那么所有的二进制文件将针对默认平台“current”进行构建。这个默认平台不指定任何的 architecture 或 operatingSystem 值，因此会使用第一个可用工具链的默认值。
If no target platforms are defined for a project, then all binaries are built to target a default platform named 'current'. This default platform does not specify any architecture or operatingSystem value, hence using the default values of the first available tool chain.

Gradle 提供了一个钩子，允许构建者控制传给可执行的工具链的确切参数集。这使得构建者能够围绕 Gradle 中的任何限制或做出的假定去使用。这个参数钩子应该被当作是一种“最后手段”的机制，我们更倾向于对基本领域真正地进行建模。
Gradle provides a hook that allows the build author to control the exact set of arguments passed to a tool chain executable. This enables the build author to work around any limitations in Gradle, or assumptions that Gradle makes. The arguments hook should be seen as a 'last-resort' mechanism, with preference given to truly modelling the underlying domain.

model {
    toolChains {
        visualCpp(VisualCpp) {
            cppCompiler.withArguments { args ->
                args << "-DFRENCH"
            }
        }
        clang(Clang){
            cCompiler.withArguments { args ->
                Collections.replaceAll(args, "CUSTOM", "-DFRENCH")
            }
            linker.withArguments { args ->
                args.remove "CUSTOM"
            }
            staticLibArchiver.withArguments { args ->
                args.remove "CUSTOM"
            }
        }

    }
}

通过添加对其他目标平台的支持，可以做到使用 Gcc 和 Clang 工具链进行交叉编译。这是通过为工具链指定目标平台来完成的。 对于每个目标平台，都可以指定一个自定义的配置。
Cross-compiling is possible with the Gcc and Clang tool chains, by adding support for additional target platforms. This is done by specifying a target platform for a toolchain. For each targetted platform a custom configuration can be specified.

model {
    toolChains {
        gcc(Gcc) {
            target("arm"){
                cppCompiler.withArguments { args ->
                    args << "-m32"
                }
                linker.withArguments { args ->
                    args << "-m32"
                }
            }
            target("sparc")
        }
    }
    platforms {
        arm {
            architecture "arm"
        }
        sparc {
            architecture "sparc"
        }
    }
}

Gradle 将为项目中的每个 CUnitTestSuite 组件创建名为“cunit”的 CSourceSet。这个源码集应该包含组件源码的 cunit 测试文件。源码文件可以位于约定位置（src/${component.name}Test/cunit），也可以像其他源集一样进行配置。
Gradle will create a CSourceSet named 'cunit' for each CUnitTestSuite component in the project. This source set should contain the cunit test files for the component sources. Source files can be located in the conventional location (src/${component.name}Test/cunit) or can be configured like any other source set.

初始化 CUnit 测试注册和执行测试的作业都由 Gradle 通过某些生成的 CUnit 启动源码来执行。Gradle 将认定并调用一个 void gradle_cunit_register() 函数，这个函数你可以用于配置要执行的实际的 CUnit 套件及测试。
The job of initialising the CUnit test registry and executing the tests is performed by Gradle, via some generated CUnit launcher sources. Gradle will expect and call a function with the signature void gradle_cunit_register() that you can use to configure the actual CUnit suites and tests to execute.

#include <CUnit/Basic.h>
#include "gradle_cunit_register.h"
#include "test_operators.h"

int suite_init(void) {
    return 0;
}

int suite_clean(void) {
    return 0;
}

void gradle_cunit_register() {
    CU_pSuite pSuiteMath = CU_add_suite("operator tests", suite_init, suite_clean);
    CU_add_test(pSuiteMath, "test_plus", test_plus);
    CU_add_test(pSuiteMath, "test_minus", test_minus);
}

一个 CUnitTestSuite 组件有一个相关联的 NativeExecutable 或 NativeLibrary 组件。对于为主组件配置的每一个 ProjectNativeBinary，在测试套件组件上都会配置一个匹配的 TestSuiteExecutableBinary 。这些测试套件二进制文件可以使用一种与其他二进制实例类似的方式来配置：
A CUnitTestSuite component has an associated NativeExecutable or NativeLibrary component. For each ProjectNativeBinary configured for the main component, a matching TestSuiteExecutableBinary will be configured on the test suite component. These test suite binaries can be configured in a similar way to any other binary instance:

binaries.withType(TestSuiteExecutableBinary) {
    lib library: "cunit", linkage: "static"

    if (flavor == flavors.failing) {
        cCompiler.define "PLUS_BROKEN"
    }
}

对于每个 TestSuiteExecutableBinary， Gradle 将创建一个任务来执行此二进制文件，这个任务将运行所有已注册的 CUnit 测试。 生成的测试结果将位于 {build.dir}/test-results 目录中。
For each TestSuiteExecutableBinary, Gradle will create a task to execute this binary, which will run all of the registered CUnit tests. The generated test results will be located in the ${build.dir}/test-results directory.

apply plugin: "c"
apply plugin: "cunit"

model {
    flavors {
        passing
        failing
    }
    repositories {
        libs(PrebuiltLibraries) {
            cunit {
                headers.srcDir "lib/cunit/2.1-2/include"
                binaries.withType(StaticLibraryBinary) {
                    staticLibraryFile = file("lib/cunit/2.1-2/lib/" + findCUnitLibForPlatform(targetPlatform))
                }
            }
        }
    }
}

libraries {
    operators {}
}
binaries.withType(TestSuiteExecutableBinary) {
    lib library: "cunit", linkage: "static"

    if (flavor == flavors.failing) {
        cCompiler.define "PLUS_BROKEN"
    }
}

> gradle -q runFailingOperatorsTestCUnitExe

There were test failures:
  1. /home/user/gradle/samples/native-binaries/cunit/src/operatorsTest/cunit/test_plus.c:6  - plus(0, -2) == -2
  2. /home/user/gradle/samples/native-binaries/cunit/src/operatorsTest/cunit/test_plus.c:7  - plus(2, 2) == 4

:runFailingOperatorsTestCUnitExe FAILED

BUILD FAILED

Total time: 1 secs