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

Sử dụng bộ sưu tập để sắp xếp ngăn nắp các trang Lưu và phân loại nội dung dựa trên lựa chọn ưu tiên của bạn.
Báo cáo sự cố Xem nguồn

Các phần trước mô tả các gói, mục tiêu và nhãn, đồng thời trình bày 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, 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, Starlark.

Các câu lệnh này được hiểu là danh sách tuần tự câu lệnh.

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

Khi một hàm quy tắc xây 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 đó, bạn có thể gọi mục tiêu này bằng nhãn.

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

Để khuyến khích 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 được phép đọc danh sách và biểu thức if). Bạn có thể khai báo các hàm trong tệp .bzl. Ngoài ra, các đối số *args**kwargs không được phép trong các 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ỳ ý. Biến thể này giúp diễn giải các tệp BUILD một cách khép kín — 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, hãy xem phần Độ dày.

Bạn chỉ nên viết các tệp BUILD 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 cách sử dụng bộ ký tự Latin-1.

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

Đang tải một 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 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 thuộc tính 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 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 – các đối số này không được nằm trong phần nội dung hàm.

Đối số đầu tiên của load là một nhãn xác định tệp .bzl. Nếu đó là một nhãn tương đối, thì 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. Các nhãn tương đối trong các câu lệnh load nên sử dụng : ở đầu.

load cũng hỗ trợ các 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 đây là 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 biểu tượng bắt đầu bằng _ 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 tải chế độ hiển thị để hạn chế đối tượng có thể tải tệp .bzl.

Các loại quy tắc xây dựng

Phần lớn các quy tắc xây dựng đều xuất hiện trong các gia đình, được nhóm với nhau theo ngôn ngữ. Ví dụ: cc_binary, cc_librarycc_test lần lượt là các quy tắc xây dựng cho các 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ư xây dựng , nhưng mọi người cũng có thể tạo quy tắc mới.

  • Quy tắc *_binary tạo các chương trình thực thi bằng một ngôn ngữ cụ thể. Sau khi 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ụ xây dựng tại tên tương ứng cho nhãn của quy tắc, do đó //my:program sẽ xuất hiện tại (ví dụ) $(BINDIR)/my/program.

    Ở một số ngôn ngữ, những quy tắc này cũng tạo một thư mục runfiles chứa tất cả các tệp đề 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 cửa bắc cầu phụ thuộc; tập hợp các tệp này được tập hợp cùng nhau ở một nơi để dễ dàng triển khai trong quá trình sản xuất.

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

    Giống như tệp nhị phân, kiểm thử cũng có cây chạy tệp và các tệp bên dưới tệp là tệp duy nhất mà kiểm thử có thể mở một cách hợp lệ trong thời gian chạy. Ví dụ: một 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 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.) Việc không tuân thủ quy tắc sẽ khiến kiểm thử không đạt 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 bằng ngôn ngữ lập trình nhất định. Các thư viện có thể phụ thuộc vào các thư viện khác, các tệp nhị phân và kiểm thử có thể phụ thuộc vào hành vi biên dịch riêng dự kiến.

Nhãn Phần phụ thuộc