Tạo biến

Báo cáo vấn đề Xem nguồn Hằng đêm · 7,3 · 7.2 · 7.1 · 7 · 6,5

"Nhãn hiệu" biến là một lớp đặc biệt gồm các biến chuỗi có thể mở rộng cho các thuộc tính được đánh dấu là "Chủ đề "Tạo biến" "thay thế".

Bạn có thể sử dụng các công cụ này, ví dụ: chèn các đường dẫn chuỗi công cụ cụ thể vào do người dùng tạo.

Bazel cung cấp cả hai biến được xác định trước mà tất cả mọi người đều có thể sử dụng mục tiêu và biến tùy chỉnh được xác định trong các mục tiêu phụ thuộc và chỉ có sẵn cho các mục tiêu phụ thuộc vào chúng.

Lý do xuất hiện cụm từ "Nhà sản xuất" mang tính lịch sử: cú pháp và ngữ nghĩa của các biến này ban đầu được dự định để khớp với GNU Nhãn hiệu.

Sử dụng

Thuộc tính được đánh dấu là "Chủ đề 'Tạo biến' phép thay thế" có thể tham chiếu đến thuộc tính "Nhãn hiệu" biến FOO như sau:

my_attr = "prefix $(FOO) suffix"

Nói cách khác, bất kỳ chuỗi con nào khớp với $(FOO) sẽ được mở rộng thành giá trị của FOO. Nếu giá trị đó là "bar", kết quả cuối cùng chuỗi sẽ trở thành:

my_attr = "prefix bar suffix"

Nếu FOO không tương ứng với một biến đã biết với phương thức tiêu thụ target, Bazel gặp lỗi.

"Nhãn hiệu" các biến có tên không phải là ký hiệu chữ cái, chẳng hạn như @, cũng có thể được tham chiếu chỉ bằng ký hiệu đô la mà không cần dấu ngoặc đơn. Ví dụ:

my_attr = "prefix $@ suffix"

Để ghi $ dưới dạng giá trị cố định kiểu chuỗi (nghĩa là để ngăn biến mở rộng), hãy viết $$.

Biến được xác định trước

"Nhãn hiệu" tạo sẵn các biến có thể được tham chiếu bởi bất kỳ thuộc tính nào được đánh dấu là "Có tiêu đề "Tạo biến" "thay thế" trên bất kỳ mục tiêu nào.

Để xem danh sách các biến này và giá trị của chúng cho một tập hợp bản dựng nhất định tuỳ chọn, chạy

bazel info --show_make_env [build options]

và xem các dòng đầu ra trên cùng có chứa chữ cái viết hoa.

Xem ví dụ về các biến được xác định trước.

Biến tuỳ chọn trong chuỗi công cụ

Biến đường dẫn

  • BINDIR: Cơ sở của cây nhị phân đã tạo cho mục tiêu cấu trúc.

    Lưu ý rằng bạn có thể sử dụng một cây khác cho các chương trình chạy trong thời gian dựa trên kiến trúc máy chủ lưu trữ để hỗ trợ biên dịch chéo.

    Nếu bạn muốn chạy công cụ từ bên trong genrule, phương thức bạn nên dùng mã $(execpath toolname) để lấy đường dẫn. trong đó toolname phải được liệt kê trong phần tử genrule tools.

  • GENDIR: Cơ sở của cây mã đã tạo cho cấu trúc mục tiêu.

Biến cấu trúc máy

  • TARGET_CPU: CPU của kiến trúc mục tiêu, ví dụ: k8.

Biến tạo quy tắc được xác định trước

Các tính năng sau đây dành riêng cho genrule thuộc tính cmd và thường là quan trọng để làm cho thuộc tính đó hoạt động.

