XÂY DỰNG các tệp

Báo cáo vấn đề Xem nguồn Nightly .

Các phần trước đã mô tả gói, mục tiêu và nhãn, cũng như biểu đồ phần phụ thuộc bản dựng một cách trừu tượng. Phần này mô tả cú pháp cụ thể dùng để xác định một gói.

Theo định nghĩa, mỗi gói đều chứa một tệp BUILD. Đây là một chương trình ngắn.

Các tệp BUILD được đánh giá bằng ngôn ngữ bắt buộc là Starlark.

Chúng được hiểu là một danh sách câu lệnh tuần tự.

Nhìn chung, thứ tự rất quan trọng: chẳng hạn như bạn phải xác định các biến trước khi sử dụng chúng. Tuy nhiên, hầu hết các tệp BUILD chỉ bao gồm nội dung khai báo theo quy tắc xây dựng và thứ tự tương đối của các câu lệnh này là không quan trọng; tất cả những gì quan trọng là quy tắc điều gì được khai báo và giá trị nào được khai báo vào thời điểm hoàn tất đánh giá gói.

Khi thực thi một hàm quy tắc bản dựng, chẳng hạn như cc_library, mục tiêu mới trong biểu đồ sẽ được tạo. Sau đó, bạn có thể tham chiếu mục tiêu này bằng cách sử dụng nhãn.

Trong các tệp BUILD đơn giản, bạn có thể thoải mái sắp xếp lại các nội dung khai báo quy tắc mà không cần thay đổi hành vi.

Để phân tách rõ ràng giữa mã và dữ liệu, tệp BUILD không được chứa định nghĩa hàm, câu lệnh for hoặc câu lệnh if (nhưng vẫn có thể hiểu danh sách và biểu thức if). Thay vào đó, bạn có thể khai báo hàm trong tệp .bzl. Ngoài ra, các đối số *args và **kwargs không được cho phép trong tệp BUILD; thay vào đó, hãy liệt kê rõ ràng tất cả các đối số.

Điều quan trọng là các chương trình trong Starlark không thể thực hiện I/O tuỳ ý. Bất biến này khiến việc diễn giải các tệp BUILD ở chế độ ẩn – chỉ phụ thuộc vào một tập hợp dữ liệu đầu vào đã biết. Đây là điều cần thiết để đảm bảo rằng các bản dựng có thể tái tạo. Để biết thêm thông tin, hãy xem bài viết Độ trễ.

Tệp BUILD chỉ nên được viết bằng các ký tự ASCII, mặc dù về mặt kỹ thuật, các tệp này được diễn giải bằng bộ ký tự Latin-1.

Vì các tệp BUILD cần được cập nhật bất cứ khi nào các phần phụ thuộc của mã cơ sở thay đổi, nên các tệp này thường do nhiều người trong một nhóm duy trì. Tác giả tệp BUILD nên thoải mái nhận xét để ghi nhận vai trò của từng mục tiêu bản dựng, cho dù mục tiêu đó có dành cho mục tiêu sử dụng công khai hay không và để ghi nhận vai trò của chính gói đó.

Đang tải một tiện ích

Đuôi Bazel là các tệp có đuôi là .bzl. Sử dụng câu lệnh load để nhập biểu tượng từ một tiện ích.

load("//foo/bar:file.bzl", "some_library")

Mã này tải tệp foo/bar/file.bzl và thêm biểu tượng some_library vào môi trường. Bạn có thể dùng tính năng này để tải các quy tắc, hàm hoặc hằng số mới (ví dụ: một chuỗi hoặc một danh sách). Bạn có thể nhập nhiều biểu tượng bằng cách sử dụng các đối số bổ sung cho lệnh gọi đến load. Đối số phải là giá trị cố định kiểu chuỗi (không có biến) và câu lệnh load phải xuất hiện ở cấp cao nhất – không được nằm trong phần nội dung của hàm.

