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

Các phần trước đã mô tả các 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 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 một ngôn ngữ mệnh lệnh, Starlark.

Các câu lệnh này được diễn giải dưới dạng danh sách tuần tự các câu lệnh.

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

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

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

Để khuyến khích việc tách biệt 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 cho phép câu lệnh liệt kê và biểu thức if). Thay vào đó, bạn có thể khai báo hàm trong các tệp .bzl. Ngoài ra, các đối số *args và **kwargs không được phép trong tệp BUILD; thay vào đó, hãy liệt kê tất cả các đối số một cách rõ ràng.

Quan trọng là các chương trình trong Starlark không thể thực hiện I/O tuỳ ý. Biến không đổi này giúp việc diễn giải các tệp BUILD trở nên kín đáo – chỉ phụ thuộc vào một tập hợp đầu vào đã biết, điều này rất 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 chi tiết, hãy xem phần Hermeticity.

Bạn chỉ nên viết tệp BUILD bằng 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 chú thích một cách tự do để ghi lại 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 đích sử dụng công khai hay không, cũng như để ghi lại vai trò của chính gói đó.

Tải tiện ích

Tiện ích Bazel là các tệp có đuôi .bzl. Sử dụng câu lệnh load để nhập một ký hiệu 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 phương thức 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 danh sách). Bạn có thể nhập nhiều ký hiệu 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, nhãn đó 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. Nhãn tương đối trong câu lệnh load phải sử dụng : ở đầu.

load cũng hỗ trợ bí danh, do đó, bạn có thể chỉ định 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 ký hiệu thông thường. Ví dụ sau đây hoàn toàn hợp pháp (vui lòng lưu ý thời điểm 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 ký hiệu 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 chế độ hiển thị tải để hạn chế 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 các gia đình, đượ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 bản 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 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 Bách khoa toàn thư về bản dựng, nhưng mọi người đều có thể tạo 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ụ bản dựng ở tên tương ứng với nhãn của quy tắc, vì vậy //my:program sẽ xuất hiện tại (ví dụ:) $(BINDIR)/my/program.

  Trong một số ngôn ngữ, các quy tắc như vậy cũng tạo một thư mục runfiles chứa tất cả các 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 phần đóng chuyển đổi của các phần phụ thuộc; tập hợp tệp này được tập hợp lại ở một nơi để dễ dàng triển khai cho bản phát hành chính thức.

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

  Giống như tệp nhị phân, các chương trình kiểm thử cũng có cây tệp chạy 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ở một cách 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ó hàm tiện ích riêng để truy cập vào giá trị của $TEST_SRCDIR, nhưng tất cả đề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, quá trình kiểm thử sẽ không thành công khi được thực thi trên máy chủ kiểm thử từ xa.

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