Nhãn là giá trị nhận dạng của một mục tiêu. Một nhãn điển hình ở dạng chính tắc đầy đủ sẽ có dạng như sau:
@@myrepo//my/app/main:app_binary
Phần đầu tiên của nhãn là tên kho lưu trữ, @@myrepo. Cú pháp @ kép cho biết đây là tên kho lưu trữ chính tắc, là tên duy nhất trong không gian làm việc. Nhãn có tên kho lưu trữ chính tắc đều xác định rõ ràng một mục tiêu bất kể chúng xuất hiện trong bối cảnh nào.
Thông thường, tên kho lưu trữ chuẩn là một chuỗi arcane có dạng như @@rules_java~7.1.0~toolchains~local_jdk. Thông thường, nhãn có tên kho lưu trữ rõ ràng sẽ có dạng như sau:
@myrepo//my/app/main:app_binary
Điểm khác biệt duy nhất là tên kho lưu trữ có tiền tố @ thay vì 2.
Đây là một kho lưu trữ có tên rõ ràng là myrepo. Tên này có thể khác tuỳ theo ngữ cảnh xuất hiện của nhãn này.
Trong trường hợp thông thường, nhãn tham chiếu đến cùng một kho lưu trữ mà nhãn được sử dụng, phần tên kho lưu trữ có thể bị bỏ qua. Vì vậy, bên trong @@myrepo, nhãn đầu tiên
thường được viết là
//my/app/main:app_binary
Phần thứ hai của nhãn là tên gói không đủ điều kiện my/app/main, đường dẫn đến gói liên quan đến thư mục gốc của kho lưu trữ. Tên kho lưu trữ và tên gói không đủ điều kiện cùng nhau tạo thành tên gói đủ điều kiện @@myrepo//my/app/main. Khi nhãn tham chiếu đến cùng một gói đang sử dụng, thì tên gói (và dấu hai chấm không bắt buộc) có thể bị bỏ qua. Vì vậy, bên trong @@myrepo//my/app/main, bạn có thể viết nhãn này theo một trong các cách sau:
app_binary
:app_binary
Theo quy ước, dấu hai chấm bị bỏ qua đối với các tệp, nhưng được giữ lại cho các quy tắc, nhưng không có ý nghĩa gì khác.
Phần nhãn sau dấu hai chấm, app_binary là tên mục tiêu chưa đủ điều kiện. Khi khớp với thành phần cuối cùng của đường dẫn gói, phần tử này và dấu hai chấm có thể bị bỏ qua. Vì vậy, hai nhãn này tương đương với nhau:
//my/app/lib
//my/app/lib:lib
Tên của một mục tiêu tệp trong thư mục con của gói là đường dẫn của tệp tương ứng với thư mục gốc của gói (thư mục chứa tệp BUILD). Vì vậy, tệp này nằm trong thư mục con my/app/main/testdata của kho lưu trữ:
//my/app/main:testdata/input.txt
Các chuỗi như //my/app và @@some_repo//my/app có 2 ý nghĩa tuỳ thuộc vào ngữ cảnh sử dụng: khi Bazel yêu cầu một nhãn, các chuỗi đó có nghĩa là //my/app:app và @@some_repo//my/app:app tương ứng. Tuy nhiên, khi Bazel yêu cầu một gói (ví dụ: trong thông số kỹ thuật package_group), họ sẽ tham chiếu đến gói chứa nhãn đó.
Một lỗi phổ biến trong các tệp BUILD là dùng //my/app để tham chiếu đến một gói hoặc để tất cả mục tiêu trong một gói – vì điều này thì không. Hãy nhớ rằng phương thức này tương đương với //my/app:app, vì vậy phương thức này sẽ đặt tên cho mục tiêu app trong gói my/app của kho lưu trữ hiện tại.
Tuy nhiên, bạn nên sử dụng //my/app để tham chiếu đến một gói trong phần thông số kỹ thuật của package_group hoặc trong tệp .bzl, vì phương thức này cho biết rõ rằng tên gói là tuyệt đối và bắt nguồn từ thư mục cấp cao nhất của không gian làm việc.
Không thể sử dụng nhãn tương đối để tham chiếu đến các mục tiêu trong các gói khác. Trong trường hợp này, bạn phải luôn chỉ định giá trị nhận dạng kho lưu trữ và tên gói.
Ví dụ: nếu cây nguồn chứa cả gói my/app và gói my/app/testdata (mỗi thư mục trong số hai thư mục này có tệp BUILD riêng), thì gói sau chứa một tệp có tên là testdepot.zip. Dưới đây là 2 cách (một sai, một đúng) để tham chiếu đến tệp này trong //my/app:BUILD:
Sai – testdata là một gói khác, vì vậy, bạn không thể sử dụng đường dẫn tương đối
testdata/testdepot.zip
Đúng — tham chiếu đến testdata với đường dẫn đầy đủ
//my/app/testdata:testdepot.zip
Các nhãn bắt đầu bằng @@// là tệp tham chiếu đến kho lưu trữ chính. Các nhãn này vẫn hoạt động ngay cả từ các kho lưu trữ bên ngoài.
Do đó, @@//a/b/c khác với //a/b/c khi được tham chiếu từ một kho lưu trữ bên ngoài.
Phần tử tham chiếu lại về kho lưu trữ chính, còn phần sau tìm kiếm //a/b/c trong chính kho lưu trữ bên ngoài.
Điều này đặc biệt cần thiết khi viết các quy tắc trong kho lưu trữ chính tham chiếu đến các mục tiêu trong kho lưu trữ chính, đồng thời sẽ được dùng từ các kho lưu trữ bên ngoài.
Để biết thông tin về các cách tham chiếu đến mục tiêu, vui lòng xem các mẫu mục tiêu.
Quy cách từ vựng của một nhãn
Cú pháp nhãn không khuyến khích việc sử dụng các siêu ký tự có ý nghĩa đặc biệt đối với shell. Điều này giúp tránh việc vô tình trích dẫn và giúp bạn dễ dàng xây dựng các công cụ và tập lệnh thao túng nhãn, chẳng hạn như Ngôn ngữ truy vấn Bazel.
Dưới đây là thông tin chi tiết chính xác về các tên mục tiêu được phép.
Tên mục tiêu – package-name:target-name
target-name là tên của mục tiêu trong gói. Tên của quy tắc là giá trị của thuộc tính name trong phần khai báo của quy tắc đó trong tệp BUILD; tên của tệp là tên đường dẫn tương ứng với thư mục chứa tệp BUILD.
Tên mục tiêu phải bao gồm toàn bộ các ký tự lấy từ tập hợp a – z, A – Z, 0 – 9 và các ký hiệu dấu câu !%-@^_"#$&'()*-+,;<=>?[]{|}~/..
Tên tệp phải là tên đường dẫn tương đối ở dạng thông thường, nghĩa là tên này không được bắt đầu hoặc kết thúc bằng dấu gạch chéo (ví dụ: /foo và foo/ bị cấm) và cũng không chứa nhiều dấu gạch chéo liên tiếp làm dấu phân tách đường dẫn (ví dụ: foo//bar). Tương tự, tham chiếu cấp cao (..) và tham chiếu thư mục hiện tại (./) đều bị cấm.
Sai — Không sử dụng..` để tham chiếu đến các tệp trong các gói khác
Đúng — Dùng "//package-name:filename"
Mặc dù bạn nên dùng / khi đặt tên cho mục tiêu tệp, nhưng bạn nên tránh dùng / trong tên quy tắc. Đặc biệt là khi dạng viết tắt của nhãn được sử dụng, điều này có thể khiến người đọc nhầm lẫn. Nhãn //foo/bar/wiz luôn là viết tắt của //foo/bar/wiz:wiz, ngay cả khi không có gói foo/bar/wiz nào như vậy. Nhãn này không bao giờ đề cập đến //foo:bar/wiz, ngay cả khi mục tiêu đó tồn tại.
Tuy nhiên, có một số trường hợp mà việc sử dụng dấu gạch chéo lại thuận tiện hoặc đôi khi thậm chí cần thiết. Ví dụ: tên của một số quy tắc phải khớp với tệp nguồn chính của các quy tắc đó. Tệp này có thể nằm trong thư mục con của gói.
Tên gói – //package-name:target-name
Tên của một gói là tên của thư mục chứa tệp BUILD, tương ứng với thư mục cấp cao nhất của kho lưu trữ chứa.
Ví dụ: my/app.
Tên gói phải bao gồm toàn bộ ký tự lấy từ tập hợp
A-Z, a – z, 0–9, '/', '-', '.', '@' và '_' và không được bắt đầu bằng dấu gạch chéo.
Đối với một ngôn ngữ có cấu trúc thư mục quan trọng đối với hệ thống mô-đun của ngôn ngữ đó (ví dụ: Java), bạn phải chọn tên thư mục là giá trị nhận dạng hợp lệ trong ngôn ngữ đó.
Mặc dù Bazel hỗ trợ các mục tiêu trong gói gốc của không gian làm việc (ví dụ: //:foo), nhưng bạn nên để trống gói đó để tất cả các gói có ý nghĩa đều có tên mang tính mô tả.
Tên gói không được chứa chuỗi con // và cũng không kết thúc bằng dấu gạch chéo.
Quy tắc
Quy tắc chỉ định mối quan hệ giữa đầu vào và đầu ra, cũng như các bước tạo dữ liệu đầu ra. Quy tắc có thể thuộc một trong nhiều loại (đôi khi được gọi là lớp quy tắc), lớp này tạo ra các tệp thực thi và thư viện được biên dịch, tệp thực thi kiểm thử và các dữ liệu đầu ra được hỗ trợ khác như mô tả trong Xây dựng Bách khoa toàn thư.
Tệp BUILD khai báo mục tiêu bằng cách gọi quy tắc.
Trong ví dụ bên dưới, chúng ta thấy phần khai báo my_app mục tiêu bằng cách sử dụng quy tắc cc_binary.
cc_binary(
name = "my_app",
srcs = ["my_app.cc"],
deps = [
"//absl/base",
"//absl/strings",
],
)
Mọi lệnh gọi quy tắc đều có một thuộc tính name (phải là tên mục tiêu hợp lệ) để khai báo một mục tiêu trong gói của tệp BUILD.
Mỗi quy tắc đều có một tập hợp các thuộc tính; các thuộc tính áp dụng cho một quy tắc nhất định, ý nghĩa và ngữ nghĩa của mỗi thuộc tính là một hàm thuộc loại quy tắc đó; hãy xem Tạo Bách khoa toàn thư để biết danh sách các quy tắc và thuộc tính tương ứng của các quy tắc đó. Mỗi thuộc tính có một tên và một kiểu. Một số loại phổ biến mà một thuộc tính có thể có là số nguyên, nhãn, danh sách nhãn, chuỗi, danh sách chuỗi, nhãn đầu ra, danh sách nhãn đầu ra. Không phải thuộc tính nào cũng cần được chỉ định trong mọi quy tắc. Do đó, các thuộc tính tạo thành một từ điển từ các khoá (tên) đến các giá trị đã nhập không bắt buộc.
Thuộc tính srcs có trong nhiều quy tắc có loại "danh sách nhãn"; giá trị của thuộc tính này (nếu có) là một danh sách các nhãn, mỗi nhãn là tên của một mục tiêu là dữ liệu đầu vào cho quy tắc này.
Trong một số trường hợp, tên của loại quy tắc có phần tuỳ ý và thú vị hơn là tên của các tệp do quy tắc tạo ra, và điều này đúng với genrules. Để biết thêm thông tin, hãy xem phần Quy tắc chung: quy tắc chung.
Trong các trường hợp khác, tên này có ý nghĩa quan trọng: đối với các quy tắc *_binary và *_test, tên quy tắc sẽ xác định tên của tệp thực thi mà bản dựng tạo ra.
Biểu đồ không chu trình có hướng trên các mục tiêu được gọi là biểu đồ mục tiêu hoặc biểu đồ phần phụ thuộc của bản dựng và là miền mà Công cụ truy vấn Bazel hoạt động.
| Mục tiêu | XÂY DỰNG tệp |