Ghi tệp cấu hình bazelrc

Sử dụng bộ sưu tập để sắp xếp ngăn nắp các trang Lưu và phân loại nội dung dựa trên lựa chọn ưu tiên của bạn.
Báo cáo sự cố Xem nguồn

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

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

Bazel tìm các tệp cấu hình tuỳ chọn ở các vị trí sau, theo thứ tự bên dưới. 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 có thể ghi đè một giá trị từ tệp trước đó nếu xung đột xảy ra. Tất cả các tuỳ chọn kiểm soát tệp nào trong số này đều được tải là các tuỳ chọn khởi động, tức là các tuỳ chọn này phải xảy ra sau bazel và trước lệnh (build, test, v.v.).

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

    Đường dẫn:

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

    Đây không phải là lỗi nếu tệp này không tồn tại.

    Nếu bắt buộc phải có 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 tuỳ chỉnh của Basel, 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 không gian làm việc, trừ khi có --noworkspace_rc.

    Đường dẫn: .bazelrc trong thư mục không gian làm việc của bạn (bên cạnh tệp WORKSPACE chính).

    Đây không phải là lỗi nếu tệp này không tồn tại.

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

    Đường dẫn:

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

    Đây không phải là 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 bạn cũng có thể chỉ định nhiều lần.

    /dev/null cho biết rằng tất cả các --bazelrc khác sẽ bị bỏ qua. Việc này rất hữu ích khi bạn tắt tính năng tìm kiếm tệp rc của 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
    
    • Đã đọc x.rcy.rc.
    • z.rc bị bỏ qua do /dev/null trước đó.

Ngoài tệp cấu hình tuỳ chọn này, Bazel còn tìm kiếm một tệp rc toàn cục. Để biết thêm chi tiết, hãy xem phần toàn cục bazelrc.

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

Giống như tất cả các tệp "rc" 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 các từ được mã hoá theo các quy tắc giống như vỏ Bourne.

Nhập

Các dòng bắt đầu bằng import hoặc try-import là đặc biệt: sử dụng các dòng này để tải 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.

Sự khác biệt giữa importtry-import là Bazel không thành công nếu tệp import bị thiếu (hoặc không thể đọc), nhưng không phải là tệp tệp try-import.

Ưu tiên nhập:

  • Các tuỳ chọn trong tệp đã 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.
  • Các tuỳ chọn trong các tệp được nhập sau được ưu tiên hơn các tệp đã nhập trước đó.

Tuỳ chọn mặc định

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

  • startup: các tuỳ chọn khởi động, đứng trước lệnh và được mô tả trong bazel help startup_options.
  • common: các tuỳ chọn áp dụng cho tất cả các lệnh Bazel.
  • command: Lệnh Bazel, chẳng hạn như build hoặc query mà các tùy chọn áp dụng. Các tuỳ chọn này cũng áp dụng cho tất cả các 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 sẽ đượ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 Thụy Sĩ", sẽ tìm thấy cú pháp tương tự như 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 dưới dạng:

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

nên các cờ hiệu quả là --verbose_failures--test_tmpdir=/tmp/bar.

Mức độ ưu tiên tùy chọn:

  • Các tuỳ chọn trên dòng lệnh luôn được ưu tiên hơn các tùy chọn trong tệp rc. Ví dụ: nếu tệp rc có nội dung 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 chịu sự điều chỉnh của mức độ cụ thể: các dòng cho một lệnh cụ thể hơn sẽ được ưu tiên hơn các dòng cho một lệnh ít cụ thể hơn.

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

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

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

    Biểu đồ kế thừa (tính đặc thù) là:

    • 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
  • Hai dòng chỉ định các tùy chọn cho cùng một lệnh có mức độ cụ thể bằng 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 phù hợp với thứ tự tệp, nên quy tắc này sẽ giúp dễ đọc hơn nếu bạn làm theo thứ tự ưu tiên trong các tệp rc: bắt đầu bằng các tùy 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 tùy chọn sẽ giống với thứ tự áp dụng các lựa chọ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 một tệp, các tuỳ chọn này có mức độ ưu tiên thấp hơn so với các cấp độ đồng cấp trong các dòng lệnh và luôn được thêm vào trước danh sách tường minh đối số không phải tuỳ chọn.

--config

Ngoài việc đặt các tuỳ chọn mặc định, tệp rc có thể dùng để nhóm các tuỳ chọn và cung cấp 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 hậu tố :name vào lệnh. Các tuỳ chọn này bị bỏ qua theo mặc định, nhưng sẽ được đưa vào khi tùy chọn --config=name xuất hiện, trên dòng lệnh hoặc trong tệp .bazelrc, theo định kỳ, 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 hiện hành, theo thứ tự ưu tiên được mô tả ở trên.

--config=foo mở rộng các tuỳ chọn được xác định trong các 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 với tuỳ chọn --config=foo.

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

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 điều chỉnh 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 liên quan sử dụng các hệ thống xây dựng khác. Đặt tệp có tên .bazelignore vào 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 một dòng. Các mục 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 đặt tại etc/bazel.bazelrc.
  2. Tệp rc Workspace nằm tại $workspace/tools/bazel.rc.
  3. Tệp rc tại nhà nằm ở $HOME/.bazelrc

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