C++ Araç Zinciri Yapılandırması

Genel Bakış

Derleyiciyi doğru seçeneklerle çağırmak için Bazel'in derleyicinin dahil edilen dizinleri ve önemli işaretçileri gibi dahili özellikleri hakkında bilgi sahibi olması gerekir. Diğer bir deyişle, Bazel'in çalışma şeklini anlamak için derleyicinin basitleştirilmiş bir modeline ihtiyacı vardır.

Bazel'in bilmesi gerekenler:

• Derleyicinin ince LTO'yu, modülleri, dinamik bağlantıyı veya PIC'yi (konumdan bağımsız kod) destekleyip desteklemediği.
• gcc, ld, ar, objcopy vb. gerekli araçların yolları.
• Yerleşik sistem dizinleri içerir. Bazel'in bunları doğrulamak için kaynak dosyada yer alan tüm üstbilgilerin gerektiği gibi BUILD dosyası.
• Varsayılan sysroot.
• Derleme, bağlama, arşivleme için kullanılacak işaretler.
• Desteklenen derleme modları (opt, dbg, fastbuild) için kullanılacak işaretler.
• Derleyici tarafından özellikle gerekli kılınan değişkenleri yapın.

Derleyici birden fazla mimariyi destekliyorsa Bazel'in bunları ayrı ayrı yapılandırması gerekir.

CcToolchainConfigInfo, ihtiyacınız olan ek düzeyde ayrıntı düzeyini artırır. Bazel, varsayılan olarak CcToolchainConfigInfo'ü derlemeniz için otomatik olarak yapılandırır ancak manuel olarak yapılandırabilirsiniz. Bunun için CcToolchainConfigInfo sağlayan bir Starlark kuralına ihtiyacınız vardır ve cc_toolchain öğesinin toolchain_config özelliğini kuralınıza yönlendirmeniz gerekir. Şu numarayı arayarak CcToolchainConfigInfo oluşturabilirsiniz: cc_common.create_cc_toolchain_config_info() İşlemde ihtiyacınız olacak tüm struct'lar için Starlark oluşturucularını @rules_cc//cc:cc_toolchain_config_lib.bzl.

C++ hedefi analiz aşamasına geçtiğinde, Bazel uygun BUILD dosyasını temel alarak cc_toolchain hedefini belirler ve Şurada belirtilen hedeften CcToolchainConfigInfo sağlayıcı: cc_toolchain.toolchain_config özelliği için geçerlidir. cc_toolchain hedefi, bu bilgileri bir CcToolchainProvider aracılığıyla C++ hedefine iletir.

Örneğin, cc_binary veya cc_library için şu bilgiler gerekiyor:

• Kullanılacak derleyici veya bağlayıcı
• Derleyici/bağlantılayıcı için komut satırı işaretleri
• --copt/--linkopt seçenekleri aracılığıyla iletilen yapılandırma işaretleri
• Ortam değişkenleri
• İşlemin yürütüleceği korumalı alanda gereken yapılar

Korumalı alanda gerekli olan yapılar hariç yukarıdaki bilgilerin tümü cc_toolchain öğesinin işaret ettiği Starlark hedefinde belirtilir.

Korumalı alana gönderilecek yapı taşları cc_toolchain hedefinde belirtilir. Örneğin, cc_toolchain.linker_files özelliğiyle şunları yapabilirsiniz: korumalı alana gönderilecek bağlayıcı ikili programı ve araç zinciri kitaplıklarını belirtir.

Araç zinciri seçimi

Araç zinciri seçim mantığı aşağıdaki gibi çalışır:

1. Kullanıcı, BUILD dosyasında bir cc_toolchain_suite hedefi belirtir ve --crosstool_top seçeneğini kullanarak Bazel'i hedefe yönlendirir.

2. cc_toolchain_suite hedefi birden fazla araç zincirine referans veriyor. --cpu ve --compiler işaretlerinin değerleri, yalnızca --cpu işareti değerine veya ortak bir --cpu | --compiler değerine göre bu araç takımlarından hangisinin seçileceğini belirler. Seçim süreci aşağıdaki gibidir:

   • --compiler seçeneği belirtilirse Bazel, --cpu | --compiler ile cc_toolchain_suite.toolchains özelliğindeki ilgili girişi seçer. Bazel giriş yaparsa hata verir.

   • --compiler seçeneği belirtilmezse Bazel, cc_toolchain_suite.toolchains özelliğindeki ilgili girişi yalnızca --cpu ile seçer.

   • Herhangi bir işaret belirtilmezse Bazel, ana makine sistemini inceler ve bir seçim --cpu değeri. Bkz. inceleme mekanizması kodu ekleyin.

