Tạo biến

Biến "Make" là một lớp đặc biệt gồm các biến chuỗi có thể mở rộng, có sẵn cho các thuộc tính được đánh dấu là "Subject to 'Make variable' substitution".

Ví dụ: bạn có thể dùng các biến này để chèn các đường dẫn chuỗi công cụ cụ thể vào các thao tác xây dựng do người dùng tạo.

Bazel cung cấp cả biến xác định trước (có sẵn cho tất cả mục tiêu) và biến tuỳ 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 các biến đó).

Lý do cho thuật ngữ "Make" là do 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 Make.

Sử dụng

Các thuộc tính được đánh dấu là "Subject to 'Make variable' substitution" có thể tham chiếu đến biến "Make" FOO như sau:

my_attr = "prefix $(FOO) suffix"

Nói cách khác, mọi chuỗi con khớp với $(FOO) đều được mở rộng thành FOO's value. Nếu giá trị đó là "bar", thì chuỗi cuối cùng sẽ trở thành:

my_attr = "prefix bar suffix"

Nếu FOO không tương ứng với một biến mà mục tiêu tiêu thụ biết, thì Bazel sẽ gặp lỗi.

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

my_attr = "prefix $@ suffix"

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

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

Mọi thuộc tính được đánh dấu là "Subject to 'Make variable' substitution" trên mọi mục tiêu đều có thể tham chiếu đến các biến "Make" xác định trước.

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

bazel info --show_make_env [build options]

và xem các dòng đầu ra trên cùng bằng chữ hoa.

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

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

Biến đường dẫn

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

    Xin 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 quá trình xây dựng trên cấu trúc máy chủ để hỗ trợ biên dịch chéo.

    Nếu bạn muốn chạy một công cụ trong genrule, thì cách được đề xuất để lấy đường dẫn của công cụ đó là $(execpath toolname), trong đó toolname phải được liệt kê trong thuộc tính tools của genrule.

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

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

  • TARGET_CPU: CPU của cấu trúc mục tiêu, chẳng hạn như k8.

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

Sau đây là các biến đặc biệt có sẵn cho genrule's cmd thuộc tính và thường quan trọng để giúp thuộc tính đó hoạt động.

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

  • OUTS: Danh sách outs của genrule. Nếu 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 chính xác hơn: tên đường dẫn của các tệp tương ứng với nhãn trong danh sách 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 duy nhất. Nếu không, sẽ kích hoạt lỗi xây dựng.
  • @: OUTS, nếu đó là một tệp duy nhất. Nếu không, sẽ kích hoạt lỗi xây dựng.

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

  • @D: Thư mục đầu ra. Nếu outs có một mục nhập, thì mụ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, thì mục này sẽ mở rộng thành thư mục gốc của gói trong cây genfiles, ngay cả khi tất cả tệp đầu ra đều nằm trong cùng một thư mục con!

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

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

    Đặc biệt là tránh ghi vào các thư mục chứa dữ liệu đầu vào. Các thư mục này có thể nằm trên hệ thống tệp chỉ đọc. Ngay cả khi không, việc này sẽ làm hỏng cây nguồn.

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

Các biến xác định trước execpath, execpaths, rootpath, rootpaths, location, và locations nhận 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 đối so với thư mục gốc của không gian làm việc. Đối với các tệp là đầu ra của quy tắc, đây là đường dẫn đầu ra của tệp (xem phần giải thích về tệp đầu ra bên dưới).

