Hướng dẫn của Bazel: Xây dựng dự án C++

Báo cáo vấn đề Xem nguồn Hằng đêm · 7,4 của Google. 7.3 · 7.2 · 7.1 · 7 · 6,5

Giới thiệu

Bạn mới sử dụng Bazel? Bạn đã tìm đến đúng nơi. Hãy làm theo hướng dẫn Tạo đầu tiên này để biết hướng dẫn đơn giản về cách sử dụng Bazel. Hướng dẫn này định nghĩa các thuật ngữ chính vì chúng được sử dụng trong bối cảnh của Bazel và hướng dẫn bạn tìm hiểu những thông tin cơ bản về Bazel quy trình công việc. Bắt đầu với các công cụ cần thiết, bạn sẽ xây dựng và chạy 3 dự án có độ phức tạp tăng dần, đồng thời tìm hiểu cách thức và lý do các dự án này trở nên phức tạp hơn.

Mặc dù Bazel là một hệ thống xây dựng hỗ trợ các bản dựng đa ngôn ngữ, hướng dẫn này sẽ dùng một dự án C++ làm ví dụ đồng thời cung cấp các nguyên tắc và quy trình chung áp dụng cho hầu hết các ngôn ngữ.

Thời gian hoàn thành ước tính: 30 phút.

Điều kiện tiên quyết

Bắt đầu bằng cách cài đặt Bazel, nếu bạn chưa cài đặt. Hướng dẫn này sử dụng Git để kiểm soát nguồn, vì vậy, để có kết quả tốt nhất, hãy cài đặt Git.

Tiếp theo, hãy truy xuất dự án mẫu từ kho lưu trữ GitHub của Bazel bằng cách chạy lệnh sau trong công cụ dòng lệnh mà bạn chọn:

git clone https://github.com/bazelbuild/examples

Dự án mẫu cho hướng dẫn này nằm trong thư mục examples/cpp-tutorial.

Hãy xem phần dưới đây để biết cấu trúc của chiến dịch:

examples
└── cpp-tutorial
    ├──stage1
    │  ├── main
    │  │   ├── BUILD
    │  │   └── hello-world.cc
    │  └── WORKSPACE
    ├──stage2
    │  ├── main
    │  │   ├── BUILD
    │  │   ├── hello-world.cc
    │  │   ├── hello-greet.cc
    │  │   └── hello-greet.h
    │  └── WORKSPACE
    └──stage3
       ├── main
       │   ├── BUILD
       │   ├── hello-world.cc
       │   ├── hello-greet.cc
       │   └── hello-greet.h
       ├── lib
       │   ├── BUILD
       │   ├── hello-time.cc
       │   └── hello-time.h
       └── WORKSPACE

Có ba tập hợp tệp, mỗi tập đại diện cho một giai đoạn trong hướng dẫn này. Ở giai đoạn đầu tiên, bạn sẽ tạo một mục tiêu duy nhất nằm trong một gói duy nhất. Ở giai đoạn thứ hai, bạn sẽ tạo cả tệp nhị phân và thư viện từ một gói duy nhất. Ở bước thứ ba và cuối cùng, bạn sẽ tạo một dự án có nhiều gói và tạo dự án đó với nhiều mục tiêu.

Tóm tắt: Giới thiệu

Bằng cách cài đặt Bazel (và Git) và nhân bản kho lưu trữ cho hướng dẫn này, bạn đã đặt nền tảng cho bản dựng đầu tiên của mình bằng Bazel. Chuyển đến phần tiếp theo để xác định một số điều khoản và thiết lập không gian làm việc của bạn.

Bắt đầu

Thiết lập không gian làm việc

Trước khi có thể tạo một dự án, bạn cần thiết lập không gian làm việc của dự án đó. Không gian làm việc là một thư mục lưu giữ các tệp nguồn của dự án và dữ liệu đầu ra của bản dựng của Bazel. Tệp này cũng chứa các tệp quan trọng sau:

  • WORKSPACE file giúp xác định thư mục và nội dung trong thư mục là một không gian làm việc Bazel và nằm ở gốc cấu trúc thư mục của dự án.
  • Một hoặc nhiều BUILD files cho Bazel biết cách tạo các phần khác nhau của dự án. Thư mục trong không gian làm việc chứa tệp BUILD là một gói. (Thông tin khác về các gói ở phần sau của hướng dẫn này).

Trong các dự án sau này, để chỉ định một thư mục làm không gian làm việc Bazel, hãy tạo một tệp trống có tên là WORKSPACE trong thư mục đó. Trong phạm vi của hướng dẫn này, một tệp WORKSPACE đã có trong mỗi giai đoạn.

LƯU Ý: Khi Bazel tạo dự án, tất cả dữ liệu đầu vào phải nằm trong cùng một không gian làm việc. Các tệp nằm trong các không gian làm việc khác nhau sẽ độc lập với nhau trừ khi được liên kết. Bạn có thể tìm thêm thông tin chi tiết về quy tắc của không gian làm việc trong hướng dẫn này.

Tìm hiểu về tệp BUILD

