Fungsi

Daftar Isi

• paket
• package_group
• exports_files
• glob
• pilih
• subpaket

paket

package(default_deprecation, default_package_metadata, default_testonly, default_visibility, features)

Fungsi ini mendeklarasikan metadata yang berlaku untuk setiap aturan dalam paket. Aturan ini digunakan paling banyak satu kali dalam paket (file BUILD).

Fungsi package() harus dipanggil tepat setelah semua pernyataan load() di bagian atas file, sebelum aturan apa pun.

Argumen

Contoh

package(default_visibility = ["//foo:target"])

package_group

package_group(name, packages, includes)

Fungsi ini menentukan sekumpulan paket dan mengaitkan label dengan set tersebut. Label dapat dirujuk dalam atribut visibility.

Grup paket terutama digunakan untuk kontrol visibilitas. Target yang terlihat secara publik dapat dirujuk dari setiap paket di hierarki sumber. Target yang terlihat secara pribadi hanya dapat dirujuk dalam paketnya sendiri (bukan subpaket). Di antara ekstrem ini, target dapat mengizinkan akses ke paketnya sendiri ditambah paket apa pun yang dijelaskan oleh satu atau beberapa grup paket. Untuk penjelasan yang lebih mendetail tentang sistem visibilitas, lihat atribut visibilitas.

Paket tertentu dianggap berada dalam grup jika cocok dengan atribut packages, atau sudah ada dalam salah satu grup paket lain yang disebutkan dalam atribut includes.

Grup paket secara teknis adalah target, tetapi tidak dibuat oleh aturan, dan tidak memiliki perlindungan visibilitas.

Argumen

Contoh

Deklarasi package_group berikut menentukan grup paket bernama "tropical" yang berisi buah-buahan tropis.

package_group(
    name = "tropical",
    packages = [
        "//fruits/mango",
        "//fruits/orange",
        "//fruits/papaya/...",
    ],
)

Deklarasi berikut menentukan grup paket aplikasi fiktif:

package_group(
    name = "fooapp",
    includes = [
        ":controller",
        ":model",
        ":view",
    ],
)

package_group(
    name = "model",
    packages = ["//fooapp/database"],
)

package_group(
    name = "view",
    packages = [
        "//fooapp/swingui",
        "//fooapp/webui",
    ],
)

package_group(
    name = "controller",
    packages = ["//fooapp/algorithm"],
)

exports_files

exports_files([label, ...], visibility, licenses)

exports_files() menentukan daftar file yang termasuk dalam paket ini yang diekspor ke paket lain.

File BUILD untuk paket hanya dapat merujuk langsung ke file sumber yang termasuk dalam paket lain jika file tersebut diekspor secara eksplisit dengan pernyataan exports_files(). Baca selengkapnya tentang visibilitas file.

Sebagai perilaku lama, file yang disebutkan sebagai input ke aturan juga diekspor dengan visibilitas default hingga tanda --incompatible_no_implicit_file_export diubah. Namun, perilaku ini tidak boleh diandalkan dan harus dimigrasikan secara aktif.

Argumen

Argumennya adalah daftar nama file dalam paket saat ini. Deklarasi visibilitas juga dapat ditentukan; dalam hal ini, file akan terlihat oleh target yang ditentukan. Jika tidak ada visibilitas yang ditentukan, file akan terlihat oleh setiap paket, meskipun visibilitas default paket ditentukan dalam fungsi package. Lisensi juga dapat ditentukan.

Contoh

Contoh berikut mengekspor golden.txt, file teks dari paket test_data, sehingga paket lain dapat menggunakannya, misalnya, dalam atribut data pengujian.

# from //test_data/BUILD

exports_files(["golden.txt"])

glob

glob(include, exclude=[], exclude_directories=1, allow_empty=True)

Glob adalah fungsi bantuan yang menemukan semua file yang cocok dengan pola jalur tertentu, dan menampilkan daftar jalur baru yang dapat diubah dan diurutkan. Glob hanya menelusuri file dalam paketnya sendiri, dan hanya mencari file sumber (bukan file yang dihasilkan atau target lainnya).

Label file sumber disertakan dalam hasil jika jalur relatif paket file cocok dengan salah satu pola include dan tidak ada pola exclude yang cocok.

