Bazel on chai2010 的博客

Bazel C++ 基础[翻译]

Tue, 28 Jun 2016 00:00:00 +0000

原文：http://www.bazel.io/docs/cpp.html
译者：chai2010

使用绝对路径

包含的路径是相对于工作区的根路径。假设有以下的目录结构：

[workspace]/
    WORKSPACE
    a/
        BUILD
        a.h
        a.cc
    b/
        BUILD
        b.h
        b.cc
        main.cc

如果b/main.cc需要包含b.h头文件，我们需要创建以下的b/BUILD文件：

cc_library(
    name = "b",
    srcs = ["b.cc"],
    hdrs = ["b.h"],
)

cc_binary(
    name = "main",
    srcs = ["main.cc"],
    deps = [":b"],
)

b/main.cc可以这样包含b.h：

#include "b/b.h"

上面的头文件包含路径是相对于工作区根目录的相对路径。如果b/main.cc还要依赖a/a.h头文件的话，我们还需要添加a/BUILD文件：

cc_library(
    name = "a",
    srcs = ["a.cc"],
    hdrs = ["a.h"],
    visibility = ["//b:__pkg__"],
)

然后我们在b/BUILD添加依赖关系：

cc_binary(
    name = "main",
    srcs = ["main.cc"],
    deps = [
        ":b",
        "//a",
    ],
)

b/main.cc代码中也包含了a/a.h头文件：

#include "a/a.h"

b/main.cc就可以正常使用a/a.h或b/b.h中导出的符号了。

依赖传递

如果包含了一个头文件，那么需要将头文件对应的库添加到依赖中。不过，只需有添加直接依赖的库。假设三明治对应的sandwich.h文件包含了面包对应的bread.h文件，同时bread.h又包含了面粉对应的flour.h文件。但是，三明治sandwich.h文件并没有直接包含面粉flour.h文件（三明治用户当然不关心面粉的事情），因此BUILD文件可以这样：

cc_library(
    name = "sandwich",
    srcs = ["sandwich.cc"],
    hdrs = ["sandwich.h"],
    deps = [":bread"],
)

cc_library(
    name = "bread",
    srcs = ["bread.cc"],
    hdrs = ["bread.h"],
    deps = [":flour"],
)

cc_library(
    name = "flour",
    srcs = ["flour.cc"],
    hdrs = ["flour.h"],
)

上面表示了sandwich三明治库依赖bread面包库，bread又依赖flour对应的面粉库。

添加头文件包含路径

很多时候你可能并不希望基于工作区根路径的相对路径来包含每个头文件。因为很多已经存在的第三方库的头文件包含方式并不是基于工作区的根路径。假设有以下目录结构：

[workspace]/
    WORKSPACE
    third_party/
        some_lib/
            include/
                some_lib.h
            BUILD
            some_lib.cc

Bazel希望用third_party/some_lib/include/some_lib.h方式包含some_lib.h，但是some_lib.cc可能跟希望用"include/some_lib.h"方式包含。为了使得包含路径有效，需要在third_party/some_lib/BUILD文件中将some_lib/目录添加到头文件包含路径的搜索列表中：

cc_library(
    name = "some_lib",
    srcs = ["some_lib.cc"],
    hdrs = ["some_lib.h"],
    copts = ["-Ithird_party/some_lib"],
)

这对于依赖的外部第三方库特别有效，因为可以避免在头文件路径中出现无关的external/[repository-name]/前缀。

包含外部库：一个例子

假设使用了 Google Test。可以在WORKSPACE文件中使用new_开头的仓库相关的函数，下载依赖的GTest代码到当前仓库中：

new_http_archive(
    name = "gtest",
    url = "https://googletest.googlecode.com/files/gtest-1.7.0.zip",
    sha256 = "247ca18dd83f53deb1328be17e4b1be31514cedfc1e3424f672bf11fd7e0d60d",
    build_file = "gtest.BUILD",
)

创建gtest.BUILD文件，对应Google Test的构建配置文件。配置文件中有几个需要特别注意的地方：

