Fungsi

Daftar Isi

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

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 sebelum aturan apa pun.

Argumen

Contoh

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

package_group

package_group(name, packages, includes)

Fungsi ini menentukan kumpulan paket dan mengaitkan label dengan himpunan data. Label dapat dirujuk di Atribut visibility.

Grup paket terutama digunakan untuk kontrol visibilitas. Iklan yang terlihat secara publik target dapat direferensikan dari setiap paket dalam struktur pohon sumber. A secara pribadi target yang terlihat hanya dapat direferensikan dalam paketnya sendiri (bukan sub-paket). Di antara ekstrem ini, target mungkin mengizinkan akses ke paketnya sendiri ditambah paket yang dijelaskan oleh satu atau lebih kelompok paket. Untuk gambaran yang lebih detail tentang sistem visibilitas, lihat visibilitas .

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

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

Argumen

Contoh

Deklarasi package_group berikut menentukan grup paket yang disebut "tropical" yang mengandung buah-buahan tropis.

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

Deklarasi berikut menetapkan kelompok paket objek aplikasi:

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 milik paket ini yang diekspor ke paket lain.

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

Sebagai perilaku lama, file yang disebutkan sebagai input ke aturan juga diekspor dengan visibilitas default hingga flag --incompatible_no_implicit_file_export dibalik. Namun, perilaku ini tidak boleh diandalkan dan secara aktif tempat migrasi berasal.

Argumen

Argumennya adalah daftar nama file dalam paket saat ini. J deklarasi visibilitas juga dapat ditentukan; dalam hal ini, file tersebut akan terlihat oleh target yang ditentukan. Jika tidak ada visibilitas yang ditentukan, file akan terlihat oleh setiap paket, bahkan jika visibilitas {i>default<i} paket adalah ditentukan dalam package . Lisensi juga dapat ditentukan.

Contoh

Contoh berikut mengekspor golden.txt, file teks dari paket test_data, sehingga paket 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 yang baru, dapat diubah, dan diurutkan. Glob hanya menelusuri file dalam paketnya sendiri, dan hanya mencari file sumber (bukan file yang dihasilkan atau target lain).

Label file sumber dimasukkan dalam hasil jika paket-relatif file cocok dengan salah satu pola include dan tidak ada satu pun pola exclude.

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