Tệp BUILD chứa một số loại hướng dẫn cho Bazel. Một Tệp BUILD cần có ít nhất một quy tắc như một tập hợp các lệnh, hướng dẫn cho Bazel cách xây dựng các đầu ra mong muốn, chẳng hạn như tệp nhị phân hoặc thư viện có thể thực thi. Mỗi thực thể của quy tắc bản dựng trong Tệp BUILD được gọi là mục tiêu và trỏ đến một tập hợp tệp nguồn và dependencies cụ thể. Một mục tiêu cũng có thể trỏ đến các mục tiêu khác.

Hãy xem tệp BUILD trong thư mục cpp-tutorial/stage1/main:

cc_binary(
    name = "hello-world",
    srcs = ["hello-world.cc"],
)

Trong ví dụ của chúng ta, mục tiêu hello-world tạo bản sao cho cc_binary rule tích hợp của Bazel. Quy tắc này yêu cầu Bazel tạo một tệp nhị phân thực thi độc lập từ tệp nguồn hello-world.cc mà không có phần phụ thuộc nào.

Tóm tắt: bắt đầu

Giờ đây, bạn đã nắm được một số thuật ngữ chính và ý nghĩa của các thuật ngữ đó trong dự án này và nói chung là Bazel. Trong phần tiếp theo, bạn sẽ xây dựng và kiểm thử Giai đoạn 1 của dự án.

Giai đoạn 1: một mục tiêu, một gói

Đã đến lúc xây dựng phần đầu tiên của dự án. Để tham khảo trực quan, cấu trúc của phần Giai đoạn 1 của dự án là:

examples
└── cpp-tutorial
    └──stage1
       ├── main
       │   ├── BUILD
       │   └── hello-world.cc
       └── WORKSPACE

Chạy lệnh sau để chuyển đến thư mục cpp-tutorial/stage1:

cd cpp-tutorial/stage1

Tiếp theo, hãy chạy:

bazel build //main:hello-world

Trong nhãn mục tiêu, phần //main: là vị trí của tệp BUILD so với thư mục gốc của không gian làm việc và hello-world là tên mục tiêu trong tệp BUILD.

Bazel tạo ra thành phần có dạng như sau:

INFO: Found 1 target...
Target //main:hello-world up-to-date:
  bazel-bin/main/hello-world
INFO: Elapsed time: 2.267s, Critical Path: 0.25s

Bạn vừa tạo mục tiêu Bazel đầu tiên của mình. Bazel đặt đầu ra bản dựng trong thư mục bazel-bin ở thư mục gốc của không gian làm việc.

Bây giờ, hãy kiểm thử tệp nhị phân được tạo mới, đó là:

bazel-bin/main/hello-world

Thao tác này sẽ in ra thông báo "Hello world".

Sau đây là biểu đồ phần phụ thuộc của Giai đoạn 1:

Biểu đồ phần phụ thuộc cho hello-world hiển thị một mục tiêu duy nhất với một tệp nguồn duy nhất.

Tóm tắt: giai đoạn 1

Giờ đây, khi đã hoàn tất bản dựng đầu tiên, bạn đã có ý tưởng cơ bản về cấu trúc của một bản dựng. Ở giai đoạn tiếp theo, bạn sẽ tăng độ phức tạp bằng cách thêm một mục tiêu khác.

Giai đoạn 2: nhiều mục tiêu bản dựng

Mặc dù một mục tiêu duy nhất là đủ cho các dự án nhỏ, nhưng bạn có thể muốn tách các dự án lớn hơn thành nhiều mục tiêu và gói. Điều này cho phép các bản dựng tăng dần – tức là Bazel chỉ xây dựng lại những nội dung thay đổi – và đẩy nhanh tốc độ của bằng cách xây dựng nhiều phần của dự án cùng một lúc. Giai đoạn này của hướng dẫn sẽ thêm một mục tiêu và giai đoạn tiếp theo sẽ thêm một gói.

Đây là thư mục bạn đang làm việc cho Giai đoạn 2:

    ├──stage2
    │  ├── main
    │  │   ├── BUILD
    │  │   ├── hello-world.cc
    │  │   ├── hello-greet.cc
    │  │   └── hello-greet.h
    │  └── WORKSPACE

Hãy xem tệp BUILD ở bên dưới trong thư mục cpp-tutorial/stage2/main:

cc_library(
    name = "hello-greet",
    srcs = ["hello-greet.cc"],
    hdrs = ["hello-greet.h"],
)

cc_binary(
    name = "hello-world",
    srcs = ["hello-world.cc"],
    deps = [
        ":hello-greet",
    ],
)

Với tệp BUILD này, trước tiên, Bazel sẽ tạo thư viện hello-greet (sử dụng cc_library rule tích hợp của Bazel), sau đó là tệp nhị phân hello-world. Thuộc tính deps trong mục tiêu hello-world cho Bazel biết rằng hello-greet cần có thư viện để tạo tệp nhị phân hello-world.

Trước khi có thể tạo phiên bản mới của dự án này, bạn cần thay đổi thư mục, chuyển sang thư mục cpp-tutorial/stage2 bằng cách chạy:

cd ../stage2