Bir araç zinciri seçildikten sonra karşılık gelen feature ve action_config Starlark kuralındaki nesneler, yapının (yani öğeler için de ekleyebilirsiniz. Bu mesajlar, hiçbir değişiklik yapmadan Bazel'deki tam C++ özelliklerini Bazel ikili programı. C++ kuralları, Bazel kaynak kodunda ayrıntılı olarak açıklanan birden fazla benzersiz işlemi destekler.

Özellikler

Özellik, komut satırı işaretleri, işlemler ve işlemler gerektiren bir varlıktır. ya da bağımlılık değişiklikleri olabilir. Özellik BUILD dosyalarının şu yapılandırmaları seçmesine izin vermek kadar basit bir şey olabilir: treat_warnings_as_errors gibi) işaretlemelerini veya C++ kuralları ile etkileşimde bulunmalarını gibi yeni derleme işlemlerini ve girişlerini dahil etme: header_modules veya thin_lto.

İdeal olarak CcToolchainConfigInfo, her biri belirli Bazel işlemleri için geçerli işaretlerin listesini tanımlayan bir veya daha fazla işaret grubundan oluşan bir özellik listesi içerir.

Bir özellik, Starlark'ın tamamen ayrıştırılmasına olanak tanıyan adla belirtilmiştir kural yapılandırması oluşturun. Diğer bir deyişle, Bazel sürümü, bu yapılandırmalar yeni özelliklerin kullanılmasını gerektirmediği sürece CcToolchainConfigInfo yapılandırmalarının davranışını etkilemez.

Bir özellik aşağıdaki yöntemlerden biriyle etkinleştirilir:

• Özelliğin enabled alanı true olarak ayarlanmıştır.
• Bazel veya kural sahibi tarafından açıkça etkinleştirilmelidir.
• Kullanıcı, bu özelliği --feature Bazel seçeneği veya features kuralıyla etkinleştirir. özelliğini gönderin.

Özelliklerin birbirine bağımlılıkları olabilir. Komut satırı bayraklarına bağlı olarak BUILD dosyası kullanabilirsiniz. ayarları ve diğer değişkenleri içerir.

Özellik ilişkileri

Bağımlılıklar genellikle doğrudan Bazel ile yönetilir. Bazel, yalnızca gereksinimleri uygular ve derlemede tanımlanan özelliklerin doğasına özgü anlaşmazlıkları yönetir. Araç zinciri spesifikasyonu, doğrudan özellik desteğini ve genişletmesini yöneten Starlark kuralında kullanılmak üzere daha ayrıntılı kısıtlamalara olanak tanır. Desteklenen biçimler şunlardır:

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'],
  ),
]

İşlemler

Eylemler, belirtilen şartlarda koşulları değiştirme esnekliği sağlar. Bu eylem, eylemin nasıl gerçekleştirileceği kabul edilmeden yürütülür. action_config, bir işlemin çağırdığı araç ikilisini belirtir. feature ise işlem çağrıldığında söz konusu aracın nasıl davranacağını belirleyen yapılandırmayı (işaretler) belirtir.

Özellikler, hangi Bazel işlemlerini belirtmek için işlemlere referans verir Eylemler Bazel eylem grafiğini değiştirebildiği için onlar da etkilenir. İlgili içeriği oluşturmak için kullanılan CcToolchainConfigInfo sağlayıcıda bayraklar ve araçlar olan işlemler var bunlarla ilişkili (örneğin, c++-compile). Her işleme işaret atanır bir özellikle ilişkilendirebilirsiniz.

Her işlem adı, Bazel tarafından gerçekleştirilen tek bir işlem türünü (ör. derleme veya bağlama) temsil eder. Bununla birlikte, Çevik projeler ile arasında bir birden çok işlemleri ve Bazel işlem türleri (Bazel işlem türü bir Java sınıfını belirtir) (CppCompileAction gibi). Özellikle, "derleyici işlemleri" ve "derleyici işlemleri" aşağıdaki tabloda görebilirsiniz: CppCompileAction, bağlantı işlemleri ise CppLinkAction.

Derleyici işlemleri

Derleyici işlemleri

Bağlantı işlemleri

Artırılmış gerçeklik (AR) işlemleri

AR işlemleri, nesne dosyalarını ar aracılığıyla arşiv kitaplıklarında (.a dosyaları) bir araya getirir ve bazı anlamları isme kodlar.

LTO işlemleri

action_config'i kullanma

action_config, bir Bazel'i tanımlayan bir Starlark yapısıdır eylem sırasında çağırılacak aracı (ikili) belirterek eylemin işaret eder. Bu flag'ler, işlemin birkaç adım var.