Xem ví dụ về các biến tạo quy tắc được xác định trước.

  • OUTS: Danh sách outs của genrule. Nếu bạn có chỉ có một tệp đầu ra, bạn cũng có thể sử dụng $@.
  • SRCS: Danh sách srcs của genrule (hoặc nhiều hơn) chính xác: tên đường dẫn của các tệp tương ứng với các nhãn trong srcs). Nếu chỉ có một tệp nguồn, bạn cũng có thể sử dụng $<.
  • <: SRCS nếu là một tệp đơn. Các yếu tố kích hoạt khác lỗi bản dựng.
  • @: OUTS nếu là một tệp đơn. Trường hợp khác kích hoạt một lỗi bản dựng.

  • RULEDIR: Thư mục đầu ra của mục tiêu, tức là thư mục thư mục tương ứng với tên của gói chứa đích dưới cây genfiles hoặc bin. Để //my/pkg:my_genrule, bộ sưu tập này luôn kết thúc bằng my/pkg, ngay cả khi dữ liệu đầu ra của //my/pkg:my_genrule nằm trong các thư mục con.

  • @D: Thư mục đầu ra. Nếu out có một mục nhập thao tác này sẽ mở rộng thành thư mục chứa tệp đó. Nếu có nhiều mục nhập này, thao tác này sẽ mở rộng thành thư mục gốc của gói trong phần tử Cây genfiles, ngay cả khi tất cả các tệp đầu ra đều giống nhau thư mục con!

    Lưu ý: Hãy dùng RULEDIR thay vì @D vì RULEDIR có ngữ nghĩa đơn giản hơn và hoạt động theo cách tương tự bất kể số lượng tệp đầu ra.

    Nếu quy tắc tạo sinh cần tạo các tệp trung gian tạm thời (có thể là kết quả của việc sử dụng một số công cụ khác như trình biên dịch), ứng dụng sẽ cố gắng ghi chúng vào @D (mặc dù /tmp cũng sẽ có thể ghi) và xoá chúng trước khi hoàn tất.

    Đặc biệt, tránh ghi vào các thư mục chứa dữ liệu đầu vào. Các thiết bị này có thể đang bật chỉ có thể đọc. Ngay cả khi không, việc này sẽ khiến cây nguồn bị chuyển vào thùng rác.

Biến đường dẫn nguồn/đầu ra được xác định trước