gtest-1.7.0/src/gtest-all.cc文件已经采用#include语法包含了gtest-1.7.0/src/目录中其它*.cc文件，因此需要将它排除在外（也可以只包含它一个文件，但是需要正确配置包含路径）。
它的头文件在gtest-1.7.0/include/目录，需要将它添加到头文件包含路径列表中
GTest依赖pthread多线程库，通过linkopt选项指定。

最终的规则大概是这样：

cc_library(
    name = "main",
    srcs = glob(
        ["gtest-1.7.0/src/*.cc"],
        exclude = ["gtest-1.7.0/src/gtest-all.cc"]
    ),
    hdrs = glob([
        "gtest-1.7.0/include/**/*.h",
        "gtest-1.7.0/src/*.h"
    ]),
    copts = [
        "-Iexternal/gtest/gtest-1.7.0/include"
    ],
    linkopts = ["-pthread"],
    visibility = ["//visibility:public"],
)

这是有点混乱：所有以gtest-1.7.0为前缀的其实都是生成的临时文件。我们可以通过new_http_archive函数中的strip_prefix属性来忽略它：

new_http_archive(
    name = "gtest",
    url = "https://googletest.googlecode.com/files/gtest-1.7.0.zip",
    sha256 = "247ca18dd83f53deb1328be17e4b1be31514cedfc1e3424f672bf11fd7e0d60d",
    build_file = "gtest.BUILD",
    strip_prefix = "gtest-1.7.0",
)

现在gtest.BUILD简洁多了：

cc_library(
    name = "main",
    srcs = glob(
        ["src/*.cc"],
        exclude = ["src/gtest-all.cc"]
    ),
    hdrs = glob([
        "include/**/*.h",
        "src/*.h"
    ]),
    copts = ["-Iexternal/gtest/include"],
    linkopts = ["-pthread"],
    visibility = ["//visibility:public"],
)

现在cc_相关的规则可以通过//external:gtest/main引用GTest了。

例如：我们可以创建以下测试：

#include "gtest/gtest.h"

TEST(FactorialTest, Negative) {
  EXPECT_EQ(1, 1);
}

创建对应的BUILD文件：

cc_test(
    name = "my_test",
    srcs = ["my_test.cc"],
    copts = ["-Iexternal/gtest/include"],
    deps = ["@gtest//:main"],
)

使用bazel test命令运行测试。

依赖预编译的库

如果要依赖一个已经编译好的库（可能只有头文件和对应的*.so库文件），可以使用cc_library规则包装一个库对象：

cc_library(
    name = "mylib",
    srcs = ["mylib.so"],
    hdrs = ["mylib.h"],
)

其它的目标就可以依赖这个包装的库对象了。

Bazel教程：构建iOS应用[翻译]

Thu, 19 May 2016 00:00:00 +0000

Bazel教程：构建iOS应用

原文：http://bazel.io/docs/tutorial/ios-app.html
译者：chai2010

本教程包含以下步骤（Bazel新用户请先参考: Bazel入门教程）：

代码预览
创建BUILD构建文件
针对模拟器构建应用
查看构建输出
在模拟器环境运行／调试应用
针对设备构建应用
安装应用到设备

需要在 Mac OS X 环境，WORKSPACE 不用配置。

查看源文件结构

iOS应用源文件在$WORKSPACE/ios-app/UrlGet目录。

代码在这里：https://github.com/bazelbuild/examples/tree/master/tutorial/ios-app/UrlGet

创建BUILD文件

在命令行用vi创建并编辑BUILD文件（其它编辑器也可以）：

$ vi $WORKSPACE/ios-app/BUILD

添加一个`objc_library`规则

Bazel针对构建iOS应用提供了诸多规则命令。在这里，我们首先使用 objc_library 规则从源文件和Xib文件构建静态库。（这个只是最小的规则，此外还有ios_application规则可以用于构建多架构的iOS应用。）

BUILD的内容如下：

objc_library(
    name = "UrlGetClasses",
    srcs = [
        "UrlGet/AppDelegate.m",
        "UrlGet/UrlGetViewController.m",
    ],
    hdrs = glob(["UrlGet/*.h"]),
    xibs = ["UrlGet/UrlGetViewController.xib"],
)