Xem ví dụ về các biến đường dẫn 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 bằng bazel-myproject liên kết tượng trưng trong thư mục gốc của không gian làm việc. 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 exec của tệp đó (là đường dẫn con bên dưới thư mục gốc) là testapp/empty.source. Đây là đường dẫn mà các thao tác xây dựng có thể dùng để tìm tệp.

    Các tệp đầu ra được dàn dựng tương tự, nhưng cũng được thêm tiền tố bằng đường dẫn con bazel-out/cpu-compilation_mode/bin (hoặc đối với đầu ra của các 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's. 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 exec là bazel-out/cpu-opt-exec-hash/bin/testapp/app. Tiền tố bổ sung này giúp bạn có thể xây dựng cùng một mục tiêu, chẳng hạn như cho 2 CPU khác nhau trong cùng một bản dựng mà không làm kết quả bị ghi đè lẫn nhau.

    Nhãn được truyền đến biến này phải biểu thị chính xác một tệp. Đối với các nhãn biểu thị tệp nguồn, điều này sẽ tự động đúng. Đối với các nhãn biểu thị quy tắc, quy tắc phải tạo chính xác một đầu ra. Nếu điều này là sai hoặc nhãn bị lỗi, thì quá trình xây dựng sẽ gặp lỗi.

  • rootpath: Biểu thị đường dẫn mà tệp nhị phân đã xây dựng có thể dùng để tìm phần phụ thuộc trong thời gian chạy tương ứng với thư mục con của thư mục runfiles thư mục tương ứng với kho lưu trữ chính. Lưu ý: Điều này chỉ hoạt động nếu bạn bật --enable_runfiles, nhưng theo mặc định thì không phải như vậy trên Windows. Hãy sử dụng rlocationpath thay vì để hỗ trợ đa nền tảng.

    Điều này tương tự như execpath nhưng sẽ loại bỏ các tiền tố cấu hình được mô tả ở trên. Trong ví dụ ở trên, điều này có nghĩa là cả empty.source và app đều sử dụng các đường dẫn tương đối thuần tuý trong không gian làm việc: 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/, tiếp theo là đường dẫn tương đối trong kho lưu trữ.

    Điều này có cùng yêu cầu "chỉ một đầu ra" như execpath.

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

    Đ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ỗ 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 sẽ tạo ra các đường dẫn sau: 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/, tiếp theo là đường dẫn tương đối trong kho lưu trữ.

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

    Điều này có cùng yêu cầu "chỉ một đầu ra" như 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 hành vi này hoạt động như thế nào đối với một quy tắc cụ thể. Hãy xem #2475 để biết thông tin chi tiết.

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

Tất cả nhãn được tham chiếu phải xuất hiện trong srcs, tệp đầu ra hoặc deps. Nếu không, quá trình xây dựng sẽ gặp lỗi. Các mục tiêu C++ cũng có thể tham chiếu đến nhãn trong data.

Nhãn không cần ở dạng chính tắc: foo, :foo và //somepkg:foo đều ổn.

Biến tuỳ chỉnh

Mọi thuộc tính được đánh dấu là "Subject to 'Make variable' substitution" đều có thể tham chiếu đến các biến "Make" tuỳ chỉnh, nhưng 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ả các biến đều phải là biến tuỳ chỉnh, trừ phi có lý do thực sự chính đáng để đưa các biến đó vào Bazel cốt lõi. Đ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 mà các mục tiêu tiêu thụ có thể không quan tâm.

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

Sau đây được xác định trong các 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 bao gồm chuỗi công cụ C++ trong định nghĩa quy tắc của chúng. Các quy tắc này sẽ tự động kế thừa các biến này.

Các quy tắc C++ tích hợp phức tạp hơn nhiều so với "chạy trình biên dịch trên đó". Để hỗ trợ các chế độ biên dịch đa dạng như *SAN, ThinLTO, có/không có mô-đun và các tệp nhị phân được tối ưu hoá cẩn thận đồng thời 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ẽ cố gắng hết sức để đảm bảo rằng các dữ liệu đầu vào, đầu ra và cờ dòng lệnh chính xác được đặt trên mỗi thao tác có thể được tạo nội bộ.

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

  • ABI: Phiên bản ABI C++.
  • AR: Lệnh "ar" từ crosstool.
  • C_COMPILER: Mã nhận dạng trình biên dịch C/C++, chẳng hạn như llvm.

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

    Bạn nên luôn sử dụng CC_FLAGS 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: Một tập hợp cờ tối thiểu để trình biên dịch C/C++ có thể sử dụng được bởi genrules. Cụ thể, tập hợp này chứa các cờ để chọn cấu trúc chính xác nếu CC hỗ trợ nhiều cấu trúc.
  • DUMPBIN: Microsoft COFF Binary File Dumper (dumpbin.exe) từ từ Microsoft Visual Studio.
  • NM: Lệnh "nm" từ crosstool.
  • OBJCOPY: Lệnh objcopy từ cùng một bộ như trình biên dịch C/C++
  • STRIP: Lệnh strip từ cùng một bộ như trình biên dịch C/C++

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

Sau đây đượ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 = ["@rules_java//toolchains:current_java_runtime"] (hoặc "@rules_java//toolchains:current_host_java_runtime" cho chuỗi công cụ máy chủ 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. Các quy tắc Java tích hợp sử dụng các phương pháp phức tạp hơn nhiều để biên dịch và đóng gói Java so với các công cụ ngược dòng có thể biểu thị, chẳng hạn như Jars giao diện, Jars giao diện tiêu đề và các triển khai đóng gói và hợp nhất Jar được tối ưu hoá cao.

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

  • JAVA: Lệnh "java" (máy ảo Java ). Hãy tránh sử dụng lệnh này và thay vào đó hãy sử dụng quy tắc java_binary rule nếu có thể. Có thể là đường dẫn tương đối. Nếu bạn phải thay đổi thư mục trước khi gọi java, bạn cần ghi lại thư mục làm việc trước khi thay đổi.
  • JAVABASE: Thư mục cơ sở chứa các tiện ích Java. Có thể là đường dẫn tương đối. Thư mục này sẽ có một thư mục con "bin" subdirectory.

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 các biến hoàn toàn tuỳ chỉnh bằng cách trả về trình cung cấp TemplateVariableInfo. Mọi quy tắc phụ thuộc vào các biến này thông qua thuộc tính toolchains đều có thể đọc các giá trị của chúng:

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