Các biến được xác định trước execpath, execpaths, rootpath, rootpaths, location và locations lấy các tham số nhãn (ví dụ: $(execpath //foo:bar)) và thay thế các đường dẫn tệp được biểu thị bằng nhãn đó.

Đối với các tệp nguồn, đây là đường dẫn tương ứng với thư mục gốc của không gian làm việc. Đối với các tệp là kết quả của quy tắc, đây là đường dẫn đầu ra của tệp (xem nội dung giải thích về các tệp đầu ra ở bên dưới).

Xem ví dụ về các biến đường dẫn được xác định trước.

  • execpath: Biểu thị đường dẫn bên dưới execroot nơi Bazel chạy các thao tác xây dựng.

    Trong ví dụ trên, Bazel chạy tất cả các thao tác xây dựng trong thư mục được liên kết theo đường liên kết tượng trưng bazel-myproject trong thư mục gốc của không gian làm việc. Chiến lược phát hành đĩa đơn tệp nguồn empty.source được liên kết tại đường dẫn bazel-myproject/testapp/empty.source. Vì vậy, đường dẫn thực thi của công ty (mà là đường dẫn con ở dưới thư mục gốc) là testapp/empty.source. Chiến dịch này là đường dẫn mà thao tác có thể sử dụng để tìm tệp.

    Các tệp đầu ra được sắp xếp tương tự nhau, nhưng cũng có tiền tố là đường dẫn con bazel-out/cpu-compilation_mode/bin (hoặc cho dữ liệu đầu ra của công cụ: bazel-out/cpu-opt-exec-hash/bin). Trong ví dụ trên, //testapp:app là một công cụ vì công cụ này xuất hiện trong Thuộc tính tools của show_app_output. Vì vậy, tệp đầu ra app được ghi vào bazel-myproject/bazel-out/cpu-opt-exec-hash/bin/testapp/app. Do đó, đường dẫn thực thi sẽ là bazel-out/cpu-opt-exec-hash/bin/testapp/app. Tiền tố bổ sung này giúp có thể xây dựng cùng một mục tiêu cho, giả sử, hai CPU khác nhau trong cùng một bản dựng mà các kết quả chồng chéo nhau.

    Nhãn được chuyển đến biến này phải đại diện cho chính xác một tệp. Để các nhãn đại diện cho tệp nguồn, thì điều này sẽ tự động xảy ra. Cho nhãn biểu thị các quy tắc, thì quy tắc đó phải tạo ra chính xác một đầu ra. Nếu đây là false hoặc nhãn không đúng định dạng, bản dựng sẽ gặp lỗi.

  • rootpath: Cho biết đường dẫn mà một tệp nhị phân đã tạo có thể dùng để tìm một phần phụ thuộc trong thời gian chạy so với thư mục con của các tệp chạy bộ thư mục tương ứng với kho lưu trữ chính. Lưu ý: Cách này chỉ hiệu quả nếu Đã bật --enable_runfiles, không phải trường hợp trên Windows theo mặc định. Sử dụng rlocationpath cho hỗ trợ nhiều nền tảng.

    Hàm này tương tự như execpath nhưng xoá cấu hình các tiền tố được mô tả ở trên. Trong ví dụ ở trên, điều này có nghĩa là cả empty.source và app sử dụng không gian làm việc thuần tuý tương đối đường dẫn: testapp/empty.source và testapp/app.

    rootpath của một tệp trong kho lưu trữ bên ngoài repo sẽ bắt đầu bằng ../repo/, theo sau là đường dẫn tương đối của kho lưu trữ.

    Kết quả này có cùng "một đầu ra" các yêu cầu của execpath.

  • rlocationpath: Đường dẫn mà một tệp nhị phân đã tạo có thể truyền đến hàm Rlocation của một thư viện runfile để tìm phần phụ thuộc tại thời gian chạy, trong thư mục runfile (nếu có) hoặc sử dụng tệp kê khai của runfile.

    Điều này tương tự như rootpath ở chỗ không chứa tiền tố cấu hình, nhưng khác ở chỗ nó luôn bắt đầu bằng tên của kho lưu trữ. Trong ví dụ ở trên, điều này có nghĩa là empty.source và app dẫn đến kết quả sau đường dẫn: myproject/testapp/empty.source và myproject/testapp/app.

    rlocationpath của một tệp trong kho lưu trữ bên ngoài repo sẽ bắt đầu bằng repo/, theo sau là đường dẫn tương đối của kho lưu trữ.

    Chuyển đường dẫn này đến tệp nhị phân và phân giải thành đường dẫn hệ thống tệp bằng cách sử dụng thì thư viện runfile là phương pháp được ưu tiên để tìm các phần phụ thuộc tại thời gian chạy. So với rootpath, ứng dụng này có ưu điểm là hoạt động trên tất cả các nền tảng và ngay cả khi thư mục runfile thì không sẵn có.

    Kết quả này có cùng "một đầu ra" các yêu cầu của execpath.

  • location: Từ đồng nghĩa với execpath hoặc rootpath, tuỳ thuộc vào thuộc tính đang được mở rộng. Đây là hành vi cũ trước Starlark và không được đề xuất trừ phi bạn thực sự biết điều gì nó áp dụng cho một quy tắc cụ thể. Xem #2475 để biết thông tin chi tiết.

execpaths, rootpaths, rlocationpaths và locations là các biến thể số nhiều của execpath, rootpath, rlocationpaths vàlocation . Các thẻ này hỗ trợ nhãn tạo nhiều đầu ra, trong trường hợp nào mỗi đầu ra được liệt kê và phân tách bằng dấu cách. Quy tắc không đầu ra và không đúng định dạng nhãn tạo ra lỗi bản dựng.

Tất cả nhãn được tham chiếu phải xuất hiện trong srcs của mục tiêu tiêu thụ tệp đầu ra hoặc deps. Nếu không, bản dựng sẽ không hoạt động. Mục tiêu C++ có thể cả nhãn tham chiếu trong data.

Nhãn không nhất thiết phải ở dạng chính tắc: foo, :foo và //somepkg:foo đều ổn.

Biến tuỳ chỉnh

"Nhãn hiệu" tuỳ chỉnh các biến có thể được tham chiếu bởi bất kỳ thuộc tính nào được đánh dấu là "Có tiêu đề "Tạo biến" "thay thế", mà chỉ trên các mục tiêu phụ thuộc vào các mục tiêu khác xác định các biến này.

Tốt nhất là tất cả biến nên được tuỳ chỉnh, trừ khi có một phương thức lý do để đưa chúng vào nhân bazel. Điều này giúp Bazel không phải tải các phần phụ thuộc có thể tốn kém để cung cấp các biến dùng taret không quan tâm đến.

Biến chuỗi công cụ C++

Các nội dung sau được xác định trong quy tắc chuỗi công cụ C++ và có sẵn cho mọi quy tắc để đặt toolchains = ["@bazel_tools//tools/cpp:current_cc_toolchain"] Một số quy tắc, chẳng hạn như java_binary, ngầm ẩn đưa chuỗi công cụ C++ vào định nghĩa quy tắc của chúng. Họ kế thừa các biến này tự động.

Các quy tắc C++ tích hợp sẵn phức tạp hơn nhiều so với cách "chạy trình biên dịch trên nó". Để hỗ trợ nhiều chế độ biên dịch như *SAN, ThinLTO, có/không có mô-đun và tệp nhị phân được tối ưu hoá cẩn thận cùng lúc với các bài kiểm thử chạy nhanh trên nhiều nền tảng, các quy tắc tích hợp sẵn rất hữu ích để đảm bảo đặt chính xác đầu vào, đầu ra và cờ dòng lệnh trên từng hành động trong số nhiều hành động có thể được tạo nội bộ.

Các biến này là cơ chế dự phòng được các chuyên gia ngôn ngữ sử dụng trường hợp hiếm gặp. Nếu bạn muốn sử dụng chúng, trước tiên hãy liên hệ với các nhà phát triển Bazel.

  • ABI: Phiên bản ABI C++.
  • AR: "ar" lệnh từ crosstool.
  • C_COMPILER: Giá trị nhận dạng trình biên dịch C/C++, ví dụ: llvm.

  • CC: Lệnh trình biên dịch C và C++.

    Chúng tôi thực sự khuyên bạn nên luôn sử dụng CC_FLAGS trong kết hợp với CC. Bạn tự chịu rủi ro nếu không làm như vậy.

  • CC_FLAGS: Bộ cờ tối thiểu cho C/C++ trình biên dịch để genrules. Cụ thể, lệnh này chứa cờ để chọn đúng cấu trúc nếu CC hỗ trợ nhiều các kiến trúc khác nhau.
  • NM: "nm" lệnh từ crosstool.
  • OBJCOPY: Lệnh objcopy từ cùng một bộ với C/C++ trình biên dịch.
  • STRIP: Lệnh xoá từ cùng một bộ với C/C++ trình biên dịch.

Biến chuỗi công cụ Java

Các chỉ số sau được xác định trong các quy tắc chuỗi công cụ Java và có sẵn cho mọi quy tắc đặt toolchains = ["@bazel_tools//tools/jdk:current_java_runtime"] (hoặc "@bazel_tools//tools/jdk:current_host_java_runtime" cho chuỗi công cụ lưu trữ tương đương).

Bạn không nên sử dụng trực tiếp hầu hết các công cụ trong JDK. Java tích hợp sẵn dùng những phương pháp tinh vi hơn nhiều để biên dịch và đóng gói Java mà các công cụ ngược dòng (upstream) có thể thể hiện, chẳng hạn như Jars giao diện, giao diện tiêu đề Lọ và các phương pháp triển khai hợp nhất và đóng gói Jar được tối ưu hoá cao.

Các biến này là cơ chế dự phòng được các chuyên gia ngôn ngữ sử dụng trường hợp hiếm gặp. Nếu bạn muốn sử dụng chúng, trước tiên hãy liên hệ với các nhà phát triển Bazel.

  • JAVA: Mã "java" Command (một Java ảo máy). Tránh điều này và sử dụng quy tắc java_binary thay thế nếu có thể. Có thể là một đường dẫn tương đối. Nếu bạn phải thay đổi trước khi gọi java, bạn cần thu thập thư mục đang làm việc trước khi thay đổi thư mục đó.
  • JAVABASE: Thư mục cơ sở chứa Tiện ích Java. Có thể là một đường dẫn tương đối. Nó sẽ có một "thùng" thư mục con.

Biến do Starlark xác định

Người viết quy tắc và chuỗi công cụ có thể xác định biến hoàn toàn tuỳ chỉnh bằng cách trả về một giá trị TemplateVariableInfo Google Cloud. Bất kỳ quy tắc nào dựa trên điều này thông qua Sau đó, thuộc tính toolchains có thể đọc giá trị của các thuộc tính đó:

Xem ví dụ về các biến do Starlark xác định.