Daftar include dan exclude berisi pola jalur yang relatif terhadap paket saat ini. Setiap pola dapat terdiri dari satu atau beberapa segmen jalur. Seperti biasa dengan jalur Unix, segmen ini dipisahkan oleh /. Segmen dapat berisi karakter pengganti *: karakter ini cocok dengan substring apa pun di segmen jalur (bahkan substring kosong), kecuali pemisah direktori /. Karakter pengganti ini dapat digunakan beberapa kali dalam satu segmen jalur. Selain itu, karakter pengganti ** dapat mencocokkan nol atau lebih segmen jalur lengkap, tetapi harus dideklarasikan sebagai segmen jalur mandiri.

• foo/bar.txt sama persis dengan file foo/bar.txt dalam paket ini
• foo/*.txt mencocokkan setiap file di direktori foo/ jika file diakhiri dengan .txt (kecuali jika foo/ adalah subpaket)
• foo/a*.htm* cocok dengan setiap file di direktori foo/ yang dimulai dengan a, lalu memiliki string arbitrer (bisa kosong), lalu memiliki .htm, dan diakhiri dengan string arbitrer lainnya; seperti foo/axx.htm dan foo/a.html atau foo/axxx.html
• **/a.txt cocok dengan setiap file a.txt di setiap subdirektori paket ini
• **/bar/**/*.txt cocok dengan setiap file .txt di setiap subdirektori paket ini, jika setidaknya satu direktori di jalur yang dihasilkan disebut bar, seperti xxx/bar/yyy/zzz/a.txt atau bar/a.txt (ingat bahwa ** juga cocok dengan nol segmen) atau bar/zzz/a.txt
• ** cocok dengan setiap file di setiap subdirektori paket ini
• foo**/a.txt adalah pola yang tidak valid, karena ** harus berdiri sendiri sebagai segmen

Jika argumen exclude_directories diaktifkan (disetel ke 1), file jenis direktori akan dihilangkan dari hasil (default 1).

Jika argumen allow_empty disetel ke False, fungsi glob akan menampilkan error jika hasilnya adalah daftar kosong.

Ada beberapa batasan dan peringatan penting:

1. Karena glob() berjalan selama evaluasi file BUILD, glob() hanya mencocokkan file di hierarki sumber Anda, bukan file yang dihasilkan. Jika Anda membuat target yang memerlukan file sumber dan file yang dihasilkan, Anda harus menambahkan daftar eksplisit file yang dihasilkan ke glob. Lihat contoh di bawah dengan :mylib dan :gen_java_srcs.

2. Jika aturan memiliki nama yang sama dengan file sumber yang cocok, aturan akan "membayangi" file.

   Untuk memahaminya, ingatlah bahwa glob() menampilkan daftar jalur, sehingga penggunaan glob() di atribut aturan lain (misalnya, srcs = glob(["*.cc"])) memiliki efek yang sama dengan mencantumkan jalur yang cocok secara eksplisit. Misalnya, jika glob() menghasilkan ["Foo.java", "bar/Baz.java"], tetapi ada juga aturan dalam paket yang disebut "Foo.java" (yang diizinkan, meskipun Bazel memperingatkannya), maka konsumen glob() akan menggunakan aturan "Foo.java" (outputnya) alih-alih file "Foo.java". Lihat masalah GitHub #10395 untuk mengetahui detail selengkapnya.

3. Glob dapat mencocokkan file di subdirektori. Nama subdirektori dapat berisi karakter pengganti. Namun...

