Ghi tệp cấu hình bazelrc

Báo cáo sự cố Xem nguồn

Bazel chấp nhận nhiều lựa chọn. Một số tuỳ chọn được thay đổi thường xuyên (ví dụ: --subcommands) trong khi một số tuỳ chọn khác vẫn giữ nguyên trên nhiều bản dựng (chẳng hạn như --package_path). Để tránh việc chỉ định các tuỳ chọn không thay đổi này cho mọi bản dựng (và các lệnh khác), bạn có thể chỉ định các tuỳ chọn trong tệp cấu hình có tên .bazelrc.

Các tệp .bazelrc ở đâu?

Bazel tìm các tệp cấu hình không bắt buộc ở các vị trí sau, theo thứ tự dưới đây. Các tuỳ chọn được diễn giải theo thứ tự này, vì vậy, các tuỳ chọn trong các tệp sau này có thể ghi đè một giá trị trong tệp trước đó nếu phát sinh xung đột. Tất cả các tuỳ chọn kiểm soát tệp nào trong số này được tải đều là tuỳ chọn khởi động, nghĩa là các tuỳ chọn đó phải diễn ra sau bazel và trước lệnh (build, test, v.v.).

  1. Tệp RC của hệ thống, trừ phi có --nosystem_rc.

    Đường dẫn:

    • Trên Linux/macOS/Unixes: /etc/bazel.bazelrc
    • Trên Windows: %ProgramData%\bazel.bazelrc

    Lỗi nếu tệp này không tồn tại.

    Nếu cần một vị trí khác do hệ thống chỉ định, bạn phải tạo một tệp nhị phân Bazel tuỳ chỉnh, ghi đè giá trị BAZEL_SYSTEM_BAZELRC_PATH trong //src/main/cpp:option_processor. Vị trí do hệ thống chỉ định có thể chứa các tham chiếu biến môi trường, chẳng hạn như ${VAR_NAME} trên Unix hoặc %VAR_NAME% trên Windows.

  2. Tệp RC của không gian làm việc, trừ phi có --noworkspace_rc.

    Đường dẫn: .bazelrc trong thư mục Workspace (bên cạnh tệp WORKSPACE chính).

    Lỗi nếu tệp này không tồn tại.

  3. Tệp RC tại nhà, trừ phi có --nohome_rc.

    Đường dẫn:

    • Trên Linux/macOS/Unixes: $HOME/.bazelrc
    • Trên Windows: %USERPROFILE%\.bazelrc nếu có hoặc %HOME%/.bazelrc

    Lỗi nếu tệp này không tồn tại.

  4. Tệp RC do người dùng chỉ định, nếu được chỉ định bằng --bazelrc=file

    Cờ này là không bắt buộc nhưng cũng có thể được chỉ định nhiều lần.

    /dev/null cho biết rằng tất cả các --bazelrc tiếp theo sẽ bị bỏ qua. Điều này rất hữu ích khi bạn tắt tính năng tìm kiếm tệp rc người dùng, chẳng hạn như trong các bản phát hành.

    Ví dụ:

    --bazelrc=x.rc --bazelrc=y.rc --bazelrc=/dev/null --bazelrc=z.rc
    
    • x.rcy.rc đã được đọc.
    • z.rc bị bỏ qua do /dev/null trước đó.

Ngoài tệp cấu hình không bắt buộc này, Bazel còn tìm một tệp rc chung. Để biết thêm chi tiết, hãy xem phần bazelrc toàn cầu.

Cú pháp và ngữ nghĩa .bazelrc

Giống như tất cả tệp "rc" của UNIX, tệp .bazelrc là tệp văn bản có ngữ pháp dựa trên dòng. Các dòng và dòng trống bắt đầu bằng # (nhận xét) sẽ bị bỏ qua. Mỗi dòng chứa một chuỗi từ được mã hoá theo các quy tắc tương tự như shell Bourne.

Nhập

Các dòng bắt đầu bằng import hoặc try-import là các dòng đặc biệt: hãy sử dụng các dòng này để tải các tệp "rc" khác. Để chỉ định một đường dẫn tương ứng với thư mục gốc của không gian làm việc, hãy ghi import %workspace%/path/to/bazelrc.

Điểm khác biệt giữa importtry-import là Bazel bị lỗi nếu tệp của import bị thiếu (hoặc không đọc được), nhưng đối với tệp của try-import thì không.

