Panduan Gaya BUILD

Laporkan masalah Lihat sumber Nightly · 7.4 . 7.3 · 7.2 · 7.1 · 7.0 · 6.5

Pemformatan file BUILD mengikuti pendekatan yang sama dengan Go, dengan alat standar yang menangani sebagian besar masalah pemformatan. Buildifier adalah alat yang mengurai dan memunculkan kode sumber dalam gaya standar. Oleh karena itu, setiap file BUILD diformat dengan cara otomatis yang sama, sehingga pemformatan akan menjadi bukan masalah selama peninjauan kode. Hal ini juga mempermudah alat untuk memahami, mengedit, dan membuat file BUILD.

Format file BUILD harus cocok dengan output buildifier.

Contoh pemformatan

# Test code implementing the Foo controller.
package(default_testonly = True)

py_test(
    name = "foo_test",
    srcs = glob(["*.py"]),
    data = [
        "//data/production/foo:startfoo",
        "//foo",
        "//third_party/java/jdk:jdk-k8",
    ],
    flaky = True,
    deps = [
        ":check_bar_lib",
        ":foo_data_check",
        ":pick_foo_port",
        "//pyglib",
        "//testing/pybase",
    ],
)

Struktur file

Rekomendasi: Gunakan urutan berikut (setiap elemen bersifat opsional):

  • Deskripsi paket (komentar)

  • Semua pernyataan load()

  • Fungsi package().

  • Panggilan ke aturan dan makro

Buildifier membedakan antara komentar mandiri dan komentar yang dilampirkan ke elemen. Jika komentar tidak dilampirkan ke elemen tertentu, gunakan baris kosong setelahnya. Perbedaan ini penting saat melakukan perubahan otomatis (misalnya, untuk mempertahankan atau menghapus komentar saat menghapus aturan).

# Standalone comment (such as to make a section in a file)

# Comment for the cc_library below
cc_library(name = "cc")

Referensi ke target dalam paket saat ini

File harus dirujuk berdasarkan jalurnya yang relatif terhadap direktori paket (tanpa pernah menggunakan referensi atas, seperti ..). File yang dihasilkan harus diawali dengan ":" untuk menunjukkan bahwa file tersebut bukan sumber. File sumber tidak boleh diawali dengan :. Aturan harus diawali dengan :. Misalnya, dengan asumsi x.cc adalah file sumber:

cc_library(
    name = "lib",
    srcs = ["x.cc"],
    hdrs = [":gen_header"],
)

genrule(
    name = "gen_header",
    srcs = [],
    outs = ["x.h"],
    cmd = "echo 'int x();' > $@",
)

Penamaan target

Nama target harus deskriptif. Jika target berisi satu file sumber, target umumnya memiliki nama yang berasal dari sumber tersebut (misalnya, cc_library untuk chat.cc dapat diberi nama chat, atau java_library untuk DirectMessage.java dapat diberi nama direct_message).

Target eponim untuk sebuah paket (target dengan nama yang sama seperti direktori yang memuatnya) harus menyediakan fungsi yang dijelaskan oleh nama direktori. Jika tidak ada target tersebut, jangan buat target dengan nama yang sama.