4. Label tidak diizinkan untuk melintasi batas paket dan glob tidak cocok dengan file dalam subpaket.

   Misalnya, ekspresi glob **/*.cc dalam paket x tidak menyertakan x/y/z.cc jika x/y ada sebagai paket (baik sebagai x/y/BUILD, atau di tempat lain di jalur paket). Artinya, hasil ekspresi glob sebenarnya bergantung pada keberadaan file BUILD — yaitu, ekspresi glob yang sama akan menyertakan x/y/z.cc jika tidak ada paket yang disebut x/y atau paket tersebut ditandai sebagai dihapus menggunakan tanda --deleted_packages.

5. Pembatasan di atas berlaku untuk semua ekspresi glob, terlepas dari karakter pengganti yang digunakan.
6. File tersembunyi dengan nama file yang diawali dengan . sepenuhnya cocok dengan kartu pengganti ** dan *. Jika Anda ingin mencocokkan file tersembunyi dengan pola gabungan, pola Anda harus dimulai dengan .. Misalnya, * dan .*.txt akan cocok dengan .foo.txt, tetapi *.txt tidak akan cocok. Direktori tersembunyi juga dicocokkan dengan cara yang sama. Direktori tersembunyi dapat menyertakan file yang tidak diperlukan sebagai input, dan dapat meningkatkan jumlah file yang tidak perlu digabungkan dan konsumsi memori. Untuk mengecualikan direktori tersembunyi, tambahkan direktori tersebut ke argumen daftar "exclude".
7. Karakter pengganti "**" memiliki satu kasus sudut: pola "**" tidak cocok dengan jalur direktori paket. Artinya, glob(["**"], exclude_directories = 0) mencocokkan semua file dan direktori secara transitif dan ketat di bawah direktori paket saat ini (tetapi tentu saja tidak masuk ke direktori subpaket - lihat catatan sebelumnya tentang hal itu).

Secara umum, Anda harus berupaya memberikan ekstensi yang sesuai (misalnya, *.html) daripada menggunakan '*' kosong untuk pola glob. Nama yang lebih eksplisit mendokumentasikan dirinya sendiri dan memastikan bahwa Anda tidak secara tidak sengaja mencocokkan file cadangan, atau file simpan otomatis emacs/vi/....

Saat menulis aturan build, Anda dapat menghitung elemen glob. Hal ini memungkinkan pembuatan aturan individual untuk setiap input, misalnya. Lihat bagian contoh glob yang diperluas di bawah.

Contoh Glob

Buat library Java yang dibangun dari semua file java di direktori ini, dan semua file yang dihasilkan oleh aturan :gen_java_srcs.

java_library(
    name = "mylib",
    srcs = glob(["*.java"]) + [":gen_java_srcs"],
    deps = "...",
)

genrule(
    name = "gen_java_srcs",
    outs = [
        "Foo.java",
        "Bar.java",
    ],
    ...
)

Sertakan semua file txt di direktori testdata kecuali experimental.txt. Perhatikan bahwa file di subdirektori testdata tidak akan disertakan. Jika Anda ingin menyertakan file tersebut, gunakan glob rekursif (**).

sh_test(
    name = "mytest",
    srcs = ["mytest.sh"],
    data = glob(
        ["testdata/*.txt"],
        exclude = ["testdata/experimental.txt"],
    ),
)

Contoh Glob Rekursif

Buat pengujian bergantung pada semua file txt di direktori testdata dan subdirektorinya (dan subdirektorinya, dan seterusnya). Subdirektori yang berisi file BUILD akan diabaikan. (Lihat batasan dan catatan di atas.)

sh_test(
    name = "mytest",
    srcs = ["mytest.sh"],
    data = glob(["testdata/**/*.txt"]),
)

Buat library yang dibangun dari semua file java di direktori ini dan semua subdirektori, kecuali yang jalur filenya menyertakan direktori bernama testing. Pola ini sebaiknya dihindari jika memungkinkan, karena dapat mengurangi inkrementalitas build dan dengan demikian meningkatkan waktu build.

java_library(
    name = "mylib",
    srcs = glob(
        ["**/*.java"],
        exclude = ["**/testing/**"],
    ),
)

Contoh Glob yang Diperluas

Buat genrule individual untuk *_test.cc di direktori saat ini yang menghitung jumlah baris dalam file.

# Conveniently, the build language supports list comprehensions.
[genrule(
    name = "count_lines_" + f[:-3],  # strip ".cc"
    srcs = [f],
    outs = ["%s-linecount.txt" % f[:-3]],
    cmd = "wc -l $< >$@",
 ) for f in glob(["*_test.cc"])]

Jika file BUILD di atas berada dalam paket //foo dan paket tersebut berisi tiga file yang cocok, a_test.cc, b_test.cc, dan c_test.cc, maka menjalankan bazel query '//foo:all' akan mencantumkan semua aturan yang dibuat:

$ bazel query '//foo:all' | sort
//foo:count_lines_a_test
//foo:count_lines_b_test
//foo:count_lines_c_test

pilih