规则对应的目标名字是UrlGetClasses。

添加`objc_binary`规则

objc_binary 创建一个 bundled应用中的二进制可执行程序。

BUILD文件添加如下内容：

objc_binary(
    name = "ios-app-binary",
    srcs = [
        "UrlGet/main.m",
    ],
    deps = [
        ":UrlGetClasses",
    ],
)

其中deps属性引用了前面的UrlGetClasses静态库。

添加`ios_application`规则

ios_application 规则用于创建.ipa打包应用，同时生成Xcode过程文件。

BUILD文件添加如下内容：

ios_application(
    name = "ios-app",
    binary = ":ios-app-binary",
    infoplist = "UrlGet/UrlGet-Info.plist",
)

完整的BUILD文件在这里：https://github.com/bazelbuild/examples/blob/master/tutorial/ios-app/BUILD

构建模拟器环境的应用

命令行环境，确保当前目录对应Bazel的workspace：

$ cd $WORKSPACE

输入以下命令构建应用：

$ bazel build //ios-app:ios-app

Bazel将启动构建工作。当构建完成时，输出类似下面的信息：

INFO: Found 1 target...
Target //ios-app:ios-app up-to-date:
  bazel-bin/ios-app/ios-app.ipa
  bazel-bin/ios-app/ios-app.xcodeproj/project.pbxproj
INFO: Elapsed time: 3.765s, Critical Path: 3.44s

查找构建的输出

输出的.ipa和其它文件在$WORKSPACE/bazel-bin/ios-app目录。

模拟器环境运行／调试应用

现在可以从Xcode环境的模拟器来运行应用。先打开$WORKSPACE/bazel-bin/ios-app/ios-app.xcodeproj工程文件，然后选择相应版本的iOS模拟器，然后点击 Run 按钮运行。

注意： 如果要Xcode工程中的任何信息发生变化（比如删除文件或添加／改变依赖），必须使用Bazel重新生成Xcode工程文件。

针对设备构建应用

针对设备构建应用，需要设置bazel以找到目标对应设备的provisioning profile配置文件。根据以下步骤设置：

打开网页 Apple Profiles 下载设备对应的provisioning profile配置文件。如果又疑问，请参考 Apple’s documentation。
将profile配置文件放到$WORKSPACE/tools/objc目录。
可选操作－可以在.gitignore中忽略配置文件。

编辑 $WORKSPACE/tools/objc/BUILD 文件，添加：

  filegroup(
      name = "default_provisioning_profile",
      srcs = ["<NAME OF YOUR PROFILE>.mobileprovision"],
  )

现在可以构建针对设备的应用了：

$ bazel build //ios-app:ios-app --ios_multi_cpus=armv7,arm64

上面的命令将构建针对多个类型的设备应用。如果只需要构建真的特定类型的应用，可以指定一个特定的设备架构体系结构。

如果需要选择一个特定版本的Xcode或特定版本的SDK，可以通过--xcode_version=7.2 --ios_sdk_version=9.2指定。要确保选定版本的SDK对应的Xcode已经安装到本机。

如果需要指定一个能够运行的最小iOS版本，可以通过--ios_minimum_os=7.0指定。

安装应用到设备上

安装应用到设备最简单的方法是打开Xcode，然后点击Windows > Devices菜单。从左边列表选择相应的设备，点击 “+” 按钮并选择生成的 .ipa 文件。

如果程序没有运行，请检查设备和provisioning profile配置是否匹配。点击Devices下面的View Device Logs按钮，可以查看到相关的错误信息。

Bazel入门[翻译]

Thu, 12 May 2016 00:00:00 +0000

Bazel入门［翻译］

原文：http://bazel.io/docs/getting-started.html
译者：chai2010

安装

安装过程请参考: http://bazel.io/docs/install.html

使用工作区（workspace）

所有的Bazel构建都是基于一个 工作区（workspace） 概念，它是文件系统中一个保存了全部源代码的目录，同时还将包含一些构建后的输出目录的符号链接（例如：bazel-bin 和 bazel-out 等输出目录）。工作区目录可以随意放在哪里，但是工作区的根目录必须包含一个名为 WORKSPACE 的工作区配置文件。工作区配置文件可以是一个空文件，也可以包含引用外部构建输出所需的依赖关系。

