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

Genel Bakış

Derleyiciyi doğru seçeneklerle çağırmak için Bazel'in bazı bilgilere ihtiyacı var. dizinleri ve önemli işaretleri dahil edin. Diğer bir deyişle, Bazel'in çalışma şeklini anlamak için derleyicinin basitleştirilmiş bir modeline ihtiyacı vardır.

Bazel'ın şunları bilmesi gerekiyor:

• Derleyicinin thinLTO, modül, dinamik bağlantı veya PIC'yi destekleyip desteklemediği (konumdan bağımsız kod) girin.
• gcc, ld, ar, objcopy gibi gerekli araçların yolları.
• Yerleşik sistemde dizinler bulunur. 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 özel olarak gerekli olan değişkenler oluşturun.

Derleyici birden fazla mimariyi destekliyorsa Bazel'in oluşturabilirsiniz.

CcToolchainConfigInfo, Bazel'in C++ kurallarının davranışını yapılandırma için gerekli düzeyde ayrıntı sunan bir sağlayıcıdır. Bazel, varsayılan olarak CcToolchainConfigInfo'ü derlemeniz için otomatik olarak yapılandırır ancak manuel olarak yapılandırabilirsiniz. Bunun için bir Starlark kuralına ihtiyacınız var CcToolchainConfigInfo sağlayan ve öğesinin toolchain_config özelliği Kuralınıza cc_toolchain ekleyin. cc_common.create_cc_toolchain_config_info() numaralı telefonu arayarak CcToolchainConfigInfo öğesini oluşturabilirsiniz. İş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 üzerinden C++ hedefine iletir.

Örneğin, cc_binary veya cc_library gibi bir kural tarafından örneklendirilen bir derleme veya bağlantı işlemi için aşağıdaki bilgiler gerekir:

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

Korumalı alanda gerekli olan yapı taşları dışındaki tüm bilgiler, 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çlar zinciri seçimi

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

1. Kullanıcı, BUILD dosyasında bir cc_toolchain_suite hedefi belirtir ve --crosstool_top seçeneğini kullanarak Bazeli 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 şöyle olur:

   • --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ğine yalnızca --cpu ile ulaşabilirsiniz.

   • Herhangi bir işaret belirtilmezse Bazel, ana sistemi inceler ve bulgularına göre bir --cpu değeri seçer. Bkz. inceleme mekanizması kodu ile değiştirin.

Bir araç zinciri seçildikten sonra, Starlark kuralındaki ilgili feature ve action_config nesneleri derlemenin yapılandırmasını (yani daha sonra açıklanan öğeleri) yönetir. Bu mesajlar, Bazel ikili dosyasında değişiklik yapmadan Bazel'de tam teşekküllü C++ özelliklerinin uygulanmasına olanak tanır. C++ kuralları, ayrıntılı olarak belgelenen birden çok benzersiz işlemi destekler Bazel kaynak koduna ekleyin.

Ö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. Bir özellik, BUILD dosyalarının treat_warnings_as_errors gibi işaret yapılandırmalarını seçmesine veya C++ kurallarıyla etkileşime girmesine ve derlemeye yeni derleme işlemleri ve girişler (ör. header_modules veya thin_lto) eklemesine izin vermek kadar basit olabilir.

İdeal olarak CcToolchainConfigInfo, her bir özelliğin her birinin özellik, her biri bir işaret listesi tanımlayan bir veya daha fazla işaret grubundan oluşur seçenekleri vardır.

Özellikler adlarıyla belirtilir. Bu sayede Starlark kural yapılandırması, Bazel sürümlerinden tamamen ayrılabilir. Başka bir deyişle, bir Bazel sürümü olduğu sürece CcToolchainConfigInfo yapılandırmalarının davranışını yapılandırmaları yeni özelliklerin kullanılmasını gerektirmez.

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. Bu da özelliklerin doğası gereği çatışmaları yönetir ve oluşturmamıza yardımcı olur. Araç zinciri spesifikasyonu, daha ayrıntılı doğrudan Starlark kuralında yer alan ve ilgili özelliği düzenleyen destek ve genişleme. 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

İşlemler, bir işlemin nasıl çalışacağını varsaymadan işlemin yürütüleceği koşulları değiştirme esnekliği sağlar. action_config, bir işlemin çağırdığı araç ikili programını belirtirken bir diğer yandan feature, bu aracın işlem çağrıldığında davranır.

İşlemler Bazel işlem grafiğini değiştirebileceğinden özellikler, hangi Bazel işlemlerini etkilediklerini belirtmek için işlemlere referans verir. İ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). İşaretler, bir özellikle ilişkilendirilerek her işleme atanır.

Her işlem adı, Bazel tarafından gerçekleştirilen tek bir işlem türünü temsil eder. Örneğin: derleme veya bağlama. Bununla birlikte, işlemler ile Bazel işlem türleri arasında bire çok ilişki vardır. Bazel işlem türü, bir işlemi uygulayan Java sınıfını (CppCompileAction gibi) ifade eder. Özellikle, aşağıdaki tablodaki "toplayıcı işlemleri" ve "derleyici işlemleri" CppCompileAction iken bağlantı işlemleri CppLinkAction'dur.

Derleyici işlemleri

Derleyici işlemleri

Bağlantı işlemleri

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

AR işlemleri, ar aracılığıyla nesne dosyalarını arşiv kitaplıklarında (.a dosya) birleştirir ve ada birtakım anlamlar kodlayın.

