Hướng dẫn văn phong .bzl

7.3 · 7.2 · 7.1 · 7.0 · 6.5

Trang này trình bày các nguyên tắc cơ bản về kiểu cho Starlark, đồng thời cung cấp thông tin về macro và quy tắc.

Starlark là một ngôn ngữ xác định cách xây dựng phần mềm, do đó, đây vừa là ngôn ngữ lập trình vừa là ngôn ngữ cấu hình.

Bạn sẽ dùng Starlark để ghi tệp BUILD, macro và quy tắc bản dựng. Về cơ bản, macro và quy tắc là các siêu ngôn ngữ – chúng xác định cách viết tệp BUILD. Tệp BUILD được thiết kế để đơn giản và lặp lại.

Tất cả phần mềm đều được đọc thường xuyên hơn so với việc viết. Điều này đặc biệt đúng đối với Starlark, vì các kỹ sư đọc tệp BUILD để hiểu các phần phụ thuộc của mục tiêu và thông tin chi tiết về bản dựng. Thông tin đọc này thường xảy ra khi bạn lướt qua, gấp rút hoặc song song với việc hoàn thành một số nhiệm vụ khác. Do đó, tính đơn giản và dễ đọc là rất quan trọng để người dùng có thể nhanh chóng phân tích cú pháp và hiểu được tệp BUILD.

Khi mở tệp BUILD, người dùng sẽ nhanh chóng muốn biết danh sách các mục tiêu trong tệp; hoặc xem lại danh sách các nguồn của thư viện C++ đó; hoặc xoá một phần phụ thuộc khỏi tệp nhị phân Java đó. Mỗi lần thêm một lớp trừu tượng, bạn sẽ khiến người dùng khó thực hiện các tác vụ này hơn.

Các tệp BUILD cũng được nhiều công cụ phân tích và cập nhật. Các công cụ có thể không chỉnh sửa được tệp BUILD nếu tệp đó sử dụng các tính năng trừu tượng. Việc đơn giản hoá các tệp BUILD sẽ giúp bạn có công cụ tốt hơn. Khi cơ sở mã phát triển, bạn sẽ phải thay đổi nhiều tệp BUILD để cập nhật thư viện hoặc dọn dẹp thường xuyên hơn.

Lưu ý quan trọng: Đừng tạo biến hoặc macro chỉ để tránh một số nội dung lặp lại trong tệp BUILD. Tệp BUILD của bạn phải dễ đọc đối với cả nhà phát triển và công cụ. Nguyên tắc DRY (Khô) không thực sự áp dụng ở đây.

Lời khuyên chung

• Sử dụng Buildifier làm trình định dạng và trình tìm lỗi mã nguồn.
• Tuân thủ nguyên tắc kiểm thử.

Phong cách

Kiểu Python

Khi không chắc chắn, hãy làm theo hướng dẫn về kiểu PEP 8 nếu có thể. Cụ thể, hãy sử dụng 4 thay vì 2 dấu cách để thụt lề theo quy ước của Python.

Vì Starlark không phải là Python, nên một số khía cạnh của kiểu Python sẽ không áp dụng. Ví dụ: PEP 8 khuyên bạn nên thực hiện việc so sánh các singleton bằng is, vì đây không phải là toán tử trong Starlark.

Chuỗi văn bản

Ghi lại các tệp và hàm bằng chuỗi tài liệu (docstrings). Sử dụng docstring ở đầu mỗi tệp .bzl và docstring cho mỗi hàm công khai.

Quy tắc và khía cạnh của tài liệu

Bạn nên ghi lại các quy tắc và khía cạnh, cùng với các thuộc tính, cũng như trình cung cấp và trường của các quy tắc và khía cạnh đó bằng đối số doc.

Quy ước đặt tên

• Biến và tên hàm sử dụng chữ thường với các từ được phân tách bằng dấu gạch dưới ([a-z][a-z0-9_]*), chẳng hạn như cc_library.
• Giá trị riêng tư cấp cao nhất bắt đầu bằng một dấu gạch dưới. Bazel thực thi việc không thể sử dụng các giá trị riêng tư từ các tệp khác. Biến cục bộ không nên sử dụng tiền tố dấu gạch dưới.

Chiều dài đường kẻ

