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

Báo cáo vấn đề Nightly · 8.3 · 8.2 · 8.1 · 8.0 · 7.6

Các phương thức có trong tệp BUILD. Bạn cũng có thể xem Build Encyclopedia để biết thêm các hàm và quy tắc xây dựng. Bạn cũng có thể sử dụng các hàm và quy tắc này trong tệp BUILD.

Hội viên

depsset

depset depset(direct=None, order="default", *, transitive=None)

Tạo một depset. Tham số direct là danh sách các phần tử trực tiếp của depset, còn tham số transitive là danh sách các depset mà phần tử của chúng trở thành phần tử gián tiếp của depset được tạo. Thứ tự mà các phần tử được trả về khi depset được chuyển đổi thành danh sách được chỉ định bằng tham số order. Hãy xem bài viết Tổng quan về Depset để biết thêm thông tin.

Tất cả các phần tử (trực tiếp và gián tiếp) của một depset phải thuộc cùng một loại, như được biểu thị bằng biểu thức type(x).

Vì một tập hợp dựa trên hàm băm được dùng để loại bỏ các phần tử trùng lặp trong quá trình lặp lại, nên tất cả các phần tử của depset đều phải có thể băm. Tuy nhiên, bất biến này hiện không được kiểm tra nhất quán trong tất cả các hàm khởi tạo. Sử dụng cờ --incompatible_always_check_depset_elements để bật tính năng kiểm tra nhất quán; đây sẽ là hành vi mặc định trong các bản phát hành sau này; hãy xem Vấn đề 10313.

Ngoài ra, các phần tử hiện phải là bất biến, mặc dù hạn chế này sẽ được nới lỏng trong tương lai.

Thứ tự của depset được tạo phải tương thích với thứ tự của các depset transitive. Thứ tự "default" tương thích với mọi thứ tự khác, tất cả các thứ tự khác chỉ tương thích với chính chúng.

Thông số

Thông số Mô tả
direct sequence; hoặc None; mặc định là None
Một danh sách các phần tử trực tiếp của một depset.
order string; mặc định là "default"
Chiến lược duyệt qua cho depset mới. Hãy xem tại đây để biết các giá trị có thể có.
transitive sequence của depset; hoặc None; mặc định là None
Danh sách các depset mà các phần tử sẽ trở thành phần tử gián tiếp của depset.

existing_rule

unknown existing_rule(name)

Trả về một đối tượng bất biến giống như từ điển mô tả các thuộc tính của một quy tắc được khởi tạo trong gói của luồng này hoặc None nếu không có thực thể quy tắc nào có tên đó.

Ở đây, đối tượng bất biến giống như từ điển có nghĩa là một đối tượng bất biến sâu x hỗ trợ hoạt động lặp lại giống như từ điển, len(x), name in x, x[name], x.get(name), x.items(), x.keys() và x.values().

Kết quả chứa một mục cho từng thuộc tính, ngoại trừ các thuộc tính riêng tư (tên không bắt đầu bằng một chữ cái) và một số loại thuộc tính cũ không thể biểu thị. Ngoài ra, dict này còn chứa các mục cho name và kind của phiên bản quy tắc (ví dụ: 'cc_binary').

Các giá trị của kết quả biểu thị giá trị thuộc tính như sau:

  • Các thuộc tính thuộc loại str, int và bool được biểu thị như hiện tại.
  • Nhãn được chuyển đổi thành các chuỗi có dạng ':foo' cho các mục tiêu trong cùng một gói hoặc '//pkg:name' cho các mục tiêu trong một gói khác.
  • Danh sách được biểu thị dưới dạng bộ và từ điển được chuyển đổi thành từ điển mới, có thể thay đổi. Các phần tử của chúng được chuyển đổi đệ quy theo cùng một cách.
  • Các giá trị select được trả về cùng với nội dung đã được chuyển đổi như mô tả ở trên.
  • Những thuộc tính mà bạn không chỉ định giá trị trong quá trình tạo thực thể quy tắc và có giá trị mặc định được tính toán sẽ bị loại trừ khỏi kết quả. (Không thể tính toán các giá trị mặc định được tính toán cho đến giai đoạn phân tích.).

