Fungsi

Daftar Isi

• paket
• package_group [kelompok_paket]
• file_ekspor
• glob [glob]
• pilih
• sub-paket

paket

package(default_deprecation, default_testonly, default_visibility, features)

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

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

Argumen

Atribut	Deskripsi
default_visibility	List of labels; optional Visibilitas default aturan dalam paket ini. Setiap aturan dalam paket ini memiliki visibilitas yang ditetapkan dalam atribut ini, kecuali jika ditentukan lain dalam atribut visibility aturan. Untuk informasi mendetail tentang sintaksis atribut ini, lihat dokumentasi tentang visibilitas. Visibilitas default paket tidak berlaku untuk exports_files, yang bersifat publik secara default.
default_deprecation	String; optional Menetapkan pesan deprecation default untuk semua aturan dalam paket ini.
default_testonly	Boolean; optional; default is False except as noted Menetapkan properti testonly default untuk semua aturan dalam paket ini. Dalam paket di bawah javatests, nilai defaultnya adalah 1.
features	List strings; optional Menetapkan berbagai flag yang memengaruhi semantik file BUILD ini. Fitur ini terutama digunakan oleh orang yang bekerja pada sistem build untuk memberi tag pada paket yang memerlukan penanganan khusus. Jangan gunakan atribut ini kecuali jika diminta secara eksplisit oleh seseorang yang mengerjakan sistem build.

Contoh

Deklarasi di bawah mendeklarasikan bahwa aturan dalam paket ini hanya dapat dilihat oleh anggota grup paket //foo:target. Deklarasi visibilitas individual pada aturan, jika ada, mengganti spesifikasi ini.

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

package_group [kelompok_paket]

package_group(name, packages, includes)

Fungsi ini menentukan kumpulan paket dan mengaitkan label dengan kumpulan. Label dapat dirujuk di atribut visibility.

Grup paket utamanya digunakan untuk kontrol visibilitas. Target yang terlihat secara publik dapat direferensikan dari setiap paket di hierarki sumber. Target yang terlihat secara pribadi hanya dapat direferensikan dalam paketnya sendiri (bukan sub-paket). 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 terdapat 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 apa pun.

Argumen

Atribut	Deskripsi
name	Name; required Nama unik untuk target ini.
packages	List of strings; optional Daftar nol atau beberapa spesifikasi paket. Setiap string spesifikasi paket dapat memiliki salah satu bentuk berikut: Nama lengkap paket, tanpa repositorinya, dimulai dengan garis miring ganda. Misalnya, //foo/bar menentukan paket yang memiliki nama tersebut dan yang berada dalam repositori yang sama dengan grup paket. Seperti di atas, tetapi dengan /... di akhir. Misalnya, //foo/... menentukan kumpulan //foo dan semua sub-paketnya. //... menentukan semua paket di repositori saat ini. String public atau private, yang masing-masing menentukan setiap paket atau tanpa paket. (Formulir ini mengharuskan penetapan flag --incompatible_package_group_has_public_syntax.) Selain itu, dua jenis spesifikasi paket pertama juga dapat diawali dengan - untuk menunjukkan bahwa keduanya telah diabaikan. Grup paket berisi paket apa pun yang cocok dengan setidaknya salah satu spesifikasi positifnya dan tidak ada spesifikasi negatifnya Misalnya, nilai [//foo/..., -//foo/tests/...] mencakup semua sub-paket //foo yang juga bukan sub-paket //foo/tests. (//foo sendiri disertakan, sementara //foo/tests tidak disertakan.) Selain visibilitas publik, tidak ada cara khusus untuk menentukan paket di luar repositori saat ini. Jika atribut ini tidak ada, atribut ini sama dengan menyetelnya ke daftar kosong, yang juga sama dengan menetapkannya ke daftar yang hanya berisi private. Catatan: Spesifikasi //... memiliki perilaku lama yang sama dengan public. Perilaku ini dinonaktifkan saat --incompatible_fix_package_group_reporoot_syntax diaktifkan. Catatan: Sebagai perilaku lama, jika atribut ini diserialisasi sebagai bagian dari bazel query --output=proto (atau --output=xml), garis miring di awal akan dihilangkan jika --incompatible_package_group_includes_double_slash tidak diaktifkan. Misalnya, //pkg/foo/... akan menampilkan output sebagai \"pkg/foo/...\".
includes	List of labels; optional Grup paket lainnya yang disertakan dalam grup paket ini. Label dalam atribut ini harus merujuk pada grup paket lain. Paket dalam grup paket yang direferensikan diambil untuk menjadi bagian dari grup paket ini. Ini bersifat transitif — jika grup paket a menyertakan grup paket b, dan b mencakup grup paket c, maka setiap paket di c juga akan menjadi anggota a. Saat digunakan bersama dengan spesifikasi paket negatif, perhatikan bahwa kumpulan paket untuk setiap grup akan dihitung terlebih dahulu secara independen dan hasilnya akan digabungkan. Artinya, spesifikasi yang diabaikan dalam satu grup tidak akan memengaruhi spesifikasi di grup lainnya.

