Konfigurasi Toolchain C++

Ringkasan

Untuk memanggil compiler dengan opsi yang tepat, Bazel memerlukan beberapa pengetahuan tentang internal compiler, seperti direktori include dan tanda penting. Dengan kata lain, Bazel memerlukan model kompilator yang disederhanakan untuk memahami cara kerjanya.

Bazel perlu mengetahui hal berikut:

• Apakah compiler mendukung thinLTO, modul, penautan dinamis, atau PIC (kode independen posisi).
• Jalur ke alat yang diperlukan seperti gcc, ld, ar, objcopy, dan sebagainya.
• Direktori include sistem bawaan. Bazel memerlukan informasi ini untuk memvalidasi bahwa semua header yang disertakan dalam file sumber telah dideklarasikan dengan benar dalam file BUILD.
• Sysroot default.
• Flag yang akan digunakan untuk kompilasi, penautan, pengarsipan.
• Flag mana yang akan digunakan untuk mode kompilasi yang didukung (opt, dbg, fastbuild).
• Membuat variabel yang secara khusus diperlukan oleh compiler.

Jika compiler memiliki dukungan untuk beberapa arsitektur, Bazel perlu mengonfigurasinya secara terpisah.

CcToolchainConfigInfo adalah penyedia yang memberikan tingkat perincian yang diperlukan untuk mengonfigurasi perilaku aturan C++ Bazel. Secara default, Bazel otomatis mengonfigurasi CcToolchainConfigInfo untuk build Anda, tetapi Anda memiliki opsi untuk mengonfigurasinya secara manual. Untuk itu, Anda memerlukan aturan Starlark yang menyediakan CcToolchainConfigInfo dan Anda perlu mengarahkan atribut toolchain_config dari cc_toolchain ke aturan Anda. Anda dapat membuat CcToolchainConfigInfo dengan memanggil cc_common.create_cc_toolchain_config_info(). Anda dapat menemukan konstruktor Starlark untuk semua struct yang akan Anda perlukan dalam proses di @rules_cc//cc:cc_toolchain_config_lib.bzl.

Saat target C++ memasuki fase analisis, Bazel memilih target cc_toolchain yang sesuai berdasarkan file BUILD, dan mendapatkan penyedia CcToolchainConfigInfo dari target yang ditentukan dalam atribut cc_toolchain.toolchain_config. Target cc_toolchain meneruskan informasi ini ke target C++ melalui CcToolchainProvider.

Misalnya, tindakan kompilasi atau penautan, yang di-instansiasi oleh aturan seperti cc_binary atau cc_library, memerlukan informasi berikut:

• Compiler atau linker yang akan digunakan
• Tanda command line untuk compiler/linker
• Tanda konfigurasi yang diteruskan melalui opsi --copt/--linkopt
• Variabel lingkungan
• Artefak yang diperlukan di sandbox tempat tindakan dieksekusi

Semua informasi di atas, kecuali artefak yang diperlukan di sandbox, ditentukan dalam target Starlark yang ditunjuk oleh cc_toolchain.

Artefak yang akan dikirim ke sandbox dideklarasikan dalam target cc_toolchain. Misalnya, dengan atribut cc_toolchain.linker_files, Anda dapat menentukan biner linker dan library toolchain yang akan dikirim ke sandbox.

Pemilihan toolchain

Logika pemilihan toolchain beroperasi sebagai berikut:

1. Pengguna menentukan target cc_toolchain_suite dalam file BUILD dan mengarahkan Bazel ke target menggunakan opsi --crosstool_top.

2. Target cc_toolchain_suite mereferensikan beberapa toolchain. Nilai flag --cpu dan --compiler menentukan toolchain mana yang dipilih, baik hanya berdasarkan nilai flag --cpu, atau berdasarkan nilai --cpu | --compiler gabungan. Proses seleksinya adalah sebagai berikut:

   • Jika opsi --compiler ditentukan, Bazel akan memilih entri yang sesuai dari atribut cc_toolchain_suite.toolchains dengan --cpu | --compiler. Jika Bazel tidak menemukan entri yang sesuai, Bazel akan menampilkan error.

   • Jika opsi --compiler tidak ditentukan, Bazel akan memilih entri yang sesuai dari atribut cc_toolchain_suite.toolchains hanya dengan --cpu.

   • Jika tidak ada flag yang ditentukan, Bazel akan memeriksa sistem host dan memilih nilai --cpu berdasarkan temuannya. Lihat kode mekanisme pemeriksaan.

