Tutorial Bazel: Mem-build Project C++

Laporkan masalah Lihat sumber Per malam · 7,3 · 7,2 · 7,1 · 7,0 · 6,5

Pengantar

Baru mengenal Bazel? Anda berada di tempat yang tepat. Ikuti tutorial Pembuatan Pertama ini untuk mendapatkan pengantar sederhana tentang penggunaan Bazel. Tutorial ini mendefinisikan istilah kunci seperti digunakan dalam konteks Bazel dan memandu Anda memahami dasar-dasar Bazel alur kerja. Dimulai dengan alat yang Anda perlukan, Anda akan membangun dan menjalankan tiga proyek dengan kompleksitas yang meningkat dan mempelajari bagaimana dan mengapa proyek itu menjadi lebih kompleks.

Meskipun Bazel adalah sistem build yang mendukung build multibahasa, tutorial ini menggunakan project C++ sebagai contoh serta memberikan pedoman dan alur umum yang berlaku untuk sebagian besar bahasa.

Perkiraan waktu penyelesaian: 30 menit.

Prasyarat

Mulailah dengan menginstal Bazel, jika Anda belum melakukannya . Tutorial ini menggunakan Git untuk kontrol sumber, sehingga untuk hasil terbaik instal Git.

Selanjutnya, ambil proyek contoh dari repositori GitHub Bazel dengan menjalankan berikut di alat command line pilihan Anda:

git clone https://github.com/bazelbuild/examples

Project contoh untuk tutorial ini ada dalam examples/cpp-tutorial saat ini.

Lihat bagaimana strukturnya:

examples
└── cpp-tutorial
    ├──stage1
    │  ├── main
    │  │   ├── BUILD
    │  │   └── hello-world.cc
    │  └── MODULE.bazel
    ├──stage2
    │  ├── main
    │  │   ├── BUILD
    │  │   ├── hello-world.cc
    │  │   ├── hello-greet.cc
    │  │   └── hello-greet.h
    │  └── MODULE.bazel
    └──stage3
       ├── main
       │   ├── BUILD
       │   ├── hello-world.cc
       │   ├── hello-greet.cc
       │   └── hello-greet.h
       ├── lib
       │   ├── BUILD
       │   ├── hello-time.cc
       │   └── hello-time.h
       └── MODULE.bazel

Ada tiga kumpulan file, masing-masing kumpulan mewakili satu tahapan dalam tutorial ini. Pada tahap pertama, Anda akan membangun satu target yang berada dalam satu paket. Pada tahap kedua, Anda akan membangun biner dan library dari satu paket. Di pertemuan ketiga dan terakhir Anda akan membangun proyek dengan beberapa paket dan membangunnya dengan beberapa target.

Ringkasan: Pengantar

Dengan menginstal Bazel (dan Git) serta meng-clone repositori untuk tutorial ini, Anda telah meletakkan fondasi untuk bangunan pertama Anda dengan Bazel. Lanjutkan ke berikutnya untuk mendefinisikan beberapa istilah dan menyiapkan workspace.

Memulai

Sebelum dapat membuat project, Anda perlu menyiapkan ruang kerjanya. Ruang kerja adalah direktori yang menyimpan file sumber proyek Anda dan {i>output<i} build Bazel. File penting berikut juga berisi:

  • File MODULE.bazel, yang mengidentifikasi direktori dan kontennya sebagai ruang kerja Bazel dan berada di {i>root<i} dari direktori proyek karena ada berbagai struktur penetapan harga. Di sini juga Anda menentukan dependensi eksternal.
  • Satu atau lebih BUILD file, yang akan memberi tahu Bazel bagaimana membangun bagian-bagian proyek yang berbeda. Direktori di dalam ruang kerja yang berisi file BUILD adalah paket. (Selengkapnya tentang paket nanti di tutorial ini.)

Dalam proyek yang akan datang, untuk menetapkan direktori sebagai ruang kerja Bazel, buat file kosong bernama MODULE.bazel di direktori tersebut. Untuk tujuan tutorial, file MODULE.bazel sudah ada di setiap tahap.

Memahami file BUILD