在一个工作区内，可以根据需要共享多个项目。为了简单，我们先从只有一个项目的工作区开始介绍。

先假设你已经有了一个项目，对应 ~/gitroot/my-project/ 目录。我们先创建一个空的 ~/gitroot/my-project/WORKSPACE 工作区配置文件，用于表示这是Bazel项目对应的根目录。

创建自己的Build构建文件

使用下面的命令创建一个简单的Java项目：

$ # If you're not already there, move to your workspace directory.
$ cd ~/gitroot/my-project
$ mkdir -p src/main/java/com/example
$ cat > src/main/java/com/example/ProjectRunner.java <<EOF
package com.example;

public class ProjectRunner {
    public static void main(String args[]) {
        Greeting.sayHi();
    }
}
EOF
$ cat > src/main/java/com/example/Greeting.java <<EOF
package com.example;

public class Greeting {
    public static void sayHi() {
        System.out.println("Hi!");
    }
}
EOF

Bazel通过工作区中所有名为 BUILD 的文件来解析需要构建的项目信息，因此，我们需要先在 ~/gitroot/my-project 目录创建一个 BUILD 构建文件。下面是BUILD构建文件的内容：

# ~/gitroot/my-project/BUILD
java_binary(
    name = "my-runner",
    srcs = glob(["**/*.java"]),
    main_class = "com.example.ProjectRunner",
)

BUILD文件采用类似Python的语法。虽然不能包含任意的Python语法，但是BUILD文件中的每个构建规则看起来都象是一个Python函数调用，而且你也可以用 "#" 开头来添加单行注释。

java_binary 是一个构建规则。其中 name 对应一个构建目标的标识符，可用用它来向Bazel指定构建哪个项目。 srcs 对应一个源文件列表，Bazel需要将这些源文件编译为二进制文件。其中 glob(["**/*.java"]) 表示递归包含每个子目录中以每个 .java 为后缀名的文件。 com.example.ProjectRunner 指定包含main方法的类。

现在可以用下面的命令构建这个Java程序了：

$ cd ~/gitroot/my-project
$ bazel build //:my-runner
INFO: Found 1 target...
Target //:my-runner up-to-date:
  bazel-bin/my-runner.jar
  bazel-bin/my-runner
INFO: Elapsed time: 1.021s, Critical Path: 0.83s
$ bazel-bin/my-runner
Hi!

恭喜，你已经成功构建了第一个Bazel项目了！

添加依赖关系

对于小项目创建一个规则是可以的，但是随着项目的变大，则需要分别构建项目的不同的部件，最终再组装成产品。这种构建方式可以避免因为局部细小的修改儿导致重现构建整个应用，同时不同的构建步骤可以很好地并发执行以提高构建效率。

我们现在将一个项目拆分为两个部分独立构建，同时设置它们之间的依赖关系。基于上面的例子，我们重写了BUILD构建文件：

java_binary(
    name = "my-other-runner",
    srcs = ["src/main/java/com/example/ProjectRunner.java"],
    main_class = "com.example.ProjectRunner",
    deps = [":greeter"],
)

java_library(
    name = "greeter",
    srcs = ["src/main/java/com/example/Greeting.java"],
)

虽然源文件是一样的，但是现在Bazel将采用不同的方式来构建：首先是构建 greeter 库，然后是构建 my-other-runner。可以在构建成功后立刻运行 //:my-other-runner：

$ bazel run //:my-other-runner
INFO: Found 1 target...
Target //:my-other-runner up-to-date:
  bazel-bin/my-other-runner.jar
  bazel-bin/my-other-runner
INFO: Elapsed time: 2.454s, Critical Path: 1.58s

INFO: Running command line: bazel-bin/my-other-runner
Hi!

现在如果你改动ProjectRunner.java代码并重新构建my-other-runner目标， Greeting.java文件因为没有变化而不会重现编译。

使用多个包（Packages）

