Bazel mem-build software dari kode sumber yang disusun dalam struktur direktori yang disebut workspace. File sumber di workspace disusun dalam hierarki paket bertingkat, dengan setiap paket adalah direktori yang berisi sekumpulan file sumber terkait dan satu file BUILD. File BUILD menentukan output software yang dapat di-build dari sumber.
Workspace
Workspace adalah struktur direktori di sistem file Anda yang berisi file sumber untuk software yang ingin Anda build. Setiap workspace memiliki file teks bernama
WORKSPACE yang mungkin kosong, atau mungkin berisi referensi ke dependensi
eksternal yang diperlukan untuk mem-build output.
Direktori yang berisi file bernama WORKSPACE dianggap sebagai root workspace. Oleh karena itu, Bazel mengabaikan struktur direktori apa pun di workspace yang berakar di subdirektori yang berisi file WORKSPACE, karena membentuk workspace lain.
Bazel juga mendukung file WORKSPACE.bazel sebagai alias file WORKSPACE. Jika kedua file ada, WORKSPACE.bazel akan digunakan.
Repositori
Kode disusun dalam repositori. Direktori yang berisi file WORKSPACE adalah root repositori utama, yang juga disebut @. Repositori lain (eksternal) ditentukan dalam file WORKSPACE menggunakan aturan workspace, atau dibuat dari modul dan ekstensi dalam sistem Bzlmod. Lihat ringkasan dependensi
eksternal untuk mengetahui informasi selengkapnya.
Aturan workspace yang disertakan dengan Bazel didokumentasikan di bagian Aturan Workspace dalam Ensiklopedia Build dan dokumentasi tentang aturan repositori Starlark tersemat.
Karena repositori eksternal adalah repositori itu sendiri, repositori tersebut sering kali juga berisi file WORKSPACE. Namun, file WORKSPACE tambahan ini diabaikan oleh Bazel. Secara khusus, repositori yang bergantung secara transitif tidak ditambahkan secara otomatis.
Paket
Unit utama organisasi kode dalam repositori adalah paket. Paket adalah kumpulan file terkait dan spesifikasi tentang cara file tersebut dapat digunakan untuk menghasilkan artefak output.
Paket ditentukan sebagai direktori yang berisi file
BUILD yang diberi nama BUILD atau BUILD.bazel. Paket mencakup semua file di direktorinya, ditambah semua subdirektori di bawahnya, kecuali yang berisi file BUILD. Dari definisi ini, tidak ada file atau direktori yang dapat menjadi bagian dari dua paket yang berbeda.
Misalnya, dalam struktur direktori berikut, ada dua paket, my/app,
dan subpaket my/app/tests. Perhatikan bahwa my/app/data bukan paket, tetapi
direktori yang termasuk dalam paket my/app.
src/my/app/BUILD
src/my/app/app.cc
src/my/app/data/input.txt
src/my/app/tests/BUILD
src/my/app/tests/test.cc
Target
Paket adalah penampung target, yang ditentukan dalam file
BUILD paket. Sebagian besar target adalah salah satu dari dua jenis utama, file dan aturan.
File dibagi lagi menjadi dua jenis. File sumber biasanya ditulis oleh upaya orang, dan diperiksa ke repositori. File yang dihasilkan, terkadang disebut file turunan atau file output, tidak diperiksa, tetapi dihasilkan dari file sumber.
Jenis target kedua dideklarasikan dengan aturan. Setiap instance aturan menentukan hubungan antara sekumpulan file input dan sekumpulan file output. Input ke aturan dapat berupa file sumber, tetapi juga dapat berupa output dari aturan lain.
Apakah input ke aturan adalah file sumber atau file yang dihasilkan dalam sebagian besar kasus tidak relevan; yang penting hanyalah konten file tersebut. Fakta ini memudahkan penggantian file sumber yang kompleks dengan file yang dihasilkan oleh aturan, seperti yang terjadi saat beban mempertahankan file yang sangat terstruktur secara manual menjadi terlalu melelahkan, dan seseorang menulis program untuk menurunkannya. Tidak ada perubahan yang diperlukan untuk konsumen file tersebut. Sebaliknya, file yang dihasilkan dapat dengan mudah diganti dengan file sumber hanya dengan perubahan lokal.
Input ke aturan juga dapat menyertakan aturan lain. Arti sebenarnya dari hubungan tersebut sering kali cukup kompleks dan bergantung pada bahasa atau aturan, tetapi secara intuitif sederhana: aturan library C++ A mungkin memiliki aturan library C++ B lain untuk input. Efek dari dependensi ini adalah file header B tersedia untuk A selama kompilasi, simbol B tersedia untuk A selama penautan, dan data runtime B tersedia untuk A selama eksekusi.
Invarian semua aturan adalah bahwa file yang dihasilkan oleh aturan selalu termasuk dalam paket yang sama dengan aturan itu sendiri; file tidak dapat dihasilkan ke paket lain. Namun, input aturan sering kali berasal dari paket lain.
Grup paket adalah kumpulan paket yang tujuannya adalah untuk membatasi aksesibilitas aturan tertentu. Grup paket ditentukan oleh fungsi package_group. Grup paket memiliki tiga properti: daftar paket yang dikandungnya, namanya, dan grup paket lain yang disertakannya. Satu-satunya cara yang diizinkan untuk merujuknya adalah dari atribut
visibility aturan atau dari atribut default_visibility fungsi package; grup paket tidak menghasilkan atau menggunakan file. Untuk mengetahui informasi selengkapnya, lihat package_group
dokumentasi.