第54章. 构建原生二进制文件

对于每个产生的可执行二进制文件， 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.

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

apply plugin: 'cpp'

把 C++ 源码包含到原生二进制文件中，是通过一个 CppSourceSet来实现的，它定义了一个C++源文件集以及（可选的）一个可导出的头文件（用于library）集默认情况下，对于任何命名的组件，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”的library， src/main/headers中的文件都被视为"公共"或"导出"的头文件。不应该被导出（而是内部使用）的头文件，应该放在 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源文件集以及（可选的）一个可导出的头文件（用于library）集默认情况下，对于任何命名的组件，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”的library， src/main/headers中的文件都被视为"公共"或"导出"的头文件。不应该被导出（而是内部使用）的头文件，应该放在 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来实现的，它定义了一个汇编源文件集。默认情况下，对于任何命名的组件，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-cpp' 插件提供了Objective-C++ 语言的支持。
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.

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

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

另外，一个库依赖项可以直接提供给ExecutableBinary的executable。
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 项目产生的组件，notation是类似的。
For a component produced in a different Gradle project, the notation is similar.

project(":lib") {
    apply plugin: "cpp"
    libraries {
        main {}
    }
}

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

    executables {
        main {}
    }

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

一个 build type 确定了一个二进制文件的各种非功能性方面，比如是否包含调试信息，或者使用什么样的优化级别来编译二进制文件。典型的构建类型是“debug”和“release”，但一个project可以自由定义任意的构建类型。
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
    }
}

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

对于一个构建类型，Gradle project 通常会定义一组每个工具链的编译器/链接器标志。
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，一个project可以定义多个platforms。如果在project里没有定义任何平台，那么会添加一个默认的“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.

每个组件都可以有一组flavors，并且能为每一个flavor生成一个单独的二进制变种。在Gradle中 build type 和 target platform 变种维度是有一个确定的定义的，而每一个project都可以自由地定义数量的flavor并且用任何方式去应用它们的意义。
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.

一个关于组件flavor的例子是可以区分组件的“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
    }
}

在上面的示例中，library 定义了“english”和“french”两个flavor。当编译“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.

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

对于一个默认的组件， Gradle会尝试为这个project所定义的每一个buildType， platform 和 flavor，以及它们的每一种组合，创建一个本地二进制变种。通过指定的 targetBuildTypes， targetPlatforms 或 targetFlavors，是可以在每一个组件的基础上进行重写的。
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() and和TargetedNativeComponent.targetFlavors()上也有类似的机制。
A similar mechanism exists for selecting TargetedNativeComponent.targetBuildTypes() and TargetedNativeComponent.targetFlavors().

当为一个组件定义了一组构建类型，目标平台，以及flavor时，将会为它们的每一种可能的组合创建一个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”。对于通过Cygwin运行在Windows上的GCC，则支持“windows/x86”和“windows/x86_64”。（Cywgin运行时还不能模拟为Platform的一部分，但以后将会实现。）
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 runtime is not yet modelled as part of the Platform, but will be in the future.)

如果在project里没有定义任何平台，那么所有的二进制文件会针对一个默认平台“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.

使用 Gcc 和 Clang 工具链，通过 以编程方式添加附加的目标平台的支持，是可以做到交叉编译的。它通过 PlatformConfigurableToolChain API来完成。每个添加的 TargetPlatformConfiguration 定义了对一个特定的目标平台的支持，并且提供了针对该平台所需要的额外的工具参数。
Cross-compiling is possible with the Gcc and Clang tool chains, by programmatically adding support for additional target platforms. This is done using the PlatformConfigurableToolChain API. Each added TargetPlatformConfiguration defines support for a particular target platform, and supplies additional tool arguments that are required to target this platform.

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 组件会有一个相关联的 Executable 或 Library 组件。对于为main 组件配置的每一个ProjectNativeBinary，在测试套件组件上都会配置一个匹配的 TestSuiteExecutableBinary 。这些测试套件二进制文件可以以一种类似的方式配置到任何其他二进制的实例︰
A CUnitTestSuite component has an associated Executable or Library 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