Setelah toolchain dipilih, objek feature dan action_config yang sesuai dalam aturan Starlark akan mengatur konfigurasi build (yaitu, item yang dijelaskan nanti). Pesan ini memungkinkan penerapan fitur C++ yang lengkap di Bazel tanpa mengubah biner Bazel. Aturan C++ mendukung beberapa tindakan unik yang didokumentasikan secara mendetail dalam kode sumber Bazel.

Fitur

Fitur adalah entitas yang memerlukan tanda command line, tindakan, batasan pada lingkungan eksekusi, atau perubahan dependensi. Fitur dapat berupa hal sederhana seperti mengizinkan file BUILD untuk memilih konfigurasi flag, seperti treat_warnings_as_errors, atau berinteraksi dengan aturan C++ dan menyertakan tindakan dan input kompilasi baru ke kompilasi, seperti header_modules atau thin_lto.

Idealnya, CcToolchainConfigInfo berisi daftar fitur, dengan setiap fitur terdiri dari satu atau beberapa grup tanda, yang masing-masing menentukan daftar tanda yang berlaku untuk tindakan Bazel tertentu.

Fitur ditentukan berdasarkan nama, yang memungkinkan pelepasan penuh konfigurasi aturan Starlark dari rilis Bazel. Dengan kata lain, rilis Bazel tidak memengaruhi perilaku konfigurasi CcToolchainConfigInfo selama konfigurasi tersebut tidak memerlukan penggunaan fitur baru.

Fitur diaktifkan dengan salah satu cara berikut:

• Kolom enabled fitur disetel ke true.
• Bazel atau pemilik aturan mengaktifkannya secara eksplisit.
• Pengguna mengaktifkannya melalui opsi Bazel --feature atau atribut aturan features.

Fitur dapat memiliki saling ketergantungan, bergantung pada tanda command line, setelan file BUILD, dan variabel lainnya.

Hubungan fitur

Dependensi biasanya dikelola langsung dengan Bazel, yang hanya menerapkan persyaratan dan mengelola konflik yang melekat pada sifat fitur yang ditentukan dalam build. Spesifikasi toolchain memungkinkan batasan yang lebih terperinci untuk digunakan langsung dalam aturan Starlark yang mengatur dukungan dan perluasan fitur. Karakter pengganti ini meliputi:

requires = [
   feature_set (features = [
       'feature-name-1',
       'feature-name-2'
   ]),
]

implies = ['feature']

provides = ['feature']

with_features = [
  with_feature_set(
    features = ['feature-1'],
    not_features = ['feature-2'],
  ),
]

Tindakan

Tindakan memberikan fleksibilitas untuk mengubah kondisi saat tindakan dijalankan tanpa mengasumsikan cara tindakan akan dijalankan. action_config menentukan biner alat yang dipanggil oleh tindakan, sedangkan feature menentukan konfigurasi (flag) yang menentukan perilaku alat tersebut saat tindakan dipanggil.

Tindakan referensi Fitur untuk memberi sinyal tindakan Bazel mana yang terpengaruh karena tindakan dapat mengubah grafik tindakan Bazel. Penyedia CcToolchainConfigInfo berisi tindakan yang memiliki tanda dan alat yang terkait dengannya, seperti c++-compile. Flag ditetapkan ke setiap tindakan dengan mengaitkannya dengan fitur.

Setiap nama tindakan mewakili satu jenis tindakan yang dilakukan oleh Bazel, seperti mengompilasi atau menautkan. Namun, ada hubungan banyak-ke-satu antara tindakan dan jenis tindakan Bazel, di mana jenis tindakan Bazel mengacu pada class Java yang menerapkan tindakan (seperti CppCompileAction). Khususnya, "tindakan assembler" dan "tindakan compiler" dalam tabel di bawah adalah CppCompileAction, sedangkan tindakan penautan adalah CppLinkAction.

Tindakan assembler

Tindakan compiler