LTO işlemleri

action_config parametresini kullanma

action_config, bir Bazel işlemini tanımlayan bir Starlark yapısıdır. Bu yapı, işlem sırasında çağrılacak aracı (ikili) ve özellikler tarafından tanımlanan işaret gruplarını belirtir. Bu flag'ler, işlemin çok önemlidir.

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

Bir action_config, daha önce açıklanan özellik ilişkilerine göre diğer özellikleri ve action_config'leri gerektirebilir ve ima edebilir. Bu davranış, bir özelliğe 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ı araç zincirinde aynı action_name ile birden fazla action_config tanımlayamazsınız. Bu, araç yollarında belirsizliği önler ve action_config'ün amacını (bir işlemin özelliklerinin araç zincirindeki tek bir yerde net bir şekilde açıklanması) destekler.

Araç oluşturucuyu kullanma

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

Belirli bir action_config için yalnızca tek bir tool, araç yolunu ve yürütme koşullarını Bazel işlemine uygular. Bir araç seçildi action_config üzerinde tools özelliği aracılığıyla bir araç özellik yapılandırmasıyla eşleşen bir with_feature grubu bulundu (bu sayfanın önceki Özellik ilişkileri bölümüne bakın bakın). Araç listelerinizi varsayılan bir aracını da kullanabilirsiniz.

Örnek kullanım

Bazel işlemlerini farklı platformlar arası semantiklerle uygulamak için özellikler ve işlemler birlikte kullanılabilir. Örneğin, macOS'te hata ayıklama sembolü oluşturma işlemi için derleme işleminde sembollerin oluşturulması, ardından bağlantı işlemi sırasında sıkıştırılmış dsym arşivi oluşturmak için özel bir aracın çağrılması ve ardından uygulama paketini ve Xcode tarafından kullanılabilen .plist dosyalarını oluşturmak için bu arşivin sıkıştırmasının kaldırılması gerekir.

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

Bu özellik, farklı bir uygulama paketi kullanan Linux için fission veya .pdb dosya oluşturan Windows için. Ö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. Önceden tanımlanmış değişkenleri kullanarak içindeki "bayrak" değerine; derleyici, işareti derleme komutudur. Örneğin:

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

Bu durumda, işaretin içeriği çıkış dosyası yoluyla değiştirilir eyleme dönüşebilir.

İş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> değerine 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.

Değişkenler 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 ve açıkça belirtmek için alanların tam yolunu 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, özellikleri ve C++ kurallarını başarıyla yapılandırmak için gereken bilgileri içerir.

CcToolchainConfigInfo derleme değişkenleri

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

Bilinen özellikler

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

Eski özelliklerde yama uygulama 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
• Araç zincirinin en üstüne pic (mevcut değilse) özelliği ekler
• per_object_debug_info (varsa) özelliğini araç zincirinin en üstüne ekler
• Araç zincirinin en üstüne preprocessor_defines (mevcut değilse) özelliği ekler
• Araç zincirinin en üstüne includes (mevcut değilse) özelliği ekler
• include_paths (varsa) özelliğini araç zincirinin en üstüne 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
• Araç zincirinin en üstüne cs_fdo_optimize (mevcut değilse) özelliği ekler
• Araç zincirinin en üstüne fdo_prefetch_hints (mevcut değilse) özelliği ekler
• Araç zincirinin en üstüne autofdo (mevcut değilse) özelliği 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
• Araç zincirinin en üstüne linkstamps (mevcut değilse) özelliği 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
• archiver_flags (varsa) özelliğini araç zincirinin en üstüne ekler
• libraries_to_link (varsa) özelliğini araç zincirinin en üstüne ekler
• Araç zincirinin en üstüne force_pic_flags (mevcut değilse) özelliği ekler
• user_link_flags (varsa) özelliğini araç zincirinin en üstüne ekler
• legacy_link_flags (varsa) özelliğini araç zincirinin en üstüne ekler
• static_libgcc (varsa) özelliğini araç zincirinin en üstüne ekler
• fission_support (varsa) özelliğini araç zincirinin en üstüne ekler
• strip_debug_symbols (varsa) özelliğini araç zincirinin en üstüne ekler
• coverage (varsa) özelliğini araç zincirinin en üstüne ekler
• Araç zincirinin en üstüne llvm_coverage_map_format (mevcut değilse) özelliği ekler
• gcc_coverage_map_format (varsa) özelliğini araç zincirinin en üstüne ekler
• fully_static_link (varsa) özelliğini araç zincirinin alt kısmına ekler
• user_compile_flags (varsa) özelliğini araç zincirinin alt kısmına ekler
• Araç zincirinin en altına sysroot (mevcut değilse) özelliği ekler
• Araç zincirinin en altına unfiltered_compile_flags (mevcut değilse) özelliği ekler
• Araç zincirinin en altına linker_param_file (mevcut değilse) özelliği ekler
• Araç zincirinin en altına compiler_input_flags (mevcut değilse) özelliği ekler
• compiler_output_flags (varsa) özelliğini araç zincirinin alt kısmına ekler

Bu, uzun bir özellik listesidir. Plan, onlardan bir kez kurtulmak Starlark'taki Crosstool: tamamlandı. Merak eden okuyucular CppActionConfigs'deki uygulamayı inceleyebilir. Üretim araç zincirlerinde ise araç zincirinin daha bağımsız olması için no_legacy_features ekleyebilirsiniz.