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

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

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 cho bản dựng một cách trừu tượng. Phần này mô tả cú pháp cụ thể được 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 diễn giải là danh sách câu lệnh tuần tự.

Nhìn chung, thứ tự là quan trọng: 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 nội dung khai báo của 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 những giá trị nào, khi 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, hàm này sẽ tạo một mục tiêu mới trong biểu đồ. Bạn có thể gọi 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ể 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.

Để khuyến khích việc phân tách rõ ràng mã và dữ liệu, các 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 bạn được phép đọc hiểu danh sách và biểu thức if). Thay vào đó, bạn có thể khai báo các hàm trong tệp .bzl. Ngoài ra, bạn không được phép sử dụng đối số *args và **kwargs trong các 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.

Điều quan trọng là các chương trình trong Starlark không thể thực hiện I/O tùy ý. Tính bất biến này giúp việc diễn giải các tệp BUILD là khép kín — chỉ phụ thuộc vào một tập hợp các dữ liệu đầu vào đã biết, điều này 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 chi tiết, hãy xem phần Độ khó.

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 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 mã cơ bản thay đổi nên các tệp này thường được nhiều người trong một nhóm duy trì. Các 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, cho dù mục đích là để sử dụng công khai hay không, và ghi lại vai trò của gói đó.

Đang tải tiện ích

Đuôi tệp 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ể sử dụng đối tượng này để tải 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 thể 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 đối với 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 tên 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 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 _ 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 tải chế độ hiển thị để hạn chế người 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 xuất hiện trong nhóm gia đình, được nhóm 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 dành cho tệp nhị phân, thư viện và kiểm thử C++. Các ngôn ngữ khác cũng sử dụng cùng 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 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 thực thi bằng một ngôn ngữ cụ thể. 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ụ xây dựng tại 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.

    Ở một số ngôn ngữ, các quy tắc đó 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 một tập hợp bắc cầu 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 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ử là chương trình đơn giản 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ác cây chạy (filefile tree) và các tệp bên dưới là các tệp duy nhất mà một chương trình kiểm thử có thể mở một cách hợp pháp 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 có một 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, 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 bằng ngôn ngữ lập trình đã cho. Thư viện có thể phụ thuộc vào các thư viện khác, còn tệp nhị phân và chương trình kiểm thử có thể phụ thuộc vào thư viện, với hành vi biên dịch riêng dự kiến.

Nhãn Phần phụ thuộc