Tindakan link

Tindakan AR

Tindakan AR mengumpulkan file objek ke dalam library arsip (file .a) melalui ar dan mengenkode beberapa semantik ke dalam nama.

Tindakan LTO

Menggunakan action_config

action_config adalah struktur Starlark yang menjelaskan tindakan Bazel dengan menentukan alat (biner) yang akan dipanggil selama tindakan dan kumpulan flag, yang ditentukan oleh fitur. Flag ini menerapkan batasan pada eksekusi tindakan.

Konstruktor action_config() memiliki parameter berikut:

action_config dapat mewajibkan dan menyiratkan fitur dan action_config lain sebagaimana ditentukan oleh hubungan fitur yang dijelaskan sebelumnya. Perilaku ini mirip dengan perilaku fitur.

Dua atribut terakhir berlebihan terhadap atribut yang sesuai pada fitur dan disertakan karena beberapa tindakan Bazel memerlukan flag atau variabel lingkungan tertentu dan tujuannya adalah untuk menghindari pasangan action_config+feature yang tidak perlu. Biasanya, berbagi satu fitur di beberapa action_config lebih disukai.

Anda tidak dapat menentukan lebih dari satu action_config dengan action_name yang sama dalam toolchain yang sama. Hal ini mencegah ambiguitas dalam jalur alat dan menerapkan maksud di balik action_config - bahwa properti tindakan dijelaskan dengan jelas di satu tempat dalam toolchain.

Menggunakan konstruktor alat

action_config dapat menentukan sekumpulan alat melalui parameter tools-nya. Konstruktor tool() menggunakan parameter berikut:

Untuk action_config tertentu, hanya satu tool yang menerapkan jalur alat dan persyaratan eksekusinya ke tindakan Bazel. Alat dipilih dengan melakukan iterasi melalui atribut tools pada action_config hingga alat dengan set with_feature yang cocok dengan konfigurasi fitur ditemukan (lihat Hubungan fitur sebelumnya di halaman ini untuk mengetahui informasi selengkapnya). Anda harus mengakhiri daftar alat dengan alat default yang sesuai dengan konfigurasi fitur kosong.

Contoh penggunaan

Fitur dan tindakan dapat digunakan bersama untuk menerapkan tindakan Bazel dengan semantik lintas platform yang beragam. Misalnya, pembuatan simbol debug di macOS memerlukan pembuatan simbol dalam tindakan kompilasi, lalu memanggil alat khusus selama tindakan penautan untuk membuat arsip dsym terkompresi, dan kemudian mendekompresi arsip tersebut untuk menghasilkan bundle aplikasi dan file .plist yang dapat digunakan oleh Xcode.

Dengan Bazel, proses ini dapat diterapkan sebagai berikut, dengan unbundle-debuginfo menjadi tindakan Bazel:

load("@rules_cc//cc:defs.bzl", "ACTION_NAMES")

action_configs = [
    action_config (
        action_name = ACTION_NAMES.cpp_link_executable,
        tools = [
            tool(
                with_features = [
                    with_feature(features=["generate-debug-symbols"]),
                ],
                path = "toolchain/mac/ld-with-dsym-packaging",
            ),
            tool (path = "toolchain/mac/ld"),
        ],
    ),
]

features = [
    feature(
        name = "generate-debug-symbols",
        flag_sets = [
            flag_set (
                actions = [
                    ACTION_NAMES.c_compile,
                    ACTION_NAMES.cpp_compile
                ],
                flag_groups = [
                    flag_group(
                        flags = ["-g"],
                    ),
                ],
            )
        ],
        implies = ["unbundle-debuginfo"],
   ),
]

Fitur yang sama ini dapat diimplementasikan secara berbeda untuk Linux, yang menggunakan fission, atau untuk Windows, yang menghasilkan file .pdb. Misalnya, penerapan untuk pembuatan simbol debug berbasis fission mungkin terlihat seperti berikut:

load("@rules_cc//cc:defs.bzl", "ACTION_NAMES")

action_configs = [
    action_config (
        name = ACTION_NAMES.cpp_compile,
        tools = [
            tool(
                path = "toolchain/bin/gcc",
            ),
        ],
    ),
]