Ưu tiên nhập:

  • Các tuỳ chọn trong tệp được nhập được ưu tiên hơn các tuỳ chọn được chỉ định trước câu lệnh nhập.
  • Các tuỳ chọn được chỉ định sau câu lệnh nhập sẽ được ưu tiên hơn các tuỳ chọn trong tệp đã nhập.
  • Tuỳ chọn trong các tệp được nhập sau này sẽ được ưu tiên so với các tệp được nhập trước đó.

Mặc định của lựa chọn

Hầu hết các dòng của một bazelrc đều xác định các giá trị tuỳ chọn mặc định. Từ đầu tiên trên mỗi dòng xác định thời điểm áp dụng các giá trị mặc định này:

  • startup: các tuỳ chọn khởi động nằm trước lệnh và được mô tả trong bazel help startup_options.
  • common: các tuỳ chọn nên áp dụng cho mọi lệnh Bazel hỗ trợ các tuỳ chọn đó. Nếu một lệnh không hỗ trợ một tuỳ chọn được chỉ định theo cách này, thì tuỳ chọn này sẽ bị bỏ qua, miễn là tuỳ chọn đó hợp lệ đối với một số lệnh Bazel khác. Lưu ý rằng điều này chỉ áp dụng cho tên tuỳ chọn: Nếu lệnh hiện tại chấp nhận một tuỳ chọn có tên đã chỉ định nhưng không hỗ trợ giá trị đã chỉ định, thì lệnh đó sẽ không thành công.
  • always: các tuỳ chọn áp dụng cho mọi lệnh Bazel. Nếu một lệnh không hỗ trợ tuỳ chọn được chỉ định theo cách này, thì lệnh đó sẽ không thành công.
  • command: Lệnh Bazel, chẳng hạn như build hoặc query, áp dụng các tuỳ chọn. Các tuỳ chọn này cũng áp dụng cho mọi lệnh kế thừa từ lệnh đã chỉ định. (Ví dụ: test kế thừa từ build.)

Mỗi dòng trong số này có thể được sử dụng nhiều lần và các đối số theo sau từ đầu tiên được kết hợp như thể chúng đã xuất hiện trên một dòng. (Người dùng CVS, một công cụ khác có giao diện dòng lệnh "Dao cho quân đội Thụy Sĩ", sẽ thấy cú pháp tương tự như cú pháp của .cvsrc.) Ví dụ: các dòng:

build --test_tmpdir=/tmp/foo --verbose_failures
build --test_tmpdir=/tmp/bar

được kết hợp như sau:

build --test_tmpdir=/tmp/foo --verbose_failures --test_tmpdir=/tmp/bar

do đó, cờ hiệu quả là --verbose_failures--test_tmpdir=/tmp/bar.

Mức độ ưu tiên của lựa chọn:

  • Các tuỳ chọn trên dòng lệnh luôn được ưu tiên hơn các tuỳ chọn trong tệp rc. Ví dụ: nếu tệp rc hiển thị build -c opt nhưng cờ dòng lệnh là -c dbg, thì cờ dòng lệnh sẽ được ưu tiên.
  • Trong tệp rc, mức độ ưu tiên được điều chỉnh theo tính cụ thể: các dòng cho lệnh cụ thể hơn sẽ được ưu tiên hơn các dòng cho lệnh ít cụ thể hơn.

    Tính cụ thể được xác định theo tính kế thừa. Một số lệnh kế thừa tuỳ chọn từ các lệnh khác, khiến lệnh kế thừa cụ thể hơn lệnh cơ sở. Ví dụ: test kế thừa từ lệnh build, do đó tất cả cờ bazel build đều hợp lệ đối với bazel test và tất cả các dòng build cũng áp dụng cho bazel test trừ phi có dòng test cho cùng một tuỳ chọn. Nếu tệp rc cho biết:

    test -c dbg --test_env=PATH
    build -c opt --verbose_failures
    

    thì bazel build //foo sẽ sử dụng -c opt --verbose_failuresbazel test //foo sẽ sử dụng --verbose_failures -c dbg --test_env=PATH.

    Biểu đồ kế thừa (tính cụ thể) như sau:

    • Mọi lệnh đều kế thừa từ common
    • Các lệnh sau kế thừa (và cụ thể hơn) build: test, run, clean, mobile-install, info, print_action, config, cqueryaquery
    • coverage kế thừa từ test
  • 2 dòng chỉ định cho cùng một lệnh ở mức độ cụ thể như nhau được phân tích cú pháp theo thứ tự xuất hiện trong tệp.

  • Vì quy tắc ưu tiên này không khớp với thứ tự tệp, nên khả năng đọc sẽ hữu ích nếu bạn tuân theo thứ tự ưu tiên trong tệp rc: bắt đầu bằng các tuỳ chọn common ở trên cùng và kết thúc bằng các lệnh cụ thể nhất ở cuối tệp. Bằng cách này, thứ tự đọc các tuỳ chọn sẽ giống với thứ tự áp dụng các tuỳ chọn đó và dễ hiểu hơn.