Giống như trong tệp BUILD, không có giới hạn nghiêm ngặt về độ dài dòng vì nhãn có thể dài. Khi có thể, hãy cố gắng sử dụng tối đa 79 ký tự trên mỗi dòng (tuân theo hướng dẫn về quy tắc lập trình của Python, PEP 8). Không nên thực thi nghiêm ngặt nguyên tắc này: trình chỉnh sửa phải hiển thị hơn 80 cột, các thay đổi tự động sẽ thường xuyên đưa ra các dòng dài hơn và con người sẽ không mất thời gian chia tách các dòng đã đọc được.

Đối số từ khoá

Trong đối số từ khoá, bạn nên sử dụng dấu cách xung quanh dấu bằng:

def fct(name, srcs):
    filtered_srcs = my_filter(source = srcs)
    native.cc_library(
        name = name,
        srcs = filtered_srcs,
        testonly = True,
    )

Giá trị boolean

Ưu tiên các giá trị True và False (thay vì 1 và 0) cho các giá trị boolean (chẳng hạn như khi sử dụng thuộc tính boolean trong quy tắc).

Chỉ sử dụng lệnh in để gỡ lỗi

Đừng sử dụng hàm print() trong mã phát hành chính thức; hàm này chỉ dành cho việc gỡ lỗi và sẽ gửi thư rác cho tất cả người dùng trực tiếp và gián tiếp của tệp .bzl. Ngoại lệ duy nhất là bạn có thể gửi mã sử dụng print() nếu mã đó bị tắt theo mặc định và chỉ có thể được bật bằng cách chỉnh sửa nguồn – ví dụ: nếu tất cả các cách sử dụng print() đều được bảo vệ bằng if DEBUG:, trong đó DEBUG được mã cứng vào False. Hãy lưu ý xem những câu nhận định này có đủ hữu ích để biện minh cho tác động của chúng đến khả năng đọc hay không.

Macro

Macro là một hàm tạo bản sao của một hoặc nhiều quy tắc trong giai đoạn tải. Nói chung, sử dụng quy tắc bất cứ khi nào có thể thay vì macro. Biểu đồ bản dựng mà người dùng nhìn thấy không giống với biểu đồ mà Bazel sử dụng trong quá trình tạo bản dựng – các macro được mở rộng trước khi Bazel thực hiện bất kỳ hoạt động phân tích biểu đồ bản dựng nào.

Do đó, khi có sự cố xảy ra, người dùng sẽ cần hiểu cách triển khai macro để khắc phục sự cố bản dựng. Ngoài ra, bạn có thể khó diễn giải kết quả bazel query vì các mục tiêu hiển thị trong kết quả là từ việc mở rộng macro. Cuối cùng, các khía cạnh không nhận biết được các macro, vì vậy, công cụ phụ thuộc vào các khía cạnh (IDE và các công cụ khác) có thể không hoạt động.

Cách an toàn để sử dụng macro là xác định các mục tiêu bổ sung dự định được tham chiếu trực tiếp tại CLI Bazel hoặc trong các tệp BUILD: Trong trường hợp đó, chỉ người dùng cuối của các mục tiêu đó mới cần biết về các mục tiêu đó và mọi vấn đề về bản dựng do macro gây ra đều không xa cách với cách sử dụng của chúng.

Đối với các macro xác định mục tiêu được tạo (các chi tiết triển khai của macro không được tham chiếu tại CLI hoặc phụ thuộc vào các mục tiêu không được macro đó tạo thực thể), hãy làm theo các phương pháp hay nhất sau:

• Macro phải lấy đối số name và xác định một mục tiêu có tên đó. Mục tiêu đó trở thành mục tiêu chính của macro đó.
• Mục tiêu được tạo, tức là tất cả các mục tiêu khác do macro xác định, phải:
  • Có tên bắt đầu bằng <name> hoặc _<name>. Ví dụ: sử dụng name = '%s_bar' % (name).
  • Bị hạn chế hiển thị (//visibility:private) và
  • Có thẻ manual để tránh mở rộng trong các mục tiêu ký tự đại diện (:all, ..., :*, v.v.).
• Bạn chỉ nên sử dụng name để lấy tên của các mục tiêu do macro xác định, chứ không nên sử dụng cho bất kỳ mục đích nào khác. Ví dụ: không sử dụng tên để lấy một phần phụ thuộc hoặc tệp đầu vào không phải do chính macro tạo.
• Tất cả các mục tiêu được tạo trong macro phải được kết hợp theo cách nào đó với mục tiêu chính.
• Thông thường, name phải là đối số đầu tiên khi xác định macro.
• Giữ cho tên tham số trong macro nhất quán. Nếu một tham số được truyền dưới dạng giá trị thuộc tính cho mục tiêu chính, hãy giữ nguyên tên của tham số đó. Nếu một tham số macro có cùng mục đích với thuộc tính quy tắc chung, chẳng hạn như deps, hãy dùng tên giống như cách bạn sử dụng thuộc tính đó (xem bên dưới).
• Khi gọi một macro, chỉ sử dụng các đối số từ khoá. Điều này nhất quán với các quy tắc và giúp cải thiện đáng kể khả năng đọc.

Các kỹ sư thường viết macro khi API Starlark của các quy tắc liên quan không đủ cho trường hợp sử dụng cụ thể của họ, bất kể quy tắc đó được xác định trong Bazel bằng mã gốc hay trong Starlark. Nếu bạn gặp phải vấn đề này, hãy hỏi tác giả quy tắc xem họ có thể mở rộng API để hoàn thành mục tiêu của bạn hay không.

Theo nguyên tắc chung, càng nhiều macro giống với quy tắc thì càng tốt.

Bạn cũng có thể xem macro.

Quy tắc

• Quy tắc, khía cạnh và các thuộc tính của chúng phải sử dụng tên viết_thường ("viết hoa kiểu rắn").
• Tên quy tắc là danh từ mô tả loại cấu phần phần mềm chính do quy tắc tạo ra, từ quan điểm của các phần phụ thuộc (hoặc đối với quy tắc lá, người dùng). Đây không nhất thiết phải là hậu tố tệp. Ví dụ: một quy tắc tạo ra cấu phần phần mềm C++ dùng để làm tiện ích Python có thể được gọi là py_extension. Đối với hầu hết ngôn ngữ, các quy tắc thông thường bao gồm:
  • *_library – một đơn vị biên dịch hoặc "mô-đun".
  • *_binary – một mục tiêu tạo ra một tệp thực thi hoặc một đơn vị triển khai.
  • *_test – một mục tiêu kiểm thử. Việc này có thể bao gồm nhiều bài kiểm thử. Dự kiến tất cả các bài kiểm thử trong mục tiêu *_test đều là các biến thể của cùng một chủ đề, ví dụ: kiểm thử một thư viện.
  • *_import: một mục tiêu đóng gói cấu phần phần mềm được biên dịch trước, chẳng hạn như .jar hoặc .dll được dùng trong quá trình biên dịch.
• Sử dụng tên và loại nhất quán cho các thuộc tính. Sau đây là một số thuộc tính áp dụng chung:
  • srcs: label_list, cho phép tệp: tệp nguồn, thường do con người tạo.
  • deps: label_list, thường không cho phép tệp: phần phụ thuộc biên dịch.
  • data: label_list, cho phép các tệp: tệp dữ liệu, chẳng hạn như dữ liệu kiểm thử, v.v.
  • runtime_deps: label_list: các phần phụ thuộc thời gian chạy không cần thiết cho quá trình biên dịch.
• Đối với mọi thuộc tính có hành vi không rõ ràng (ví dụ: mẫu chuỗi có lựa chọn thay thế đặc biệt hoặc công cụ được gọi với các yêu cầu cụ thể), hãy cung cấp tài liệu bằng cách sử dụng đối số từ khoá doc cho phần khai báo của thuộc tính (attr.label_list() hoặc tương tự).
• Hàm triển khai quy tắc hầu như luôn là hàm riêng (được đặt tên bằng dấu gạch dưới ở đầu). Một kiểu phổ biến là đặt tên hàm triển khai cho myrule là _myrule_impl.
• Truyền thông tin giữa các quy tắc bằng cách sử dụng giao diện nhà cung cấp được xác định rõ ràng. Khai báo và ghi lại các trường của nhà cung cấp.
• Thiết kế quy tắc của bạn sao cho có thể mở rộng. Hãy cân nhắc rằng các quy tắc khác có thể muốn tương tác với quy tắc của bạn, truy cập vào các nhà cung cấp và sử dụng lại các hành động mà bạn tạo.
• Tuân thủ nguyên tắc về hiệu suất trong quy tắc của bạn.