Buat Variabel

Laporkan masalah Lihat sumber Nightly · 8.4 · 8.3 · 8.2 · 8.1 · 8.0 · 7.6

Variabel "Merek" adalah class khusus variabel string yang dapat diperluas dan tersedia untuk atribut yang ditandai sebagai "Tunduk pada penggantian 'Variabel merek'".

Opsi ini dapat digunakan, misalnya, untuk menyisipkan jalur toolchain tertentu ke dalam tindakan build yang dibuat pengguna.

Bazel menyediakan variabel yang telah ditentukan sebelumnya, yang tersedia untuk semua target, dan variabel kustom, yang ditentukan dalam target dependensi dan hanya tersedia untuk target yang bergantung padanya.

Alasan penggunaan istilah "Make" adalah historis: sintaksis dan semantik variabel ini awalnya dimaksudkan agar cocok dengan GNU Make.

Gunakan

Atribut yang ditandai sebagai "Tunduk pada penggantian 'Buat variabel'" dapat mereferensikan variabel "Merek" FOO sebagai berikut:

my_attr = "prefix $(FOO) suffix"

Dengan kata lain, setiap substring yang cocok dengan $(FOO) akan diperluas ke nilai FOO. Jika nilai tersebut adalah "bar", string akhirnya menjadi:

my_attr = "prefix bar suffix"

Jika FOO tidak sesuai dengan variabel yang diketahui oleh target penggunaan, Bazel akan gagal dengan error.

Variabel "Make" yang namanya adalah simbol non-huruf, seperti @, juga dapat dirujuk hanya menggunakan tanda dolar, tanpa tanda kurung. Contoh:

my_attr = "prefix $@ suffix"

Untuk menulis $ sebagai literal string (yaitu untuk mencegah ekspansi variabel), tulis $$.

Variabel yang telah ditetapkan

Variabel "Merek" yang telah ditentukan sebelumnya dapat dirujuk oleh atribut apa pun yang ditandai sebagai "Tunduk pada penggantian 'Variabel merek'" pada target apa pun.

Untuk melihat daftar variabel ini dan nilainya untuk kumpulan opsi build tertentu, jalankan

bazel info --show_make_env [build options]

dan lihat baris output teratas dengan huruf kapital.

Lihat contoh variabel yang telah ditentukan sebelumnya.

Variabel opsi toolchain

Variabel jalur

  • BINDIR: Dasar pohon biner yang dihasilkan untuk arsitektur target.

    Perhatikan bahwa pohon yang berbeda dapat digunakan untuk program yang berjalan selama build pada arsitektur host, untuk mendukung kompilasi silang.

    Jika Anda ingin menjalankan alat dari dalam genrule, cara yang direkomendasikan untuk mendapatkan jalurnya adalah $(execpath toolname), dengan toolname harus tercantum dalam atribut tools genrule.

  • GENDIR: Dasar hierarki kode yang dihasilkan untuk arsitektur target.

Variabel arsitektur mesin

  • TARGET_CPU: CPU arsitektur target, misalnya k8.

Variabel genrule yang telah ditentukan sebelumnya

Berikut adalah nilai yang tersedia khusus untuk atribut genrule's cmd dan umumnya penting agar atribut tersebut berfungsi.

Lihat contoh variabel genrule yang telah ditentukan sebelumnya.

  • OUTS: Daftar outs genrule. Jika hanya memiliki satu file output, Anda juga dapat menggunakan $@.
  • SRCS: Daftar srcs genrule (atau lebih tepatnya: nama jalur file yang sesuai dengan label dalam daftar srcs). Jika hanya memiliki satu file sumber, Anda juga dapat menggunakan $<.
  • <: SRCS, jika berupa satu file. Else memicu error build.
  • @: OUTS, jika berupa satu file. Else memicu error build.

  • RULEDIR: Direktori output target, yaitu direktori yang sesuai dengan nama paket yang berisi target di bawah hierarki genfiles atau bin. Untuk //my/pkg:my_genrule ini selalu berakhir di my/pkg, meskipun output //my/pkg:my_genrule berada di subdirektori.

  • @D: Direktori output. Jika outs memiliki satu entri, ini akan diperluas ke direktori yang berisi file tersebut. Jika memiliki beberapa entri, ini akan diperluas ke direktori root paket di hierarki genfiles, meskipun semua file output berada di subdirektori yang sama.

    Catatan: Gunakan RULEDIR daripada @D karena RULEDIR memiliki semantik yang lebih sederhana dan berperilaku sama terlepas dari jumlah file output.

    Jika genrule perlu membuat file perantara sementara (mungkin sebagai akibat penggunaan beberapa alat lain seperti compiler), genrule harus mencoba menulisnya ke @D (meskipun /tmp juga dapat ditulis) dan menghapusnya sebelum selesai.

    Terutama hindari penulisan ke direktori yang berisi input. File tersebut mungkin berada di sistem file hanya baca. Meskipun tidak, melakukannya akan menghapus pohon sumber.