features = [
    feature (
        name = "generate-debug-symbols",
        requires = [with_feature_set(features = ["dbg"])],
        flag_sets = [
            flag_set(
                actions = [ACTION_NAMES.cpp_compile],
                flag_groups = [
                    flag_group(
                        flags = ["-gsplit-dwarf"],
                    ),
                ],
            ),
            flag_set(
                actions = [ACTION_NAMES.cpp_link_executable],
                flag_groups = [
                    flag_group(
                        flags = ["-Wl", "--gdb-index"],
                    ),
                ],
            ),
      ],
    ),
]

Grup tanda

CcToolchainConfigInfo memungkinkan Anda mengelompokkan tanda ke dalam grup yang memenuhi tujuan tertentu. Anda dapat menentukan tanda di dalamnya menggunakan variabel yang telah ditentukan sebelumnya dalam nilai tanda, yang diperluas oleh compiler saat menambahkan tanda ke perintah build. Contoh:

flag_group (
    flags = ["%{output_execpath}"],
)

Dalam hal ini, konten tanda akan diganti dengan jalur file output tindakan.

Grup tanda diuraikan ke perintah build sesuai urutan kemunculannya dalam daftar, dari atas ke bawah, kiri ke kanan.

Untuk tanda yang perlu diulang dengan nilai yang berbeda saat ditambahkan ke perintah build, grup tanda dapat melakukan iterasi variabel jenis list. Misalnya, variabel include_path berjenis list:

flag_group (
    iterate_over = "include_paths",
    flags = ["-I%{include_paths}"],
)

meluas menjadi -I<path> untuk setiap elemen jalur dalam daftar include_paths. Semua flag (atau flag_group) dalam isi deklarasi grup flag diperluas sebagai satu unit. Contoh:

flag_group (
    iterate_over = "include_paths",
    flags = ["-I", "%{include_paths}"],
)

meluas menjadi -I <path> untuk setiap elemen jalur dalam daftar include_paths.

Variabel dapat diulang beberapa kali. Contoh:

flag_group (
    iterate_over = "include_paths",
    flags = ["-iprefix=%{include_paths}", "-isystem=%{include_paths}"],
)

meluas menjadi:

-iprefix=<inc0> -isystem=<inc0> -iprefix=<inc1> -isystem=<inc1>

Variabel dapat sesuai dengan struktur yang dapat diakses menggunakan notasi titik. Contoh:

flag_group (
    flags = ["-l%{libraries_to_link.name}"],
)

Struktur dapat bertingkat dan juga dapat berisi urutan. Untuk mencegah konflik nama dan agar lebih jelas, Anda harus menentukan jalur lengkap melalui kolom. Contoh:

flag_group (
    iterate_over = "libraries_to_link",
    flag_groups = [
        flag_group (
            iterate_over = "libraries_to_link.shared_libraries",
            flags = ["-l%{libraries_to_link.shared_libraries.name}"],
        ),
    ],
)

Perluasan bersyarat

Grup flag mendukung perluasan bersyarat berdasarkan keberadaan variabel tertentu atau kolomnya menggunakan atribut expand_if_available, expand_if_not_available, expand_if_true, expand_if_false, atau expand_if_equal. Contoh:

flag_group (
    iterate_over = "libraries_to_link",
    flag_groups = [
        flag_group (
            iterate_over = "libraries_to_link.shared_libraries",
            flag_groups = [
                flag_group (
                    expand_if_available = "libraries_to_link.shared_libraries.is_whole_archive",
                    flags = ["--whole_archive"],
                ),
                flag_group (
                    flags = ["-l%{libraries_to_link.shared_libraries.name}"],
                ),
                flag_group (
                    expand_if_available = "libraries_to_link.shared_libraries.is_whole_archive",
                    flags = ["--no_whole_archive"],
                ),
            ],
        ),
    ],
)

Referensi CcToolchainConfigInfo

Bagian ini memberikan referensi variabel build, fitur, dan informasi lain yang diperlukan untuk berhasil mengonfigurasi aturan C++.

Variabel build CcToolchainConfigInfo

Berikut adalah referensi variabel build CcToolchainConfigInfo.

Fitur yang sudah dikenal

Berikut adalah referensi fitur dan kondisi aktivasinya.