Nếu có thể, chỉ sử dụng hàm này trong các hàm triển khai của macro tượng trưng cho trình hoàn tất quy tắc. Không nên sử dụng hàm này trong các ngữ cảnh khác và hàm này sẽ bị vô hiệu hoá trong một bản phát hành Bazel trong tương lai; hàm này khiến các tệp BUILD dễ bị lỗi và phụ thuộc vào thứ tự. Ngoài ra, hãy lưu ý rằng quy tắc này khác biệt một chút so với 2 quy tắc chuyển đổi khác về giá trị thuộc tính quy tắc từ biểu mẫu nội bộ sang Starlark: một quy tắc được dùng theo mặc định được tính toán, quy tắc còn lại được dùng theo ctx.attr.foo.

Thông số

Thông số Mô tả
name string; required
Tên của mục tiêu.

existing_rules

unknown existing_rules()

Trả về một đối tượng bất biến giống như từ điển, mô tả các quy tắc đã được khởi tạo cho đến nay trong gói của luồng này. Mỗi mục trong đối tượng giống như từ điển sẽ liên kết tên của thực thể quy tắc với kết quả mà existing_rule(name) sẽ trả về.

Ở đây, đối tượng bất biến giống như từ điển có nghĩa là một đối tượng bất biến sâu x hỗ trợ hoạt động lặp lại giống như từ điển, len(x), name in x, x[name], x.get(name), x.items(), x.keys() và x.values().

Nếu có thể, chỉ sử dụng hàm này trong các hàm triển khai của macro tượng trưng cho trình hoàn tất quy tắc. Không nên sử dụng hàm này trong các ngữ cảnh khác và hàm này sẽ bị vô hiệu hoá trong một bản phát hành Bazel trong tương lai; hàm này khiến các tệp BUILD dễ bị lỗi và phụ thuộc vào thứ tự.

exports_files

None exports_files(srcs, visibility=None, licenses=None)

Chỉ định danh sách các tệp thuộc gói này được xuất sang các gói khác.

Thông số

Thông số Mô tả
srcs sequence của strings; required
Danh sách các tệp cần xuất.
visibility sequence; hoặc None; mặc định là None
Bạn có thể chỉ định một khai báo về khả năng hiển thị. Các tệp này sẽ hiển thị cho những mục tiêu mà bạn chỉ định. Nếu bạn không chỉ định chế độ hiển thị, thì mọi gói đều có thể nhìn thấy các tệp.
licenses sequence của string; hoặc None; mặc định là None
Giấy phép cần được chỉ định.

glob

sequence glob(include=[], exclude=[], exclude_directories=1, allow_empty=unbound)

Glob trả về một danh sách mới, có thể thay đổi và được sắp xếp của mọi tệp trong gói hiện tại:
  • Khớp ít nhất một mẫu trong include.
  • Không khớp với bất kỳ mẫu nào trong exclude (mặc định là []).
Nếu đối số exclude_directories được bật (đặt thành 1), các tệp thuộc loại thư mục sẽ bị bỏ qua trong kết quả (mặc định là 1).

Thông số

Thông số Mô tả
include sequence của strings; mặc định là []
Danh sách các mẫu glob cần đưa vào.
exclude sequence của strings; mặc định là []
Danh sách các mẫu glob cần loại trừ.
exclude_directories int; mặc định là 1
Cờ cho biết có loại trừ thư mục hay không.
allow_empty mặc định là unbound
Liệu chúng ta có cho phép các mẫu glob không khớp với nội dung nào hay không. Nếu `allow_empty` là False, thì mỗi mẫu include riêng lẻ phải khớp với một nội dung nào đó và kết quả cuối cùng cũng phải không có nội dung (sau khi các kết quả khớp của mẫu `exclude` bị loại trừ).