对于更大的项目，我们通常需要将它们拆分到多个目录中。你可以用类似//path/to/directory:target-name的名字引用在其他BUILD文件定义的目标。假设src/main/java/com/example/有一个cmdline/子目录，包含下面的文件：

$ mkdir -p src/main/java/com/example/cmdline
$ cat > src/main/java/com/example/cmdline/Runner.java <<EOF
package com.example.cmdline;

import com.example.Greeting;

public class Runner {
    public static void main(String args[]) {
        Greeting.sayHi();
    }
}
EOF

Runner.java依赖com.example.Greeting，因此我们需要在src/main/java/com/example/cmdline/BUILD 构建文件中添加相应的依赖规则：

# ~/gitroot/my-project/src/main/java/com/example/cmdline/BUILD
java_binary(
    name = "runner",
    srcs = ["Runner.java"],
    main_class = "com.example.cmdline.Runner",
    deps = ["//:greeter"]
)

然而，默认情况下构建目标都是私有的。也就是说，我们只能在同一个BUILD文件中被引用。这可以避免将很多实现的细节暴漏给公共的接口，但是也意味着我们需要手工允许runner所依赖的//:greeter目标。就是类似下面这个在构建runner目标时遇到的错误：

$ bazel build //src/main/java/com/example/cmdline:runner
ERROR: /home/user/gitroot/my-project/src/main/java/com/example/cmdline/BUILD:2:1:
  Target '//:greeter' is not visible from target '//src/main/java/com/example/cmdline:runner'.
  Check the visibility declaration of the former target if you think the dependency is legitimate.
ERROR: Analysis of target '//src/main/java/com/example/cmdline:runner' failed; build aborted.
INFO: Elapsed time: 0.091s

可用通过在BUILD文件增加visibility = level属性来改变目标的可间范围。下面是通过在~/gitroot/my-project/BUILD文件增加可见规则，来改变greeter目标的可见范围：

java_library(
    name = "greeter",
    srcs = ["src/main/java/com/example/Greeting.java"],
    visibility = ["//src/main/java/com/example/cmdline:__pkg__"],
)

这个规则表示//:greeter目标对于//src/main/java/com/example/cmdline包是可见的。现在我们可以重新构建runner目标程序：

$ bazel run //src/main/java/com/example/cmdline:runner
INFO: Found 1 target...
Target //src/main/java/com/example/cmdline:runner up-to-date:
  bazel-bin/src/main/java/com/example/cmdline/runner.jar
  bazel-bin/src/main/java/com/example/cmdline/runner
INFO: Elapsed time: 1.576s, Critical Path: 0.81s

INFO: Running command line: bazel-bin/src/main/java/com/example/cmdline/runner
Hi!

参考文档中有可见性配置说明。

部署

如果你查看 bazel-bin/src/main/java/com/example/cmdline/runner.jar 的内容，可以看到里面只包含了Runner.class，并没有保护所依赖的Greeting.class：

$ jar tf bazel-bin/src/main/java/com/example/cmdline/runner.jar
META-INF/
META-INF/MANIFEST.MF
com/
com/example/
com/example/cmdline/
com/example/cmdline/Runner.class

这只能在本机正常工作（因为Bazel的runner脚本已经将greeter jar添加到了classpath），但是如果将runner.jar单独复制到另一台机器上讲不能正常运行。如果想要构建可用于部署发布的自包含所有依赖的目标，可以构建runner_deploy.jar目标（类似<target-name>_deploy.jar以_deploy为后缀的名字对应可部署目标）。

$ bazel build //src/main/java/com/example/cmdline:runner_deploy.jar
INFO: Found 1 target...
Target //src/main/java/com/example/cmdline:runner_deploy.jar up-to-date:
  bazel-bin/src/main/java/com/example/cmdline/runner_deploy.jar
INFO: Elapsed time: 1.700s, Critical Path: 0.23s

runner_deploy.jar中将包含全部的依赖。

下一步

现在，您可以创建自己的目标并组装最终产品了。接下来，可查看相关教程分别学习如何用Bazel构建一个服务器、Android和iOS应用。也可以参考构建百科和用户手册获得更多的信息。如果有问题的话，可以到 bazel-discuss 论坛提问。