Variabel jalur input/output yang telah ditentukan sebelumnya

Variabel bawaan execpath, execpaths, rootpath, rootpaths, location, dan locations mengambil parameter label (misalnya, $(execpath //foo:bar)) dan mengganti jalur file yang ditunjukkan oleh label tersebut.

Untuk file sumber, ini adalah jalur relatif terhadap root ruang kerja Anda. Untuk file yang merupakan output aturan, ini adalah jalur output file (lihat penjelasan file output di bawah).

Lihat contoh variabel jalur yang telah ditentukan sebelumnya.

  • execpath: Menunjukkan jalur di bawah execroot tempat Bazel menjalankan tindakan build.

    Dalam contoh di atas, Bazel menjalankan semua tindakan build di direktori yang ditautkan oleh link simbolis bazel-myproject di root ruang kerja Anda. File sumber empty.source ditautkan di jalur bazel-myproject/testapp/empty.source. Jadi, jalur eksekusinya (yang merupakan subjalur di bawah root) adalah testapp/empty.source. Ini adalah jalur yang dapat digunakan tindakan build untuk menemukan file.

    File output dipentaskan dengan cara yang sama, tetapi juga diberi awalan dengan subjalur bazel-out/cpu-compilation_mode/bin (atau untuk output alat: bazel-out/cpu-opt-exec-hash/bin). Dalam contoh di atas, //testapp:app adalah alat karena muncul di atribut tools show_app_output. Jadi, file output app ditulis ke bazel-myproject/bazel-out/cpu-opt-exec-hash/bin/testapp/app. Oleh karena itu, jalur exec adalah bazel-out/cpu-opt-exec-hash/bin/testapp/app. Awalan tambahan ini memungkinkan target yang sama dibangun untuk, misalnya, dua CPU berbeda dalam build yang sama tanpa hasil yang saling menimpa.

    Label yang diteruskan ke variabel ini harus mewakili tepat satu file. Untuk label yang merepresentasikan file sumber, nilai ini otomatis benar. Untuk label yang merepresentasikan aturan, aturan harus menghasilkan tepat satu output. Jika ini salah (false) atau label salah format, build akan gagal dengan error.

  • rootpath: Menunjukkan jalur yang dapat digunakan biner yang dibuat untuk menemukan dependensi saat runtime relatif terhadap subdirektori runfiles-nya yang sesuai dengan repositori utama. Catatan: Ini hanya berfungsi jika --enable_runfiles diaktifkan, yang tidak terjadi di Windows secara default. Gunakan rlocationpath sebagai gantinya untuk dukungan lintas platform.

    Tindakan ini mirip dengan execpath, tetapi menghapus awalan konfigurasi yang dijelaskan di atas. Dalam contoh di atas, artinya empty.source dan app menggunakan jalur murni relatif ruang kerja: testapp/empty.source dan testapp/app.

    rootpath file di repositori eksternal repo akan dimulai dengan ../repo/, diikuti dengan jalur relatif repositori.

    Hal ini memiliki persyaratan "hanya satu output" yang sama dengan execpath.

  • rlocationpath: Jalur yang dapat diteruskan biner yang dibuat ke fungsi Rlocation dari library runfiles untuk menemukan dependensi saat runtime, baik di direktori runfiles (jika tersedia) atau menggunakan manifes runfiles.

    Hal ini mirip dengan rootpath karena tidak berisi awalan konfigurasi, tetapi berbeda karena selalu dimulai dengan nama repositori. Dalam contoh di atas, ini berarti bahwa empty.source dan app menghasilkan jalur berikut: myproject/testapp/empty.source dan myproject/testapp/app.

    rlocationpath file di repositori eksternal repo akan dimulai dengan repo/, diikuti dengan jalur relatif repositori.

    Meneruskan jalur ini ke biner dan menyelesaikannya ke jalur sistem file menggunakan library runfiles adalah pendekatan yang lebih disukai untuk menemukan dependensi saat runtime. Dibandingkan dengan rootpath, cara ini memiliki keunggulan karena berfungsi di semua platform dan bahkan jika direktori runfiles tidak tersedia.

    Hal ini memiliki persyaratan "hanya satu output" yang sama dengan execpath.

  • location: Sinonim untuk execpath atau rootpath, bergantung pada atribut yang diperluas. Ini adalah perilaku pra-Starlark lama dan tidak direkomendasikan kecuali jika Anda benar-benar tahu apa yang dilakukannya untuk aturan tertentu. Lihat #2475 untuk mengetahui detailnya.

execpaths, rootpaths, rlocationpaths, dan locations adalah variasi jamak dari execpath, rootpath, rlocationpaths, danlocation, masing-masing. Label ini mendukung beberapa output, yang dalam hal ini setiap output dicantumkan dan dipisahkan dengan spasi. Aturan output nol dan label yang salah format menghasilkan error build.

Semua label yang dirujuk harus muncul di srcs, file output, atau deps target yang menggunakan. Jika tidak, build akan gagal. Target C++ juga dapat mereferensikan label di data.

Label tidak harus dalam bentuk kanonis: foo, :foo dan //somepkg:foo tidak masalah.

Variabel kustom

Variabel "Merek" kustom dapat dirujuk oleh atribut apa pun yang ditandai sebagai "Tunduk pada penggantian 'Variabel merek'", tetapi hanya pada target yang bergantung pada target lain yang menentukan variabel ini.

Sebagai praktik terbaik, semua variabel harus bersifat kustom kecuali ada alasan yang sangat kuat untuk memasukkannya ke dalam Bazel inti. Hal ini mencegah Bazel memuat dependensi yang berpotensi mahal untuk menyediakan variabel yang menggunakan target yang mungkin tidak penting.

Variabel toolchain C++

Berikut ini ditentukan dalam aturan toolchain C++ dan tersedia untuk aturan apa pun yang menetapkan toolchains = ["@bazel_tools//tools/cpp:current_cc_toolchain"] Beberapa aturan, seperti java_binary, secara implisit menyertakan toolchain C++ dalam definisi aturannya. Variabel ini diwariskan secara otomatis.

Aturan C++ bawaan jauh lebih canggih daripada "jalankan compiler di atasnya". Untuk mendukung mode kompilasi yang beragam seperti *SAN, ThinLTO, dengan/tanpa modul, dan biner yang dioptimalkan dengan cermat sekaligus menjalankan pengujian cepat di beberapa platform, aturan bawaan berupaya keras untuk memastikan input, output, dan flag command line yang benar ditetapkan pada setiap tindakan yang berpotensi dihasilkan secara internal.

Variabel ini adalah mekanisme penggantian yang akan digunakan oleh pakar bahasa dalam kasus yang jarang terjadi. Jika Anda tergoda untuk menggunakannya, hubungi developer Bazel terlebih dahulu.

  • ABI: Versi ABI C++.
  • AR: Perintah "ar" dari crosstool.
  • C_COMPILER: ID compiler C/C++, misalnya llvm.

  • CC: Perintah compiler C dan C++.

    Sebaiknya selalu gunakan CC_FLAGS bersama dengan CC. Jika tidak melakukannya, Anda akan menanggung sendiri risikonya.

  • CC_FLAGS: Kumpulan minimum flag untuk compiler C/C++ agar dapat digunakan oleh genrules. Khususnya, ini berisi tanda untuk memilih arsitektur yang benar jika CC mendukung beberapa arsitektur.
  • NM: Perintah "nm" dari crosstool.
  • OBJCOPY: Perintah objcopy dari rangkaian yang sama dengan compiler C/C++.
  • STRIP: Perintah strip dari rangkaian yang sama dengan compiler C/C++.

Variabel toolchain Java

Berikut ini ditentukan dalam aturan toolchain Java dan tersedia untuk aturan apa pun yang menetapkan toolchains = ["@bazel_tools//tools/jdk:current_java_runtime"] (atau "@bazel_tools//tools/jdk:current_host_java_runtime" untuk toolchain host yang setara).

Sebagian besar alat di JDK tidak boleh digunakan secara langsung. Aturan Java bawaan menggunakan pendekatan yang jauh lebih canggih untuk kompilasi dan pengemasan Java daripada yang dapat dilakukan oleh alat upstream, seperti JAR antarmuka, JAR antarmuka header, dan implementasi pengemasan serta penggabungan JAR yang sangat dioptimalkan.

Variabel ini adalah mekanisme penggantian yang akan digunakan oleh pakar bahasa dalam kasus yang jarang terjadi. Jika Anda tergoda untuk menggunakannya, hubungi developer Bazel terlebih dahulu.

  • JAVA: Perintah "java" (Java virtual machine). Hindari hal ini, dan gunakan aturan java_binary jika memungkinkan. Dapat berupa jalur relatif. Jika Anda harus mengubah direktori sebelum memanggil java, Anda perlu merekam direktori kerja sebelum mengubahnya.
  • JAVABASE: Direktori dasar yang berisi utilitas Java. Dapat berupa jalur relatif. Direktori ini akan memiliki subdirektori "bin".

Variabel yang ditentukan Starlark

Penulis aturan dan toolchain dapat menentukan variabel kustom sepenuhnya dengan menampilkan penyedia TemplateVariableInfo. Aturan apa pun yang bergantung pada aturan ini melalui atribut toolchains kemudian dapat membaca nilainya:

Lihat contoh variabel yang ditentukan Starlark.