Các đối số được chỉ định trên một dòng của tệp rc có thể bao gồm các đối số không phải là tuỳ chọn, chẳng hạn như tên của mục tiêu bản dựng, v.v. Giống như các tuỳ chọn được chỉ định trong cùng tệp, có mức độ ưu tiên thấp hơn so với các đối số cùng cấp trên dòng lệnh và luôn được thêm vào trước danh sách rõ ràng các đối số không phải tuỳ chọn.

--config

Ngoài việc đặt giá trị mặc định cho tuỳ chọn, bạn có thể sử dụng tệp rc để nhóm các tuỳ chọn và là cách viết tắt cho các nhóm phổ biến. Bạn có thể thực hiện việc này bằng cách thêm một hậu tố :name vào lệnh. Các tuỳ chọn này được bỏ qua theo mặc định, nhưng sẽ được đưa vào khi tuỳ chọn --config=name xuất hiện, trên dòng lệnh hoặc trong tệp .bazelrc, theo quy tắc đệ quy, ngay cả bên trong một định nghĩa cấu hình khác. Các tuỳ chọn do command:name chỉ định sẽ chỉ được mở rộng cho các lệnh áp dụng, theo thứ tự ưu tiên được mô tả ở trên.

--config=foo mở rộng thành các tuỳ chọn được xác định trong tệp rc "tại chỗ" để các tuỳ chọn được chỉ định cho cấu hình có cùng mức độ ưu tiên như tuỳ chọn --config=foo.

Cú pháp này không bao gồm việc sử dụng startup để đặt các tuỳ chọn khởi động. Việc đặt startup:config-name --some_startup_option trong .bazelrc sẽ bị bỏ qua.

--enable_platform_specific_config

Bạn có thể tự động bật các cấu hình dành riêng cho nền tảng trong .bazelrc bằng cách sử dụng --enable_platform_specific_config. Ví dụ: nếu hệ điều hành máy chủ là Linux và lệnh build đang chạy, thì cấu hình build:linux sẽ tự động được bật. Các giá trị nhận dạng hệ điều hành được hỗ trợ là linux, macos, windows, freebsdopenbsd. Việc bật cờ này tương đương với việc sử dụng --config=linux trên Linux, --config=windows trên Windows, v.v.

Hãy xem phần --enable_platform_specific_config.

Ví dụ:

Dưới đây là tệp ~/.bazelrc mẫu:

# Bob's Bazel option defaults

startup --host_jvm_args=-XX:-UseParallelGC
import /home/bobs_project/bazelrc
build --show_timestamps --keep_going --jobs 600
build --color=yes
query --keep_going

# Definition of --config=memcheck
build:memcheck --strip=never --test_timeout=3600

Các tệp khác chi phối hành vi của Bazel

.bazelignore

Bạn có thể chỉ định các thư mục trong không gian làm việc mà bạn muốn Bazel bỏ qua, chẳng hạn như các dự án có liên quan sử dụng các hệ thống xây dựng khác. Đặt một tệp có tên là .bazelignore ở thư mục gốc của không gian làm việc và thêm các thư mục bạn muốn Bazel bỏ qua, mỗi thư mục trên một dòng. Các mục nhập tương ứng với thư mục gốc của không gian làm việc.

Tệp bazelrc toàn cầu

Bazel đọc các tệp bazelrc không bắt buộc theo thứ tự sau:

  1. Tệp rc-hệ thống nằm tại etc/bazel.bazelrc.
  2. Workspace. Tệp rc-rc nằm tại $workspace/tools/bazel.rc.
  3. Tệp rc tại nhà nằm tại $HOME/.bazelrc

Mỗi tệp bazelrc được liệt kê ở đây đều có một cờ tương ứng có thể dùng để vô hiệu hoá các tệp đó (ví dụ: --nosystem_rc, --noworkspace_rc, --nohome_rc). Bạn cũng có thể khiến Bazel bỏ qua tất cả các bazelrcs bằng cách chuyển tuỳ chọn khởi động --ignore_all_rc_files.