Đối số đầu tiên của load là một nhãn xác định tệp .bzl. Nếu là nhãn tương đối, thì nhãn này sẽ được phân giải theo gói (không phải thư mục) chứa tệp bzl hiện tại. Các nhãn tương đối trong câu lệnh load phải sử dụng : đứng đầu.

load cũng hỗ trợ bí danh, do đó, bạn có thể chỉ định các tên khác nhau cho các biểu tượng đã nhập.

load("//foo/bar:file.bzl", library_alias = "some_library")

Bạn có thể xác định nhiều bí danh trong một câu lệnh load. Hơn nữa, danh sách đối số có thể chứa cả bí danh và tên biểu tượng thông thường. Ví dụ sau là hoàn toàn hợp pháp (vui lòng lưu ý khi nào sử dụng dấu ngoặc kép).

load(":my_rules.bzl", "some_rule", nice_alias = "some_other_rule")

Trong tệp .bzl, các biểu tượng bắt đầu bằng _ sẽ không được xuất và không thể tải từ một tệp khác.

Bạn có thể sử dụng tính năng chế độ hiển thị tải để hạn chế những người có thể tải tệp .bzl.

Các loại quy tắc bản dựng

Phần lớn các quy tắc bản dựng đều thuộc về gia đình và được nhóm lại với nhau theo ngôn ngữ. Ví dụ: cc_binary, cc_library và cc_test lần lượt là các quy tắc xây dựng cho tệp nhị phân, thư viện và kiểm thử C++. Các ngôn ngữ khác sử dụng cùng một lược đồ đặt tên, với một tiền tố khác, chẳng hạn như java_* cho Java. Một số hàm trong số này được ghi lại trong Build Encyclopedia (Tạo Bách khoa toàn thư), nhưng bất kỳ ai cũng có thể tạo các quy tắc mới.

  • Quy tắc *_binary tạo các chương trình có thể thực thi bằng một ngôn ngữ nhất định. Sau khi tạo bản dựng, tệp thực thi sẽ nằm trong cây đầu ra nhị phân của công cụ tạo tại tên tương ứng của nhãn của quy tắc, vì vậy, //my:program sẽ xuất hiện tại (chẳng hạn) $(BINDIR)/my/program.

    Ở một số ngôn ngữ, các quy tắc như vậy cũng tạo ra một thư mục runfile chứa mọi tệp được đề cập trong thuộc tính data thuộc quy tắc đó, hoặc bất kỳ quy tắc nào trong trạng thái đóng bắc cầu của các phần phụ thuộc; tập hợp các tệp này được tập hợp ở cùng một nơi để dễ dàng triển khai cho môi trường thực tế.

  • Quy tắc *_test là một chuyên môn của quy tắc *_binary, dùng để kiểm thử tự động. Kiểm thử chỉ đơn giản là những chương trình trả về 0 khi thành công.

    Giống như tệp nhị phân, chương trình kiểm thử cũng có cây runfile và các tệp bên dưới đó là những tệp duy nhất mà chương trình kiểm thử có thể mở hợp lệ trong thời gian chạy. Ví dụ: chương trình cc_test(name='x', data=['//foo:bar']) có thể mở và đọc $TEST_SRCDIR/workspace/foo/bar trong quá trình thực thi. (Mỗi ngôn ngữ lập trình đều có một hàm hiệu dụng riêng để truy cập vào giá trị của $TEST_SRCDIR, nhưng tất cả các hàm đó đều tương đương với việc sử dụng trực tiếp biến môi trường.) Nếu không tuân thủ quy tắc này, quy trình kiểm thử sẽ không thành công khi được thực thi trên một máy chủ kiểm thử từ xa.

  • Các quy tắc *_library chỉ định các mô-đun được biên dịch riêng bằng ngôn ngữ lập trình đã cho. Các thư viện có thể phụ thuộc vào các thư viện khác, đồng thời các tệp nhị phân và kiểm thử có thể phụ thuộc vào các thư viện với hành vi biên dịch riêng dự kiến.

Nhãn Phần phụ thuộc