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

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

Các phần trước đã mô tả gói, mục tiêu và nhãn, cũng như tạo biểu đồ phần phụ thuộc 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, là một .

Lưu ý: Bạn có thể đặt tên tệp BUILD là BUILD hoặc BUILD.bazel. Nếu cả hai có tệp nào tồn tại, thì BUILD.bazel sẽ được ưu tiên hơn BUILD. Để cho đơn giản, tài liệu này chỉ đề cập đến các tệp này dưới dạng BUILD tệp.

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

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

Nói chung, thứ tự rất quan trọng: bạn phải xác định biến trước khi chúng được sử dụng. Tuy nhiên, hầu hết các tệp BUILD chỉ bao gồm nội dung khai báo của các 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ả điều quan trọng là quy tắc nào được khai báo và với giá trị nào được hoàn tất đánh giá gói thời gian.

Khi thực thi một hàm quy tắc bản dựng, chẳng hạn như cc_library, hàm này sẽ tạo một mục tiêu mới trong biểu đồ. 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 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 danh sách mức hiểu bài và biểu thức if). Các hàm có thể được khai báo trong Thay vào đó, .bzl tệp. Ngoài ra, các đối số *args và **kwargs không được được phép sử dụng trong BUILD tệp; 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 làm cho việc diễn giải tệp BUILD ở chế độ kín — chỉ phụ thuộc vào các dữ liệu tập hợp đầu vào, cần thiết để đảm bảo rằng các bản dựng có thể tái tạo được. Để biết thêm thông tin, hãy xem bài viết Hermeticity.

Tệp BUILD chỉ được viết bằng các ký tự ASCII, mặc dù về mặt kỹ thuật, chúng được diễn giải bằng cách sử dụ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 phần phụ thuộc của thay đổi mã cơ bản, chúng thường được nhiều người duy trì trên một . BUILD tác giả tệp nên thoải mái nhận xét để ghi lại vai trò này 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 cộng hay không và ghi lại 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 một biểu tượng trên 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 đối với môi trường. Hàm này có thể được dùng để 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). 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 — chúng không được trong phần nội dung hàm.

Đối số đầu tiên của load là một nhãn xác định .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. Nhãn tương đối ở Các 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 ký hiệu được 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. Nội dung sau đây ví dụ 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 được được 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ế 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 xây dựng đều thuộc về gia đình, được nhóm với nhau theo ngôn ngữ. Ví dụ: cc_binary, cc_library và cc_test là quy tắc xây dựng cho tệp nhị phân C++, thư viện và bài kiểm thử tương ứng. Các ngôn ngữ khác cũng sử dụng cùng một ngôn ngữ 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ố chức năng trong số này được ghi lại trong Xây dựng Bách khoa toàn thư, nhưng có thể cho bất kỳ ai 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 một bản dựng, tệp thực thi sẽ nằm trong tệp nhị phân của công cụ xây dựng cây đầu ra tại tên tương ứng với nhãn của quy tắc, nên //my:program sẽ xuất hiện tại (ví dụ) $(BINDIR)/my/program.

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

• Quy tắc *_test là một chuyên môn của quy tắc *_binary, được dùng để tự động hoá kiểm thử. 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, kiểm thử cũng có cây runfile và 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ở 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 có hàm số hiệu dụng riêng cho đang truy cập vào giá trị của $TEST_SRCDIR, nhưng tất cả đều là tương đương với việc sử dụng trực tiếp biến môi trường). Việc không tuân thủ quy tắc sẽ khiến bài kiểm thử không thành công thực thi trên một 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 trong ngôn ngữ lập trình. Các thư viện có thể phụ thuộc vào các thư viện khác, cũng như tệp nhị phân và kiểm thử có thể phụ thuộc vào thư viện, với biên dịch riêng biệt.

Nhãn	Phần phụ thuộc