Build Foundation đã bắt đầu tuyển chọn thành viên sáng lập! Tham gia danh sách gửi thư, đọc thoả thuận tham gia và đăng ký!

Ghi tệp cấu hình bazelrc

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

Nightly · 9.0 · 8.6 · 8.5 · 8.4 · 8.3 · 8.2 · 7.7

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

Tệp `.bazelrc` nằm ở đâu?

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

Tệp RC 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
Nếu tệp này không tồn tại thì không phải là lỗ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.
Tệp RC không gian làm việc, trừ phi có --noworkspace_rc.

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

Nếu tệp này không tồn tại thì không phải là lỗi.
Tệp RC chính, trừ phi 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
Nếu tệp này không tồn tại thì không phải là lỗi.
Tệp RC biến môi trường, nếu đường dẫn của tệp được đặt bằng BAZELRC biến môi trường.

Biến môi trường có thể bao gồm nhiều đường dẫn được phân tách bằng dấu phẩy.
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ả --bazelrc tiếp theo sẽ bị bỏ qua. Điều này hữu ích để 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 dựng phát hành .

Ví dụ:
```
--bazelrc=x.rc --bazelrc=y.rc --bazelrc=/dev/null --bazelrc=z.rc
```
- x.rc và y.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 toàn cầu. Để biết thêm thông tin, hãy xem phần bazelrc toàn cầu.

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

Giống như tất cả các tệp "rc" của UNIX, tệp .bazelrc là một tệp văn bản có ngữ pháp dựa trên dòng. Các dòng trống và các dò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ùng một quy tắc như Bourne shell.

Nhập

Các dòng bắt đầu bằng import, try-import hoặc try-import-if-bazel-version là các dòng đặc biệt: 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 viết import %workspace%/path/to/bazelrc.

Sự khác biệt giữa các câu lệnh nhập khác nhau như sau:

import – Bazel sẽ gặp lỗi nếu tệp imported'ed bị thiếu (hoặc không thể đọc được)
try-import – Hệ thống sẽ cố gắng nhập tệp, nhưng không giống như import, Bazel sẽ KHÔNG gặp lỗi nếu tệp bị thiếu (hoặc không thể đọc được).
try-import-if-bazel-version – Tương tự như try-import, nhưng một điều kiện bổ sung về phiên bản Bazel hiện tại sẽ được kiểm tra trước khi cố gắng thực hiện nhập. Xem cú pháp bên dưới.

Tính năng nhập phiên bản Bazel có điều kiện có thể hữu ích nếu một dự án cần hoạt động trong nhiều phiên bản Bazel hoặc trong quá trình chuyển đổi từ phiên bản Bazel này sang phiên bản Bazel khác. Bạn có thể cần các cờ khác nhau cho các phiên bản Bazel khác nhau vì các cờ có thể bị ngừng sử dụng, bị xoá hoặc được giới thiệu trong mỗi bản phát hành. Để kiểm tra phiên bản Bazel mà bạn đang sử dụng, hãy chạy bazel --version. Các điều kiện kiểm tra sau đây được hỗ trợ và yêu cầu các phiên bản ngữ nghĩa hợp lệ:

# Strictly greater than: used for post-release targeting
try-import-if-bazel-version >7.0.0 %workspace%/configs/post_v7.rc

# Greater than or equal to: commonly used for feature introduction
try-import-if-bazel-version >=6.0.0 %workspace%/configs/features.rc

# Strictly less than: used for deprecated flags removed in newer versions
try-import-if-bazel-version <7.0.0 %workspace%/configs/legacy.rc

# Less than or equal to: caps configuration to a specific version
try-import-if-bazel-version <=5.4.0 %workspace%/configs/v5_fixes.rc

# Exact match: hotfix for a specific broken release
try-import-if-bazel-version ==6.3.2 %workspace%/configs/hotfix_6.3.2.rc

# Not equal to: excludes broken version from standard config
try-import-if-bazel-version !=7.0.1 %workspace%/configs/standard.rc

Một toán tử dấu ngã bổ sung cung cấp các phạm vi cho các thay đổi về phiên bản bản vá, phiên bản phụ và phiên bản lớn:

# Equivalent to >=1.2.3 <1.3.0
try-import-if-bazel-version ~1.2.3 %workspace%/configs/1.2.3_flags.rc

# Equivalent to >=1.2.0 <1.3.0 (Same as 1.2.x)
try-import-if-bazel-version ~1.2 %workspace%/configs/1.2_flags.rc

# Equivalent to >=1.0.0 <2.0.0 (Same as 1.x)
try-import-if-bazel-version ~1 %workspace%/configs/v1_flags.rc