Contoh

Deklarasi package_group berikut menentukan grup paket yang disebut "tropis" 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"],
)

file_ekspor

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

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

File BUILD untuk sebuah paket hanya boleh merujuk langsung ke file sumber milik paket lain jika paket tersebut diekspor secara eksplisit dengan pernyataan exports_files(). Baca selengkapnya tentang visibilitas file.

Sebagai perilaku lama, file yang juga disebut sebagai input ke aturan diekspor dengan visibilitas default hingga tanda --incompatible_no_implicit_file_export dibalik. Namun, perilaku ini sebaiknya tidak diandalkan dan dimigrasikan secara aktif darinya.

Argumen

Argumen 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 sesuai dengan salah satu pola include dan tidak ada pola exclude.

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 dalam segmen jalur (bahkan substring kosong), tidak termasuk pemisah direktori /. Karakter pengganti ini dapat digunakan beberapa kali dalam satu segmen jalur. Selain itu, karakter pengganti ** dapat cocok dengan segmen segmen nol atau lebih lengkap, tetapi karakter pengganti tersebut harus dideklarasikan sebagai segmen jalur mandiri.

Contoh:

• foo/bar.txt sama persis dengan file foo/bar.txt dalam paket ini
• foo/*.txt cocok dengan setiap file dalam direktori foo/ jika file diakhiri dengan .txt (kecuali jika foo/ adalah sub-paket)
• foo/a*.htm* cocok dengan setiap file dalam 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
• ** mencocokkan 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 direktori jenis akan dihilangkan dari hasil (default 1).

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

Ada beberapa batasan dan peringatan penting:

1. Karena glob() berjalan selama evaluasi file BUILD, glob() hanya mencocokkan file dalam hierarki sumber, bukan file yang dihasilkan. Jika mem-build target yang memerlukan file sumber dan 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 "shadow" file.

   Untuk memahami hal ini, ingat bahwa glob() menampilkan daftar jalur, sehingga menggunakan glob() dalam atribut aturan&#39 lainnya (misalnya srcs = glob(["*.cc"])) memiliki efek yang sama seperti mencantumkan jalur yang cocok secara eksplisit. Jika misalnya glob() menghasilkan ["Foo.java", "bar/Baz.java"], tetapi ada juga aturan dalam paket bernama "Foo.java" (yang diizinkan, meskipun Bazel memperingatkan tentang hal ini), maka konsumen glob() akan menggunakan aturan "Foo.java" (output-nya) bukan file "Foo.java" Lihat Masalah GitHub #10395 untuk detail selengkapnya.

3. Globs mungkin cocok dengan file di subdirektori. Selain itu, nama subdirektori mungkin diberi karakter pengganti. Namun...

4. Label tidak diizinkan melintasi batas paket dan glob tidak cocok dengan file dalam sub-paket.

   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 pada jalur paket). Ini berarti hasil dari ekspresi glob sebenarnya bergantung pada keberadaan file BUILD — yaitu, ekspresi glob yang sama akan menyertakan x/y/z.cc jika tidak ada paket bernama x/y atau ditandai sebagai dihapus menggunakan flag --removed_packages.

5. Pembatasan di atas berlaku untuk semua ekspresi glob, terlepas dari karakter pengganti yang mereka gunakan.
6. File tersembunyi dengan nama file yang dimulai dengan . benar-benar cocok dengan karakter pengganti ** dan *. Jika 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 mencakup file yang tidak diperlukan sebagai input, dan dapat meningkatkan jumlah penggunaan file dan memori yang tidak diperlukan. Untuk mengecualikan direktori tersembunyi, tambahkan direktori tersebut ke argumen "exclude".
7. Karakter pengganti "**" memiliki satu kasus sudut: pola "**" tidak cocok dengan jalur direktori paket. Artinya, glob(["**"], exclude_directories = 0) cocok dengan semua file dan direktori secara transitif secara ketat dalam direktori paket saat ini (tetapi tentu saja tidak masuk ke direktori sub-paket - lihat catatan sebelumnya tentang hal tersebut).

Secara umum, Anda harus mencoba memberikan ekstensi yang sesuai (misalnya, *.html) bukan menggunakan pola kosong seperti #&39;*'. Nama yang lebih eksplisit adalah mendokumentasikannya sendiri dan memastikan bahwa Anda tidak sengaja cocok dengan file cadangan, atau emacs/vi/... simpan otomatis file.

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

Contoh Glob

Buat library Java yang dibuat dari semua file Java dalam 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 dalam data pengujian direktori, kecuali eksperimental.txt. Perhatikan bahwa file dalam subdirektori data pengujian tidak akan disertakan. Jika Anda ingin file tersebut disertakan, gunakan glob rekursif (**).

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

Contoh Glob Rekursif

Membuat pengujian bergantung pada semua file txt dalam direktori testdata dan subdirektorinya (dan subdirektorinya, dan sebagainya). Subdirektori yang berisi file BUILD akan diabaikan. (Lihat batasan dan peringatan di atas.)

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

Buat library yang dibuat dari semua file Java dalam direktori ini, dan semua subdirektori, kecuali yang jalurnya menyertakan direktori bernama pengujian. Pola ini harus dihindari jika memungkinkan, karena dapat mengurangi inkrementalitas build, sehingga meningkatkan waktu build.

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

Contoh Glob yang Diperluas

Buat genrule individu untuk *_test.cc dalam 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 ada dalam paket //foo dan paket berisi tiga file yang cocok, a_test.cc, b_test.cc dan c_test.cc, lalu menjalankan bazel query '//foo:all' akan mencantumkan semua aturan yang dihasilkan:

$ 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. API ini dapat menggantikan sisi kanan hampir penetapan atribut apa pun sehingga nilainya bergantung pada tanda Bazel command line. Anda dapat menggunakan ini, misalnya, untuk menentukan dependensi khusus platform atau menyematkan berbagai resource, bergantung pada apakah aturan dibuat dalam mode "developer" vs. "release".

Penggunaan dasar adalah sebagai berikut:

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

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 merupakan referensi label ke config_setting atau constraint_value, yang "cocok dengan" 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:

• Hanya satu kondisi yang dipilih pada pemanggilan apa pun.
• Jika beberapa kondisi cocok dan satu adalah spesialisasi lainnya, spesialisasi akan diutamakan. Kondisi B dianggap sebagai spesialisasi kondisi A jika B memiliki semua tanda dan nilai batasan yang sama seperti A plus beberapa tanda atau nilai batasan tambahan. Ini juga berarti bahwa resolusi spesialisasi tidak dirancang untuk membuat urutan seperti yang ditunjukkan pada Contoh 2 di bawah.
• Jika beberapa kondisi cocok dan satu bukan spesialisasi dari yang lainnya, Bazel akan gagal dengan menampilkan error.
• Label semu khusus //conditions:default dianggap cocok jika tidak ada kondisi lain yang cocok. Jika kondisi ini terlewat, beberapa 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 sebagai nonconfigurable dalam dokumentasinya.

  sub-paket

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

  subpackages() adalah fungsi bantuan, mirip dengan glob() yang mencantumkan sub-paket, bukan file dan direktori. Metode ini menggunakan pola jalur yang sama dengan glob() dan dapat cocok dengan subpaket apa pun yang merupakan turunan langsung dari file BUILD yang saat ini dimuat. Lihat glob untuk penjelasan detail dan contoh pola penyertaan dan pengecualian.

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

  Contoh

  Contoh berikut mencantumkan semua sub-paket 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, akan lebih baik daripada memanggil fungsi ini secara langsung bahwa pengguna menggunakan 'subpackages' modul skylib.