module_name

string module_name()

Tên của mô-đun Bazel liên kết với kho lưu trữ mà gói này nằm trong. Nếu gói này đến từ một kho lưu trữ được xác định trong WORKSPACE thay vì MODULE.bazel, thì gói này sẽ trống. Đối với các kho lưu trữ do tiện ích mô-đun tạo, đây là tên của mô-đun lưu trữ tiện ích. Trường này giống với trường module.name mà bạn thấy trong module_ctx.modules. Có thể trả về None.

module_version

string module_version()

Phiên bản của mô-đun Bazel liên kết với kho lưu trữ mà gói này nằm trong. Nếu gói này đến từ một kho lưu trữ được xác định trong WORKSPACE thay vì MODULE.bazel, thì gói này sẽ trống. Đối với các kho lưu trữ do tiện ích mô-đun tạo, đây là phiên bản của mô-đun lưu trữ tiện ích. Trường này giống với trường module.version mà bạn thấy trong module_ctx.modules. Có thể trả về None.

gói hàng

unknown package(**kwargs)

Khai báo siêu dữ liệu áp dụng cho mọi quy tắc trong gói. Bạn chỉ được gọi hàm này tối đa một lần trong một gói (tệp BUILD). Nếu được gọi, đây phải là lệnh gọi đầu tiên trong tệp BUILD, ngay sau các câu lệnh load().

Thông số

Thông số Mô tả
kwargs required
Hãy xem hàm package() trong Bách khoa toàn thư về bản dựng để biết các đối số có thể áp dụng.

package_default_visibility

List package_default_visibility()

Trả về chế độ hiển thị mặc định của gói đang được đánh giá. Đây là giá trị của tham số default_visibility của package(), được mở rộng để bao gồm cả gói.

package_group

None package_group(name, packages=[], includes=[])

Hàm này xác định một nhóm gói và chỉ định nhãn cho nhóm đó. Bạn có thể tham chiếu nhãn trong các thuộc tính visibility.

Thông số

Thông số Mô tả
name string; required
Tên riêng biệt cho quy tắc này.
packages sequence của strings; default is []
Một danh sách đầy đủ các gói trong nhóm này.
includes sequence của strings; mặc định là []
Các nhóm gói khác có trong nhóm này.

package_name

string package_name()

Tên của gói đang được đánh giá, không có tên kho lưu trữ. Ví dụ: trong tệp BUILD some/package/BUILD, giá trị của tệp này sẽ là some/package. Nếu tệp BUILD gọi một hàm được xác định trong tệp .bzl, thì package_name() sẽ khớp với gói tệp BUILD của trình gọi. Giá trị này sẽ luôn là một chuỗi trống đối với gói gốc.

package_relative_label

Label package_relative_label(input)

Chuyển đổi chuỗi đầu vào thành một đối tượng Label, trong bối cảnh của gói hiện đang được khởi chạy (tức là tệp BUILD mà macro hiện tại đang thực thi). Nếu đầu vào đã là một Label, thì đầu vào đó sẽ được trả về mà không thay đổi.

Bạn chỉ có thể gọi hàm này trong khi đánh giá một tệp BUILD và các macro mà tệp đó gọi trực tiếp hoặc gián tiếp; bạn không thể gọi hàm này (ví dụ) trong một hàm triển khai quy tắc.

Kết quả của hàm này là giá trị Label giống như giá trị được tạo ra bằng cách truyền chuỗi đã cho đến một thuộc tính có giá trị nhãn của mục tiêu được khai báo trong tệp BUILD.