Mức độ ưu tiên nhập:

Các lựa chọn trong tệp đã nhập có mức độ ưu tiên cao hơn các lựa chọn được chỉ định trước câu lệnh nhập.
Các lựa chọn được chỉ định sau câu lệnh nhập có mức độ ưu tiên cao hơn các lựa chọn trong tệp đã nhập.
Các lựa chọn trong các tệp được nhập sau này có mức độ ưu tiên cao hơn các tệp được nhập trước đó.

Giá trị mặc định của lựa chọn

Hầu hết các dòng của bazelrc đều xác định các giá trị lựa 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 này:

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

Mỗi dòng 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 đa năng", 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 thành:

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

vì vậy, các cờ hiệu quả là --verbose_failures và --test_tmpdir=/tmp/bar.

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

Các lựa chọn trên dòng lệnh luôn có mức độ ưu tiên cao hơn các lựa chọn trong tệp rc. Ví dụ: nếu một tệp rc cho biết build -c opt nhưng cờ hiệu dòng lệnh là -c dbg, thì cờ hiệu dòng lệnh sẽ có mức độ ưu tiên cao hơn.
Trong tệp rc, mức độ ưu tiên chịu sự điều chỉnh của tính cụ thể: các dòng cho một lệnh cụ thể hơn có mức độ ưu tiên cao 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 lựa 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, vì vậy, tất cả cá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ó một dòng test cho cùng một lựa 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_failures và bazel test //foo sẽ 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 đây kế thừa từ (và cụ thể hơn) build: test, run, clean, mobile-install, info, print_action, config, cquery và aquery
- coverage, fetch và vendor kế thừa từ test
Hai dòng chỉ định các lựa chọn cho cùng một lệnh ở 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 khớp với thứ tự tệp, nên bạn nên tuân theo thứ tự ưu tiên trong các tệp rc để dễ đọc hơn: bắt đầu bằng các lựa 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 lựa chọn giống như thứ tự áp dụng các lựa chọn, giúp bạn 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à lựa chọn, chẳng hạn như tên của các mục tiêu bản dựng, v.v. Giống như các lựa chọn được chỉ định trong cùng một tệp, các đối số này có mức độ ưu tiên thấp hơn các đối số cùng cấp trên dòng lệnh và luôn được thêm vào danh sách rõ ràng của các đối số không phải là lựa chọn.

`--config`

Ngoài việc đặt các giá trị mặc định của lựa chọn, bạn có thể sử dụng tệp rc để nhóm các lựa chọn và cung cấp một lối 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. Theo mặc định, các lựa chọn này sẽ bị bỏ qua, nhưng sẽ được đưa vào khi có lựa chọn --config=name, trên dòng lệnh hoặc trong tệp .bazelrc, một cách đệ quy, ngay cả bên trong một định nghĩa cấu hình khác. Các lựa chọn được chỉ định bởi command:name 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 lựa chọn được xác định trong các tệp rc "tại chỗ" để các lựa chọn được chỉ định cho cấu hình có cùng mức độ ưu tiên mà lựa chọn --config=foo đã có.

Cú pháp này không mở rộng đến việc sử dụng startup để đặt các lựa 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 được chạy, thì cấu hình build:linux sẽ tự động được bật. Các mã nhận dạng hệ điều hành được hỗ trợ là linux, macos, windows, freebsd và openbsd. 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, --config=macos trên macOS, --config=freebsd trên FreeBSD và --config=openbsd trên OpenBSD.

Xem --enable_platform_specific_config.

Các cấu hình dành riêng cho nền tảng cũng áp dụng cho các lựa chọn startup. Ví dụ: startup:linux --some_startup_option sẽ được áp dụng khi hệ điều hành máy chủ là Linux. Các mã nhận dạng hệ điều hành được hỗ trợ là linux, macos, windows, freebsd và openbsd. Hành vi này luôn được bật.

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 liên quan sử dụng các hệ thống bản 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 .bazelignore không cho phép ngữ nghĩa glob. Bazel 8 giới thiệu tệp REPO.bazel cho phép một lệnh khác là ignore_directories(). Lệnh này lấy một danh sách các thư mục để bỏ qua giống như .bazelignore, nhưng có ngữ nghĩa glob. Xem #24203.

Tệp bazelrc toàn cầu

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

Tệp rc hệ thống nằm ở /etc/bazel.bazelrc.
Tệp rc không gian làm việc nằm ở $workspace/tools/bazel.rc.
Tệp rc chính nằm ở $HOME/.bazelrc

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

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.

Tệp .bazelrc nằm ở đâu?

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