Giờ đây, bạn có thể tạo tệp nhị phân mới bằng lệnh quen thuộc sau:

bazel build //main:hello-world

Một lần nữa, Bazel tạo ra thành phần như sau:

INFO: Found 1 target...
Target //main:hello-world up-to-date:
  bazel-bin/main/hello-world
INFO: Elapsed time: 2.399s, Critical Path: 0.30s

Bây giờ, bạn có thể kiểm thử tệp nhị phân mới tạo và tệp này sẽ trả về một "Hello world" khác:

bazel-bin/main/hello-world

Nếu bạn sửa đổi hello-greet.cc và tạo lại dự án, Bazel sẽ chỉ biên dịch lại tệp đó.

Khi xem biểu đồ phần phụ thuộc, bạn có thể thấy hello-world phụ thuộc vào một đầu vào bổ sung tên là hello-greet:

Biểu đồ phần phụ thuộc cho "hello-world" hiển thị các thay đổi về phần phụ thuộc sau khi sửa đổi tệp.

Tóm tắt: giai đoạn 2

Bây giờ, bạn đã tạo dự án với hai mục tiêu. Mục tiêu hello-world tạo một tệp nguồn và phụ thuộc vào một mục tiêu khác (//main:hello-greet), mục tiêu này tạo thêm hai tệp nguồn. Trong phần tiếp theo, hãy tiến thêm một bước và thêm một gói khác.

Giai đoạn 3: nhiều gói

Giai đoạn tiếp theo này thêm một lớp chức năng khác và tạo dự án có nhiều gói. Hãy xem cấu trúc và nội dung của phần dưới đây Thư mục cpp-tutorial/stage3:

└──stage3
   ├── main
   │   ├── BUILD
   │   ├── hello-world.cc
   │   ├── hello-greet.cc
   │   └── hello-greet.h
   ├── lib
   │   ├── BUILD
   │   ├── hello-time.cc
   │   └── hello-time.h
   └── WORKSPACE

Bạn có thể thấy rằng hiện có hai thư mục con, trong đó mỗi thư mục chứa một BUILD . Do đó, đối với Bazel, không gian làm việc hiện chứa 2 gói: lib và main.

Hãy xem tệp lib/BUILD:

cc_library(
    name = "hello-time",
    srcs = ["hello-time.cc"],
    hdrs = ["hello-time.h"],
    visibility = ["//main:__pkg__"],
)

Và tại tệp main/BUILD:

cc_library(
    name = "hello-greet",
    srcs = ["hello-greet.cc"],
    hdrs = ["hello-greet.h"],
)

cc_binary(
    name = "hello-world",
    srcs = ["hello-world.cc"],
    deps = [
        ":hello-greet",
        "//lib:hello-time",
    ],
)

Mục tiêu hello-world trong gói chính phụ thuộc vào mục tiêu hello-time trong gói lib (do đó, nhãn mục tiêu là //lib:hello-time) – Bazel biết điều này thông qua thuộc tính deps. Bạn có thể thấy điều này được phản ánh trong biểu đồ phần phụ thuộc:

Biểu đồ phần phụ thuộc cho "hello-world" cho biết cách mục tiêu trong gói chính phụ thuộc vào mục tiêu trong gói "lib".

Để bản dựng thành công, bạn phải làm cho mục tiêu //lib:hello-time trong lib/BUILD hiển thị rõ ràng cho các mục tiêu trong main/BUILD bằng cách sử dụng thuộc tính chế độ hiển thị. Lý do là theo mặc định, các mục tiêu chỉ hiển thị với các mục tiêu khác trong cùng một tệp BUILD. Bazel sử dụng chế độ hiển thị mục tiêu để ngăn chặn các vấn đề như thư viện chứa chi tiết triển khai bị rò rỉ vào API công khai.

Bây giờ, hãy tạo phiên bản cuối cùng của dự án này. Chuyển sang thư mục cpp-tutorial/stage3 bằng cách chạy:

cd  ../stage3

Chạy lại lệnh sau:

bazel build //main:hello-world

Bazel tạo ra thành phần có dạng như sau:

INFO: Found 1 target...
Target //main:hello-world up-to-date:
  bazel-bin/main/hello-world
INFO: Elapsed time: 0.167s, Critical Path: 0.00s

Bây giờ, hãy kiểm tra tệp nhị phân cuối cùng của hướng dẫn này để biết thông báo Hello world cuối cùng:

bazel-bin/main/hello-world

Tóm tắt: giai đoạn 3

Giờ đây, bạn đã tạo dự án dưới dạng hai gói với ba mục tiêu và hiểu rõ các phần phụ thuộc giữa các gói đó. Điều này giúp bạn có thể tiếp tục và tạo các dự án trong tương lai bằng Bazel. Trong phần tiếp theo, hãy xem cách tiếp tục hành trình sử dụng Bazel.

Các bước tiếp theo

Giờ đây, bạn đã hoàn tất bản dựng cơ bản đầu tiên bằng Bazel, nhưng đây mới chỉ là bước khởi đầu. Dưới đây là một số tài nguyên khác để tiếp tục tìm hiểu cùng Bazel:

Chúc bạn xây dựng vui vẻ!