Pilih nama pendek saat merujuk ke target eponim (//x, bukan //x:x). Jika Anda berada dalam paket yang sama, pilih referensi lokal (:x, bukan //x).

Hindari penggunaan nama target "yang direservasi" yang memiliki arti khusus. Ini mencakup all, __pkg__, dan __subpackages__. Nama ini memiliki semantik khusus dan dapat menyebabkan kebingungan serta perilaku yang tidak terduga saat digunakan.

Jika tidak ada konvensi tim yang berlaku, berikut beberapa rekomendasi yang tidak mengikat yang digunakan secara luas di Google:

  • Secara umum, gunakan "snake_case"
    • Untuk java_library dengan satu src, ini berarti menggunakan nama yang tidak sama dengan nama file tanpa ekstensi
    • Untuk aturan *_binary dan *_test Java, gunakan "Upper CamelCase". Hal ini memungkinkan nama target cocok dengan salah satu src. Untuk java_test, hal ini memungkinkan atribut test_class disimpulkan dari nama target.
  • Jika ada beberapa varian target tertentu, tambahkan akhiran untuk membedakan (seperti. :foo_dev, :foo_prod, atau :bar_x86, :bar_x64)
  • Akhiri target _test dengan _test, _unittest, Test, atau Tests
  • Hindari akhiran yang tidak bermakna seperti _lib atau _library (kecuali jika diperlukan untuk menghindari konflik antara target _library dan _binary yang sesuai)
  • Untuk target terkait proto:
    • proto_library target harus memiliki nama yang diakhiri dengan _proto
    • Aturan *_proto_library khusus bahasa harus cocok dengan proto yang mendasarinya, tetapi ganti _proto dengan akhiran khusus bahasa seperti:
      • cc_proto_library: _cc_proto
      • java_proto_library: _java_proto
      • java_lite_proto_library: _java_proto_lite

Visibilitas

Visibilitas harus dicakup seketat mungkin, sambil tetap mengizinkan akses oleh pengujian dan dependensi terbalik. Gunakan __pkg__ dan __subpackages__ sesuai kebutuhan.

Hindari menyetel paket default_visibility ke //visibility:public. //visibility:public harus ditetapkan satu per satu hanya untuk target dalam API publik project. Library ini dapat berupa library yang didesain untuk diandalkan oleh project eksternal atau biner yang dapat digunakan oleh proses build project eksternal.

Dependensi

Dependensi harus dibatasi ke dependensi langsung (dependensi yang diperlukan oleh sumber yang tercantum dalam aturan). Jangan cantumkan dependensi transitif.

Dependensi lokal paket harus dicantumkan terlebih dahulu dan dirujuk sedemikian rupa agar kompatibel dengan bagian Referensi ke target dalam paket saat ini di atas (bukan berdasarkan nama paket absolutnya).

Pilih untuk mencantumkan dependensi secara langsung, sebagai satu daftar. Menempatkan dependensi "umum" beberapa target ke dalam variabel akan mengurangi kemampuan pemeliharaan, sehingga alat tidak dapat mengubah dependensi target, dan dapat menyebabkan dependensi yang tidak digunakan.

Glob

Tunjukkan "tidak ada target" dengan []. Jangan gunakan glob yang tidak cocok dengan apa pun: lebih rentan terhadap error dan kurang jelas daripada daftar kosong.

Rekursif

Jangan gunakan glob rekursif untuk mencocokkan file sumber (misalnya, glob(["**/*.java"])).

Glob rekursif membuat file BUILD sulit dipahami karena melewati subdirektori yang berisi file BUILD.

Bola rekursif umumnya kurang efisien dibandingkan memiliki file BUILD per direktori dengan grafik dependensi yang ditentukan di antara keduanya karena hal ini memungkinkan paralelisme dan caching jarak jauh yang lebih baik.

Sebaiknya buat file BUILD di setiap direktori dan tentukan grafik dependensi di antara file tersebut.

Non-rekursif

Glob non-rekursif umumnya dapat diterima.

Konvensi lainnya

  • Gunakan huruf besar dan garis bawah untuk mendeklarasikan konstanta (seperti GLOBAL_CONSTANT), gunakan huruf kecil dan garis bawah untuk mendeklarasikan variabel (seperti my_variable).

  • Label tidak boleh dipisah, bahkan jika panjangnya lebih dari 79 karakter. Label harus berupa string literal jika memungkinkan. Argumentasi: Cara ini memudahkan menemukan dan mengganti. Hal ini juga meningkatkan keterbacaan.

  • Nilai atribut nama harus berupa string konstanta literal (kecuali dalam makro). Alasan: Alat eksternal menggunakan atribut nama untuk merujuk ke aturan. Mereka perlu menemukan aturan tanpa harus menafsirkan kode.

  • Saat menetapkan atribut jenis boolean, gunakan nilai boolean, bukan nilai bilangan bulat. Untuk alasan lama, aturan masih mengonversi bilangan bulat menjadi boolean sesuai kebutuhan, tetapi hal ini tidak disarankan. Argumentasi: flaky = 1 dapat salah diartikan sebagai pernyataan "deflake target ini dengan menjalankannya kembali sekali". flaky = True dengan jelas menyatakan "pengujian ini tidak stabil".

Perbedaan dengan panduan gaya Python

Meskipun kompatibilitas dengan panduan gaya Python adalah tujuan, ada beberapa perbedaan:

  • Tidak ada batas panjang baris yang ketat. Komentar panjang dan string panjang sering kali dibagi menjadi 79 kolom, tetapi tidak wajib. Hal ini tidak boleh diterapkan dalam peninjauan kode atau skrip pra-pengiriman. Alasan: Label dapat panjang dan melebihi batas ini. File BUILD biasanya dihasilkan atau diedit oleh alat, dan tidak sesuai dengan batas panjang baris.

  • Penggabungan string implisit tidak didukung. Gunakan operator +. Alasan: File BUILD berisi banyak daftar string. Kita sering kali melupakan koma, yang menyebabkan hasil yang sama sekali berbeda. Hal ini telah menyebabkan banyak bug di masa lalu. Lihat juga diskusi ini.

  • Gunakan spasi di sekitar tanda = untuk argumen kata kunci dalam aturan. Alasan: Argumen bernama jauh lebih sering digunakan daripada di Python dan selalu berada di baris terpisah. Spasi meningkatkan keterbacaan. Konvensi ini sudah ada sejak lama, dan tidak perlu mengubah semua file BUILD yang ada.

  • Secara default, gunakan tanda kutip ganda untuk string. Alasan: Hal ini tidak ditentukan dalam panduan gaya Python, tetapi merekomendasikan konsistensi. Jadi, kita memutuskan untuk hanya menggunakan string dengan tanda kutip ganda. Banyak bahasa menggunakan tanda petik ganda untuk literal string.

  • Gunakan satu baris kosong antara dua definisi tingkat atas. Alasan: Struktur file BUILD tidak seperti file Python biasa. File ini hanya memiliki pernyataan tingkat teratas. Menggunakan satu baris kosong akan membuat file BUILD lebih pendek.