Logika penambalan fitur lama

Bazel menerapkan perubahan berikut pada fitur toolchain untuk kompatibilitas mundur:

• Memindahkan fitur legacy_compile_flags ke bagian atas toolchain
• Memindahkan fitur default_compile_flags ke bagian atas toolchain
• Menambahkan fitur dependency_file (jika tidak ada) ke bagian atas toolchain
• Menambahkan fitur pic (jika tidak ada) ke bagian atas toolchain
• Menambahkan fitur per_object_debug_info (jika tidak ada) ke bagian atas toolchain
• Menambahkan fitur preprocessor_defines (jika tidak ada) ke bagian atas toolchain
• Menambahkan fitur includes (jika tidak ada) ke bagian atas toolchain
• Menambahkan fitur include_paths (jika tidak ada) ke bagian atas toolchain
• Menambahkan fitur fdo_instrument (jika tidak ada) ke bagian atas toolchain
• Menambahkan fitur fdo_optimize (jika tidak ada) ke bagian atas toolchain
• Menambahkan fitur cs_fdo_instrument (jika tidak ada) ke bagian atas toolchain
• Menambahkan fitur cs_fdo_optimize (jika tidak ada) ke bagian atas toolchain
• Menambahkan fitur fdo_prefetch_hints (jika tidak ada) ke bagian atas toolchain
• Menambahkan fitur autofdo (jika tidak ada) ke bagian atas toolchain
• Menambahkan fitur build_interface_libraries (jika tidak ada) ke bagian atas toolchain
• Menambahkan fitur dynamic_library_linker_tool (jika tidak ada) ke bagian atas toolchain
• Menambahkan fitur shared_flag (jika tidak ada) ke bagian atas toolchain
• Menambahkan fitur linkstamps (jika tidak ada) ke bagian atas toolchain
• Menambahkan fitur output_execpath_flags (jika tidak ada) ke bagian atas toolchain
• Menambahkan fitur runtime_library_search_directories (jika tidak ada) ke bagian atas toolchain
• Menambahkan fitur library_search_directories (jika tidak ada) ke bagian atas toolchain
• Menambahkan fitur archiver_flags (jika tidak ada) ke bagian atas toolchain
• Menambahkan fitur libraries_to_link (jika tidak ada) ke bagian atas toolchain
• Menambahkan fitur force_pic_flags (jika tidak ada) ke bagian atas toolchain
• Menambahkan fitur user_link_flags (jika tidak ada) ke bagian atas toolchain
• Menambahkan fitur legacy_link_flags (jika tidak ada) ke bagian atas toolchain
• Menambahkan fitur static_libgcc (jika tidak ada) ke bagian atas toolchain
• Menambahkan fitur fission_support (jika tidak ada) ke bagian atas toolchain
• Menambahkan fitur strip_debug_symbols (jika tidak ada) ke bagian atas toolchain
• Menambahkan fitur coverage (jika tidak ada) ke bagian atas toolchain
• Menambahkan fitur llvm_coverage_map_format (jika tidak ada) ke bagian atas toolchain
• Menambahkan fitur gcc_coverage_map_format (jika tidak ada) ke bagian atas toolchain
• Menambahkan fitur fully_static_link (jika tidak ada) ke bagian bawah toolchain
• Menambahkan fitur user_compile_flags (jika tidak ada) ke bagian bawah toolchain
• Menambahkan fitur sysroot (jika tidak ada) ke bagian bawah toolchain
• Menambahkan fitur unfiltered_compile_flags (jika tidak ada) ke bagian bawah toolchain
• Menambahkan fitur linker_param_file (jika tidak ada) ke bagian bawah toolchain
• Menambahkan fitur compiler_input_flags (jika tidak ada) ke bagian bawah toolchain
• Menambahkan fitur compiler_output_flags (jika tidak ada) ke bagian bawah toolchain

Ini adalah daftar panjang fitur. Rencananya adalah menghapusnya setelah Crosstool di Starlark selesai. Untuk pembaca yang ingin tahu, lihat implementasinya di CppActionConfigs, dan untuk toolchain produksi, pertimbangkan untuk menambahkan no_legacy_features agar toolchain lebih mandiri.