• foo/bar.txt sama persis dengan file foo/bar.txt dalam paket ini
• foo/*.txt cocok dengan setiap file di direktori foo/ jika file diakhiri dengan .txt (kecuali jika foo/ adalah subpaket)
• foo/a*.htm* cocok dengan setiap file dalam 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 dari paket ini, jika paling tidak satu direktori pada jalur yang dihasilkan disebut bar, seperti xxx/bar/yyy/zzz/a.txt atau bar/a.txt (ingatlah bahwa ** juga cocok dengan nol segmen) atau bar/zzz/a.txt
• ** cocok dengan setiap file di setiap subdirektori dari folder ini paket
• 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, parameter Fungsi glob akan mengalami error jika hasilnya sebaliknya daftar kosong.

Ada beberapa batasan dan peringatan penting:

1. Karena glob() berjalan selama evaluasi file BUILD, glob() hanya cocok dengan file di hierarki sumber, tidak pernah file yang dihasilkan. Jika Anda membangun target yang memerlukan sumber dan file yang dihasilkan, Anda harus menambahkan daftar eksplisit 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 "bayangan" file tersebut.

   Untuk memahaminya, ingatlah bahwa glob() menampilkan daftar jalur, jadi menggunakan glob() dalam aturan lain (mis. 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 di paket bernama "Foo.java" (yang diperbolehkan, meskipun Bazel sudah memperingatkannya), konsumen glob() akan menggunakan "Foo.java" aturan (outputnya) bukan "Foo.java" . Lihat GitHub masalah #10395 untuk mengetahui detail selengkapnya.

3. Globs dapat cocok dengan file di subdirektori. Dan nama subdirektori dapat menggunakan karakter pengganti. Namun...

4. Label tidak diizinkan melewati batas paket dan glob melakukan tidak mencocokkan 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 bahwa hasil ekspresi glob sebenarnya bergantung pada keberadaan file BUILD — yaitu, ekspresi glob yang sama akan sertakan x/y/z.cc jika tidak ada paket yang disebut x/y atau ditandai sebagai dihapus menggunakan --deleted_packages penanda.

5. Pembatasan di atas berlaku untuk semua ekspresi glob, tidak peduli {i>wildcard <i}mana yang mereka gunakan.
6. File tersembunyi dengan nama file yang dimulai dengan . akan dicocokkan sepenuhnya dengan karakter pengganti ** dan *. Jika Anda ingin mencocokkan file tersembunyi dengan pola majemuk, pola Anda harus dimulai dengan .. Misalnya, * dan .*.txt akan cocok dengan .foo.txt, tetapi *.txt tidak akan terjadi. Direktori tersembunyi juga dicocokkan dengan cara yang sama. Direktori tersembunyi dapat menyertakan file yang tidak diperlukan sebagai input, dan dapat meningkatkan jumlah file globb yang tidak perlu dan konsumsi memori. Untuk mengecualikan direktori tersembunyi, tambahkan ke "exclude" (kecualikan) daftar argumen.
7. "**" karakter pengganti memiliki satu huruf besar/kecil: pola "**" tidak cocok dengan jalur direktori paket. Yaitu untuk misalnya, glob(["**"], exclude_directories = 0) cocok dengan semua file dan direktori secara transitif secara ketat berada di bawah direktori paket saat ini (tapi tentu saja tidak masuk ke direktori sub-paket - lihat catatan tentang hal itu).

Secara umum, Anda harus mencoba memberikan ekstensi yang sesuai (misalnya *.html) alih-alih menggunakan '*' kosong untuk pola glob. Semakin eksplisit nama mendokumentasikan dirinya sendiri dan memastikan bahwa Anda tidak sengaja mencocokkan file, atau emacs/vi/... file yang disimpan secara otomatis.

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

Contoh Glob

Buatlah library Java yang dibangun dari semua file java di direktori ini, dan semua file yang dibuat 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 testdata direktori kecuali experiment.txt. Perhatikan bahwa file dalam subdirektori data pengujian 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 (beserta subdirektorinya, dan sebagainya). Subdirektori yang berisi file BUILD diabaikan. (Lihat batasan dan peringatan 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 semuanya subdirektori kecuali yang jalurnya menyertakan direktori bernama pengujian. Pola ini sebaiknya dihindari jika memungkinkan, karena dapat mengurangi build inkrementalitas sehingga dapat 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 ada dalam paket //foo dan paket tersebut berisi tiga mencocokkan file, a_test.cc, b_test.cc, dan c_test.cc kemudian 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 penetapan atribut apa pun sehingga nilainya bergantung pada tanda Bazel {i>command line<i}. Anda bisa menggunakannya, misalnya, untuk mendefinisikan dependensi spesifik platform atau untuk menyematkan resource yang berbeda bergantung pada apakah aturan dibuat di "developer" atau tidak vs. "rilis" mode.

Penggunaan dasarnya 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 yang dapat dikonfigurasi dengan mengganti label normalnya daftar tugas dengan panggilan select yang memetakan kondisi konfigurasi hingga nilai yang cocok. Setiap kondisi adalah label referensi ke config_setting atau constraint_value, yang “cocok” jika konfigurasi target cocok dengan kumpulan masing-masing. Nilai mytarget#srcs kemudian menjadi salah satu daftar label cocok dengan pemanggilan saat ini.

Catatan:

• Hanya satu kondisi yang dipilih pada setiap pemanggilan.
• Jika beberapa kondisi cocok dan satu kondisi merupakan spesialisasi dari kondisi yang lain, spesialisasi lebih diprioritaskan. Kondisi B dianggap spesialisasi kondisi A jika B memiliki semua penanda dan batasan yang sama nilai sebagai A ditambah beberapa penanda atau nilai batasan tambahan. Hal ini juga berarti bahwa resolusi spesialisasi tidak dirancang untuk membuat pengaturan seperti ditunjukkan dalam Contoh 2 di bawah ini.
• Jika beberapa kondisi cocok dan salah satunya bukan merupakan spesialisasi dari semua yang lain, Bazel gagal dengan sebuah {i>error.<i}
• Label semu khusus //conditions:default adalah dianggap cocok jika tidak ada kondisi lain yang cocok. Jika kondisi ini diabaikan, beberapa aturan lain harus cocok untuk menghindari kesalahan.
• select dapat disematkan di dalam file yang lebih besar penetapan atribut. 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. 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 alih-alih file dan direktori. Model ini menggunakan metode sebagai glob() dan dapat cocok dengan sub-paket apa pun yang turunan langsung dari file BUILD yang sedang dimuat. Lihat glob untuk mengetahui penjelasan mendetail serta contoh penyertaan dan contoh mengecualikan pola.

  Daftar sub-paket yang dihasilkan dikembalikan dalam urutan yang diurutkan dan berisi jalur relatif terhadap paket pemuatan saat ini yang sesuai dengan pola yang diberikan include dan bukan yang ada 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, lebih baik daripada memanggil fungsi ini secara langsung bahwa pengguna menggunakan 'sub-paket' modul skylib.