File BUILD berisi beberapa jenis petunjuk yang berbeda untuk Bazel. Masing-masing File BUILD memerlukan setidaknya satu rule sebagai kumpulan petunjuk, yang memberi tahu Bazel cara membangun {i>output<i} yang Anda inginkan, seperti biner yang dapat dieksekusi atau perpustakaan. Setiap instance aturan build dalam file BUILD disebut target dan mengarah ke kumpulan {i>file<i} sumber dan dependensi. Target dapat juga mengarah ke target lain.

Lihat file BUILD di direktori cpp-tutorial/stage1/main:

cc_binary(
    name = "hello-world",
    srcs = ["hello-world.cc"],
)

Dalam contoh kita, target hello-world membuat instance bawaan Bazel Aturan cc_binary. Aturan memerintahkan Bazel untuk membangun biner yang dapat dieksekusi mandiri dari hello-world.cc&gt; file sumber tanpa dependensi.

Ringkasan: memulai

Sekarang Anda telah mengenal beberapa istilah kunci, dan apa artinya dalam konteks proyek ini dan Bazel secara umum. Pada bagian berikutnya, Anda akan membangun dan menguji Tahap 1 proyek.

Tahap 1: target tunggal, paket tunggal

Saatnya membangun bagian pertama proyek. Untuk referensi visual, struktur bagian Tahap 1 dari proyek adalah:

examples
└── cpp-tutorial
    └──stage1
       ├── main
       │   ├── BUILD
       │   └── hello-world.cc
       └── MODULE.bazel

Jalankan perintah berikut untuk berpindah ke direktori cpp-tutorial/stage1:

cd cpp-tutorial/stage1

Kemudian jalankan:

bazel build //main:hello-world

Di label target, bagian //main: adalah lokasi file BUILD relatif terhadap root ruang kerja, dan hello-world adalah nama target di file BUILD.

Bazel menghasilkan sesuatu yang terlihat seperti ini:

INFO: Found 1 target...
Target //main:hello-world up-to-date:
  bazel-bin/main/hello-world
INFO: Elapsed time: 2.267s, Critical Path: 0.25s

Kamu baru saja membuat target Bazel pertama. Menempatkan Bazel membuat output di Direktori bazel-bin di root ruang kerja.

Sekarang uji biner yang baru Anda bangun, yaitu:

bazel-bin/main/hello-world

Tindakan ini akan menghasilkan "Hello world" yang dicetak untuk membuat pesan email baru.

Berikut adalah grafik dependensi Tahap 1:

Grafik dependensi untuk hello-world menampilkan satu target dengan satu sumber .

Ringkasan: tahap 1

Sekarang setelah menyelesaikan pembangunan pertama, Anda memiliki gagasan dasar tentang bagaimana adalah struktur yang terstruktur. Pada tahap selanjutnya, Anda akan menambahkan kompleksitas dengan menambahkan target lain.

Tahap 2: beberapa target build

Meskipun satu target sudah cukup untuk project kecil, sebaiknya Anda membagi proyek yang lebih besar menjadi beberapa target dan paket. Hal ini memungkinkan tambahan – yaitu, Bazel hanya membangun ulang apa yang berubah – dan mempercepat build Anda dengan membangun beberapa bagian proyek sekaligus. Tahap ini tutorial menambahkan target, dan selanjutnya menambahkan paket.

Ini adalah direktori yang sedang Anda gunakan untuk Tahap 2:

    ├──stage2
    │  ├── main
    │  │   ├── BUILD
    │  │   ├── hello-world.cc
    │  │   ├── hello-greet.cc
    │  │   └── hello-greet.h
    │  └── MODULE.bazel

Lihat file BUILD di direktori cpp-tutorial/stage2/main:

cc_library(
    name = "hello-greet",
    srcs = ["hello-greet.cc"],
    hdrs = ["hello-greet.h"],
)

cc_binary(
    name = "hello-world",
    srcs = ["hello-world.cc"],
    deps = [
        ":hello-greet",
    ],
)

Dengan file BUILD ini, Bazel terlebih dahulu membangun library hello-greet (menggunakan Fitur bawaan Bazel cc_library aturan), maka Biner hello-world. Atribut deps dalam target hello-world memberi tahu Bazel bahwa library hello-greet diperlukan untuk membangun hello-world biner.

Sebelum dapat membangun versi baru project ini, Anda perlu melakukan perubahan direktori, beralih ke direktori cpp-tutorial/stage2 dengan menjalankan:

cd ../stage2

Sekarang Anda dapat membangun biner baru menggunakan perintah yang sudah dikenal berikut:

bazel build //main:hello-world

Sekali lagi, Bazel menghasilkan sesuatu yang terlihat seperti ini:

INFO: Found 1 target...
Target //main:hello-world up-to-date:
  bazel-bin/main/hello-world
INFO: Elapsed time: 2.399s, Critical Path: 0.30s

Sekarang Anda dapat menguji biner yang baru dibangun, yang menampilkan "Hello world" lain:

bazel-bin/main/hello-world

Jika sekarang Anda mengubah hello-greet.cc dan mem-build ulang project, hanya Bazel akan mengompilasi ulang file tersebut.

Dengan melihat grafik dependensi, Anda dapat melihat bahwa hello-world bergantung pada input tambahan bernama hello-greet:

Grafik dependensi untuk `hello-world` menampilkan perubahan dependensi setelah perubahan pada file.

Ringkasan: tahap 2

Sekarang Anda telah membangun proyek dengan dua target. Target hello-world di-build satu file sumber dan bergantung pada satu target lain (//main:hello-greet), yang membangun dua file sumber tambahan. Di bagian berikutnya, lakukan lebih jauh dan menambahkan paket lain.

Tahap 3: beberapa paket

Tahap berikutnya ini menambahkan lapisan detail lain dan membangun project dengan beberapa paket. Lihatlah struktur dan isi dari Direktori cpp-tutorial/stage3:

└──stage3
   ├── main
   │   ├── BUILD
   │   ├── hello-world.cc
   │   ├── hello-greet.cc
   │   └── hello-greet.h
   ├── lib
   │   ├── BUILD
   │   ├── hello-time.cc
   │   └── hello-time.h
   └── MODULE.bazel

Anda dapat melihat bahwa sekarang ada dua subdirektori, dan masing-masing berisi BUILD . Oleh karena itu, bagi Bazel, ruang kerja sekarang berisi dua paket: lib dan main.

Lihat file lib/BUILD:

cc_library(
    name = "hello-time",
    srcs = ["hello-time.cc"],
    hdrs = ["hello-time.h"],
    visibility = ["//main:__pkg__"],
)

Dan pada file main/BUILD:

cc_library(
    name = "hello-greet",
    srcs = ["hello-greet.cc"],
    hdrs = ["hello-greet.h"],
)

cc_binary(
    name = "hello-world",
    srcs = ["hello-world.cc"],
    deps = [
        ":hello-greet",
        "//lib:hello-time",
    ],
)

Target hello-world dalam paket utama bergantung pada target hello-time dalam paket lib (maka label target //lib:hello-time) - Bazel tahu ini melalui atribut deps. Anda dapat melihatnya di dependensi {i>graphic<i}:

Grafik dependensi untuk `hello-world` menampilkan cara target dalam paket utama bergantung pada target di `lib` paket.

Agar build berhasil, Anda membuat target //lib:hello-time di lib/BUILD terlihat secara eksplisit oleh target di main/BUILD menggunakan atribut visibilitas. Hal ini karena target default hanya terlihat oleh target lain dalam File BUILD. Bazel menggunakan visibilitas target untuk mencegah masalah seperti library berisi detail implementasi yang bocor ke API publik.

Sekarang, bangun project versi akhir ini. Beralih ke cpp-tutorial/stage3 dengan menjalankan:

cd  ../stage3

Sekali lagi, jalankan perintah berikut:

bazel build //main:hello-world

Bazel menghasilkan sesuatu yang terlihat seperti ini:

INFO: Found 1 target...
Target //main:hello-world up-to-date:
  bazel-bin/main/hello-world
INFO: Elapsed time: 0.167s, Critical Path: 0.00s

Sekarang uji biner terakhir dalam tutorial ini untuk melihat pesan Hello world akhir:

bazel-bin/main/hello-world

Ringkasan: tahap 3

Anda sekarang telah membangun proyek sebagai dua paket dengan tiga target dan memahami ketergantungan di antara mereka, yang memungkinkan Anda untuk maju dan membangun masa depan proyek bersama Bazel. Di bagian berikutnya, lihat cara melanjutkan Perjalanan Bazel.

Langkah berikutnya

Anda sekarang telah menyelesaikan pembangunan dasar pertama dengan Bazel, tetapi ini hanyalah memulai. Berikut beberapa referensi lainnya untuk melanjutkan pembelajaran dengan Bazel:

Selamat membangun!