action_config() kurucusu aşağıdaki parametrelere sahiptir:

action_config, başka özellikler ve action_config tarafından belirlenen özellik ilişkilerine değineceğiz. Bu davranış bir özelliğinkine benzer.

Son iki özellik, özelliklerdeki ilgili özelliklere göre gereksizdir ve bazı Bazel işlemleri belirli işaretler veya ortam değişkenleri gerektirdiği ve amaç gereksiz action_config+feature çiftlerini önlemek olduğu için dahil edilmiştir. Genellikle tek bir özelliği birden fazla action_config ile paylaşmak tercih edilir.

Aynı action_name ile birden fazla action_config tanımlayamazsınız aynı araç zincirinin içinde olup olmadığını sorun. Bu, araç yollarında belirsizliği önler ve action_config'ün amacını (bir işlemin özelliklerinin araç zincirindeki tek bir yerde açıkça açıklanması) destekler.

Araç oluşturucu kullanma

Bir action_config, tools parametresi aracılığıyla bir araç grubu belirtebilir. tool() oluşturucusu, aşağıdaki parametreleri alır:

Belirli bir action_config için yalnızca tek bir tool geçerlidir Bazel eylemi için gereken araç yolu ve yürütme gereksinimlerini. Bir action_config öğesindeki tools özelliğinde iterasyon yapılarak özellik yapılandırmasıyla eşleşen bir with_feature kümesi içeren bir araç bulunana kadar araç seçilir (daha fazla bilgi için bu sayfanın başlarındaki Özellik ilişkileri bölümüne bakın). Araç listelerinizi boş bir özellik yapılandırmasına karşılık gelen varsayılan bir araçla bitirmeniz gerekir.

Örnek kullanım

Özellikler ve işlemler, Bazel işlemlerini uygulamak için birlikte kullanılabilir farklı anlamlara sahip olabiliyor. Örneğin, şurada hata ayıklama simgesi oluşturma: macOS, derleme işleminde simge oluşturmayı ve ardından bağlantı işlemi sırasında özel bir araç kullanarak sıkıştırılmış dsym arşivini oluşturabilir ve ardından bu arşivin sıkıştırılmış sürümünü açarak uygulama paketini ve .plist'ı oluşturun. dosyaları Xcode tarafından kullanılabilir.

Bazel ile bu işlem aşağıdaki gibi uygulanabilir: unbundle-debuginfo bir Bazel işlemidir:

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"],
   ),
]

Aynı özellik, fission kullanan Linux için veya .pdb dosyaları oluşturan Windows için tamamen farklı şekilde uygulanabilir. Örneğin, fission tabanlı hata ayıklama sembolü oluşturma uygulaması aşağıdaki gibi görünebilir: şöyle olur:

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"],
                    ),
                ],
            ),
      ],
    ),
]

İşaret grupları

CcToolchainConfigInfo, işaretleri belirli bir amaca hizmet eden gruplar halinde toplamanıza olanak tanır. İşaretçi değeri içinde önceden tanımlanmış değişkenler kullanarak bir işaretçi belirtebilirsiniz. Derleyici, işaretçiyi derleme komutuna eklerken bu değişkenleri genişletir. Örneğin:

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

Bu durumda, işaretin içeriği işlemin çıkış dosyası yoluyla değiştirilir.

İşaret grupları, listede göründükleri sırayla (yukarıdan aşağıya, soldan sağa) derleme komutuna genişletilir.

Derleme komutuna eklendiğinde farklı değerlerle tekrarlanması gereken işaretler için işaret grubu, list türündeki değişkenleri yineleyebilir. Örneğin, list türündeki include_path değişkeni:

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

include_paths listesindeki her yol öğesi için -I<path> olarak genişler. Bir işaret grubu beyanının gövdesinde bulunan tüm işaretler (veya flag_group'ler) bir birim olarak genişletilir. Örneğin:

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

include_paths listesindeki her yol öğesi için -I <path> olarak genişler.

Bir değişken birden çok kez tekrarlanabilir. Örneğin:

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

şu şekilde genişler:

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

Değişkenler, nokta gösterimi kullanılarak erişilebilen yapılara karşılık gelebilir. Örneğin:

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

Yapılar iç içe yerleştirilebilir ve sıralar da içerebilir. Ad çakışmalarını önlemek için ve açık olmak için alanlarda tam yolu belirtmeniz gerekir. Örneğin:

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}"],
        ),
    ],
)

Koşullu genişletme