select(
    {conditionA: valuesA, conditionB: valuesB, ...},
    no_match_error = "custom message"
)

select() adalah fungsi bantuan yang membuat atribut aturan dapat dikonfigurasi. Ini dapat menggantikan sisi kanan hampir penugasan atribut apa pun sehingga nilainya bergantung pada flag Bazel command line. Anda dapat menggunakan ini, misalnya, untuk menentukan dependensi khusus platform atau untuk menyematkan resource yang berbeda, bergantung pada apakah aturan dibuat dalam mode "developer" vs. "rilis".

Penggunaan dasarnya adalah sebagai berikut:

sh_binary(
    name = "mytarget",
    srcs = select({
        ":conditionA": ["mytarget_a.sh"],
        ":conditionB": ["mytarget_b.sh"],
        "//conditions:default": ["mytarget_default.sh"]
    })
)

Hal ini membuat atribut srcs dari sh_binary dapat dikonfigurasi dengan mengganti penetapan daftar label normalnya dengan panggilan select yang memetakan kondisi konfigurasi ke nilai yang cocok. Setiap kondisi adalah referensi label ke config_setting atau constraint_value, yang "cocok" jika konfigurasi target cocok dengan kumpulan nilai yang diharapkan. Nilai mytarget#srcs kemudian menjadi daftar label mana pun yang cocok dengan pemanggilan saat ini.

Catatan:

• Tepat satu kondisi dipilih pada setiap pemanggilan.
• Jika beberapa kondisi cocok dan salah satunya merupakan spesialisasi dari kondisi lainnya, spesialisasi akan diutamakan. Kondisi B dianggap sebagai spesialisasi kondisi A jika B memiliki semua tanda dan nilai batasan yang sama dengan A ditambah beberapa tanda atau nilai batasan tambahan. Hal ini juga berarti bahwa resolusi spesialisasi tidak dirancang untuk membuat pengurutan seperti yang ditunjukkan dalam Contoh 2 di bawah.
• Jika beberapa kondisi cocok dan salah satunya bukan spesialisasi dari semua kondisi lainnya, Bazel akan gagal dengan error, kecuali jika semua kondisi di-resolve ke nilai yang sama.
• Pseudo-label khusus //conditions:default dianggap cocok jika tidak ada kondisi lain yang cocok. Jika kondisi ini dihilangkan, aturan lain harus cocok untuk menghindari error.
• select dapat disematkan di dalam penetapan atribut yang lebih besar. Jadi, srcs = ["common.sh"] + select({ ":conditionA": ["myrule_a.sh"], ...}) dan srcs = select({ ":conditionA": ["a.sh"]}) + select({ ":conditionB": ["b.sh"]}) adalah ekspresi yang valid.
• select berfungsi dengan sebagian besar, tetapi tidak semua, atribut. Atribut yang tidak kompatibel ditandai nonconfigurable dalam dokumentasinya.

  subpaket

  subpackages(include, exclude=[], allow_empty=True)

  subpackages() adalah fungsi helper, mirip dengan glob() yang mencantumkan subpaket, bukan file dan direktori. Menggunakan pola jalur yang sama dengan glob() dan dapat mencocokkan subpaket apa pun yang merupakan turunan langsung dari file BUILD yang saat ini dimuat. Lihat glob untuk penjelasan mendetail dan contoh pola sertakan dan kecualikan.

  Daftar subpaket yang dihasilkan ditampilkan dalam urutan yang diurutkan dan berisi jalur relatif ke paket pemuatan saat ini yang cocok dengan pola yang diberikan di include dan bukan yang ada di exclude.

  Contoh

  Contoh berikut mencantumkan semua subpaket langsung untuk paket foo/BUILD

  # The following BUILD files exist:
  # foo/BUILD
  # foo/bar/baz/BUILD
  # foo/sub/BUILD
  # foo/sub/deeper/BUILD
  #
  # In foo/BUILD a call to
  subs = subpackages(include = ["**"])
  
  # results in subs == ["sub", "bar/baz"]
  #
  # 'sub/deeper' is not included because it is a subpackage of 'foo/sub' not of
  # 'foo'
  

  Secara umum, lebih baik pengguna menggunakan modul 'subpackages' dari skylib daripada memanggil fungsi ini secara langsung.