Lưu ý khi sử dụng: Điểm khác biệt giữa hàm này và Label() là Label() sử dụng ngữ cảnh của gói trong tệp .bzl đã gọi hàm này, chứ không phải gói trong tệp BUILD. Sử dụng Label() khi bạn cần tham chiếu đến một mục tiêu cố định được cố định trong mã nguồn vào macro, chẳng hạn như một trình biên dịch. Sử dụng package_relative_label() khi bạn cần chuẩn hoá một chuỗi nhãn do tệp BUILD cung cấp thành một đối tượng Label. (Không có cách nào để chuyển đổi một chuỗi thành Label trong ngữ cảnh của một gói khác ngoài tệp BUILD hoặc tệp .bzl gọi. Do đó, các macro bên ngoài nên luôn ưu tiên truyền các đối tượng Nhãn đến các macro bên trong thay vì các chuỗi nhãn.)

Thông số

Thông số Mô tả
input string; hoặc Label; required
Chuỗi nhãn đầu vào hoặc đối tượng Nhãn. Nếu một đối tượng Nhãn được truyền, thì đối tượng đó sẽ được trả về nguyên trạng.

repo_name

string repo_name()

Tên chính tắc của kho lưu trữ chứa gói hiện đang được đánh giá, không có dấu @ ở đầu.

repository_name

string repository_name()

Thử nghiệm. API này đang trong giai đoạn thử nghiệm và có thể thay đổi bất cứ lúc nào. Vui lòng không phụ thuộc vào thông tin này. Bạn có thể bật chế độ này theo cách thử nghiệm bằng cách đặt --+incompatible_enable_deprecated_label_apis
Không dùng nữa. Bạn nên sử dụng repo_name thay thế. Lớp này không chứa dấu @ giả mạo ở đầu, nhưng hoạt động giống hệt như vậy.

Tên chính tắc của kho lưu trữ chứa gói hiện đang được đánh giá, có một ký tự @ (@) ở phía trước. Ví dụ: trong các gói được gọi bằng đoạn WORKSPACE local_repository(name='local', path=...), giá trị này sẽ được đặt thành @local. Trong các gói trong kho lưu trữ chính, giá trị này sẽ được đặt thành @.

chọn

unknown select(x, no_match_error='')

select() là hàm trợ giúp giúp thuộc tính quy tắc có thể định cấu hình. Hãy xem phần xây dựng bách khoa toàn thư để biết thông tin chi tiết.

Thông số

Thông số Mô tả
x dict; required
Một dict ánh xạ các điều kiện cấu hình với các giá trị. Mỗi khoá là một Nhãn hoặc một chuỗi nhãn xác định một thực thể config_setting hoặc constraint_value. Hãy xem tài liệu về macro để biết thời điểm sử dụng Nhãn thay vì chuỗi.
no_match_error string; mặc định là ''
Lỗi tuỳ chỉnh không bắt buộc để báo cáo nếu không có điều kiện nào trùng khớp.

gói con

sequence subpackages(include, exclude=[], allow_empty=False)

Trả về một danh sách có thể thay đổi mới của mọi gói con trực tiếp của gói hiện tại, bất kể độ sâu của thư mục hệ thống tệp. Danh sách trả về được sắp xếp và chứa tên của các gói con tương ứng với gói hiện tại. Bạn nên ưu tiên sử dụng các phương thức trong mô-đun bazel_skylib.subpackages thay vì gọi trực tiếp hàm này.

Thông số

Thông số Mô tả
include sequence của strings; required
Danh sách các mẫu glob để đưa vào quá trình quét gói con.
exclude sequence của strings; mặc định là []
Danh sách các mẫu glob cần loại trừ khỏi quá trình quét gói con.
allow_empty bool; mặc định là False
Liệu chúng ta có thất bại nếu lệnh gọi trả về một danh sách trống hay không. Theo mặc định, danh sách trống cho biết có thể xảy ra lỗi trong tệp BUILD khi lệnh gọi đến subpackages() là không cần thiết. Nếu bạn đặt thành true, thì hàm này sẽ thành công trong trường hợp đó.