İşaret grupları, expand_if_available, expand_if_not_available, expand_if_true, expand_if_false veya expand_if_equal özelliklerini kullanarak belirli bir değişkenin veya alanının varlığına dayalı koşullu genişletmeyi destekler. Örneğin:

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"],
                ),
            ],
        ),
    ],
)

CcToolchainConfigInfo referansı

Bu bölümde, derleme değişkenleri, özellikler ve C++ kurallarını başarıyla yapılandırmak için gereken diğer bilgilere referans verilmektedir.

CcToolchainConfigInfo derleme değişkenleri

Aşağıda, CcToolchainConfigInfo derleme değişkenine referans verilmiştir.

İyi bilinen özellikler

Aşağıda, özelliklerin ve etkinleştirme koşullarının referansı verilmiştir.

Eski özellikler için yamalar mantığı

Bazel, geriye dönük uyumluluk için araç zincirinin özelliklerinde aşağıdaki değişiklikleri uygular:

• legacy_compile_flags özelliğini araç zincirinin en üstüne taşır
• default_compile_flags özelliğini araç zincirinin en üstüne taşır
• dependency_file (varsa) özelliğini araç zincirinin en üstüne ekler
• pic (varsa) özelliğini araç zincirinin başına ekler
• Araç zincirinin en üstüne per_object_debug_info (mevcut değilse) özelliği ekler
• preprocessor_defines (varsa) özelliğini araç zincirinin en üstüne ekler
• Araç zincirinin en üstüne includes (mevcut değilse) özelliği ekler
• Araç zincirinin en üstüne include_paths (mevcut değilse) özelliği ekler
• Araç zincirinin en üstüne fdo_instrument (mevcut değilse) özelliği ekler
• fdo_optimize (varsa) özelliğini araç zincirinin en üstüne ekler
• cs_fdo_instrument (varsa) özelliğini araç zincirinin en üstüne ekler
• cs_fdo_optimize (varsa) özelliğini araç zincirinin en üstüne ekler
• fdo_prefetch_hints (varsa) özelliğini araç zincirinin en üstüne ekler
• autofdo (varsa) özelliğini araç zincirinin en üstüne ekler
• Araç zincirinin en üstüne build_interface_libraries (mevcut değilse) özelliği ekler
• Araç zincirinin en üstüne dynamic_library_linker_tool (mevcut değilse) özelliği ekler
• shared_flag (varsa) özelliğini araç zincirinin en üstüne ekler
• linkstamps (varsa) özelliğini araç zincirinin en üstüne ekler
• output_execpath_flags (varsa) özelliğini araç zincirinin en üstüne ekler
• runtime_library_search_directories (varsa) özelliğini araç zincirinin en üstüne ekler
• Araç zincirinin en üstüne library_search_directories (mevcut değilse) özelliği ekler
• Araç zincirinin en üstüne archiver_flags (mevcut değilse) özelliği ekler
• Araç zincirinin en üstüne libraries_to_link (mevcut değilse) özelliği ekler
• force_pic_flags (varsa) özelliğini araç zincirinin en üstüne ekler
• user_link_flags (varsa) özelliğini araç zincirinin en üstüne ekler
• Araç zincirinin en üstüne legacy_link_flags (mevcut değilse) özelliği ekler
• static_libgcc (varsa) özelliğini araç zincirinin başına ekler
• Araç zincirinin en üstüne fission_support (mevcut değilse) özelliği ekler
• strip_debug_symbols (varsa) özelliğini araç zincirinin en üstüne ekler
• coverage (varsa) özelliğini araç zincirinin en üstüne ekler
• llvm_coverage_map_format (varsa) özelliğini araç zincirinin en üstüne ekler
• gcc_coverage_map_format (varsa) özelliğini araç zincirinin en üstüne ekler
• Araç zincirinin en altına fully_static_link (mevcut değilse) özelliği ekler
• user_compile_flags (varsa) özelliğini araç zincirinin alt kısmına ekler
• sysroot (varsa) özelliğini araç zincirinin alt kısmına ekler
• Araç zincirinin en altına unfiltered_compile_flags (mevcut değilse) özelliği ekler
• linker_param_file (varsa) özelliğini araç zincirinin alt kısmına ekler
• Araç zincirinin en altına compiler_input_flags (mevcut değilse) özelliği ekler
• Araç zincirinin en altına compiler_output_flags (mevcut değilse) özelliği ekler

Bu, uzun bir özellik listesidir. Starlark'ta Crosstool tamamlandıktan sonra bunları kaldırmayı planlıyoruz. Merak eden okuyucular CppActionConfigs'deki uygulamayı inceleyebilir. Üretim araç zincirlerinde ise araç zincirinin daha bağımsız olması için no_legacy_features ekleyebilirsiniz.