Buat Variabel

Laporkan masalah Lihat sumber Nightly · 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 perluasan variabel), tulis $$.

Predefined variables

Predefined "Make" variables can be referenced by any attribute marked as "Subject to 'Make variable' substitution" on any target.

To see the list of these variables and their values for a given set of build options, run

bazel info --show_make_env [build options]

and look at the top output lines with capital letters.

See an example of predefined variables.

Toolchain option variables

Path variables

  • BINDIR: The base of the generated binary tree for the target architecture.

    Note that a different tree may be used for programs that run during the build on the host architecture, to support cross-compiling.

    If you want to run a tool from within a genrule, the recommended way to get its path is $(execpath toolname), where toolname must be listed in the genrule's tools attribute.

  • GENDIR: The base of the generated code tree for the target architecture.

Machine architecture variables

  • TARGET_CPU: The target architecture's CPU, e.g. k8.

Predefined genrule variables

The following are specially available to genrule's cmd attribute and are generally important for making that attribute work.

See an example of predefined genrule variables.

  • OUTS: The genrule's outs list. If you have only one output file, you can also use $@.
  • SRCS: The genrule's srcs list (or more precisely: the path names of the files corresponding to labels in the srcs list). If you have only one source file, you can also use $<.
  • <: SRCS, if it is a single file. Else triggers a build error.
  • @: OUTS, if it is a single file. Else triggers a build error.

  • RULEDIR: The output directory of the target, that is, the directory corresponding to the name of the package containing the target under the genfiles or bin tree. For //my/pkg:my_genrule this always ends in my/pkg, even if //my/pkg:my_genrule's outputs are in subdirectories.

  • @D: The output directory. If outs has one entry, this expands to the directory containing that file. If it has multiple entries, this expands to the package's root directory in the genfiles tree, even if all output files are in the same subdirectory!

    Note: Use RULEDIR over @D because RULEDIR has simpler semantics and behaves the same way regardless of the number of output files.

    If the genrule needs to generate temporary intermediate files (perhaps as a result of using some other tool like a compiler), it should attempt to write them to @D (although /tmp will also be writable) and remove them before finishing.

    Especially avoid writing to directories containing inputs. They may be on read-only filesystems. Even if not, doing so would trash the source tree.

Note: If the filenames corresponding to the input labels or the output filenames contain spaces, ', or other special characters (or your genrule is part of a Starlark macro which downstream users may invoke on such files), then $(SRCS) and $(OUTS) are not suitable for interpolation into a command line, as they do not have the semantics that "${@}" would in Bash.

One workaround is to convert to a Bash array, with 

mapfile SRCS <<< "$$(sed -e 's/ /\\n/g' <<'genrule_srcs_expansion'
$(SRC)
genrule_srcs_expansion
), lalu gunakan "$$\{SRCS[@]}" di baris perintah berikutnya sebagai pengganti $(SRCS). Opsi yang lebih andal adalah menulis aturan Starlark.





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 merepresentasikan 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
      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 
      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 runfile 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, rlocationpath, 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:toolchain_type"]
  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.
  
    • 


  
  •  DUMPBIN: Microsoft COFF Binary File Dumper (dumpbin.exe) dari
    dari Microsoft Visual Studio. 
    • 

  
  •  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 =
["@rules_java//toolchains:current_java_runtime"] (atau "@rules_java//toolchains: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.