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 gibi gerekli araçların yolları.
• Yerleşik sistem dizinleri içerir. Bazel, kaynak dosyaya dahil edilen tüm üst bilgilerin BUILD dosyasında doğru şekilde tanımlandığını doğrulamak için bu bilgilere ihtiyaç duyar.
• 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 bunları ayrı ayrı yapılandırması gerekir.

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 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. cc_common.create_cc_toolchain_config_info() numaralı telefonu arayarak CcToolchainConfigInfo öğesini oluşturabilirsiniz. İşlemde ihtiyaç duyacağınız tüm yapıların Starlark yapıcıları @rules_cc//cc:cc_toolchain_config_lib.bzl adresinde bulunabilir.

Bir C++ hedefi analiz aşamasına girdiğinde Bazel, BUILD dosyasına göre uygun cc_toolchain hedefini seçer ve cc_toolchain.toolchain_config özelliğinde belirtilen hedeften CcToolchainConfigInfo sağlayıcıyı alır. cc_toolchain hedefi, bu bilgileri bir CcToolchainProvider aracılığıyla 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 aracılığıyla 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 korumalı alana gönderilecek bağlayıcı ikilisini ve araç zinciri kitaplıklarını belirtebilirsiniz.

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 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, karşılık gelen bir giriş bulamazsa hata verir.

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

   • Herhangi bir işaret belirtilmezse Bazel, ana sistemi inceler ve bulgularına göre bir --cpu değeri seçer. İnceleme mekanizması koduna bakın.

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ı, Bazel kaynak kodunda ayrıntılı olarak açıklanan birden fazla benzersiz işlemi destekler.

Özellikler

Özellik, komut satırı işaretleri, işlemler, yürütme ortamında kısıtlamalar veya bağımlılık değişiklikleri gerektiren bir öğedir. 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 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.

Özellikler adlarıyla belirtilir. Bu sayede Starlark kural yapılandırması, Bazel sürümlerinden tamamen ayrılabilir. 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ı, --feature Bazel seçeneği veya features kural özelliği aracılığıyla bu özelliği etkinleştirir.

Özellikler birbirine bağımlı olabilir, komut satırı işaretlerine, BUILD dosya ayarlarına ve diğer değişkenlere bağlı olabilir.

Ö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

İş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ç 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.

İşlemler Bazel işlem grafiğini değiştirebileceğinden özellikler, hangi Bazel işlemlerini etkilediklerini belirtmek için işlemlere referans verir. CcToolchainConfigInfo sağlayıcı, c++-compile gibi işaretleri ve araçları olan işlemleri içerir. İş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ü (ör. derleme veya bağlama) temsil eder. 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'dır.

Derleyici işlemleri

Derleyici işlemleri

Bağlantı işlemleri

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ı ada kodlar.

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 işaretler, işlemin yürütülmesine kısıtlamalar uygular.

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 açıkça 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. Özellik yapılandırmasıyla eşleşen bir with_feature kümesi içeren bir araç bulunana kadar bir action_config üzerindeki tools özelliğinde iterasyon yapılarak bir 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

Bazel işlemlerini farklı platformlar arası anlamlarla 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'de bu işlem, unbundle-debuginfo bir Bazel işlemi olacak şekilde aşağıdaki gibi uygulanabilir:

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 veya .pdb dosyaları oluşturan Windows için tamamen farklı şekilde uygulanabilir. Örneğin, fission tabanlı hata ayıklama simgesi oluşturma için uygulama aşağıdaki gibi görünebilir:

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.

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şletilir:

-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 diziler de 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, ö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şkenleri referansı verilmiştir.

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 başına ekler
• pic (varsa) özelliğini araç zincirinin başına ekler
• per_object_debug_info (varsa) özelliğini araç zincirinin başına ekler
• preprocessor_defines (varsa) özelliğini araç zincirinin başına ekler
• includes (varsa) özelliğini araç zincirinin başına ekler
• include_paths (varsa) özelliğini araç zincirinin başına ekler
• fdo_instrument (varsa) özelliğini araç zincirinin başına ekler
• fdo_optimize (varsa) özelliğini araç zincirinin başına ekler
• cs_fdo_instrument (varsa) özelliğini araç zincirinin başına ekler
• cs_fdo_optimize (varsa) özelliğini araç zincirinin başına ekler
• fdo_prefetch_hints (varsa) özelliğini araç zincirinin başına ekler
• autofdo (varsa) özelliğini araç zincirinin başına ekler
• build_interface_libraries (varsa) özelliğini araç zincirinin başına ekler
• dynamic_library_linker_tool (varsa) özelliğini araç zincirinin başına ekler
• shared_flag (varsa) özelliğini araç zincirinin başına ekler
• linkstamps (varsa) özelliğini araç zincirinin başına ekler
• output_execpath_flags (varsa) özelliğini araç zincirinin başına ekler
• runtime_library_search_directories (varsa) özelliğini araç zincirinin başına ekler
• library_search_directories (varsa) özelliğini araç zincirinin başına ekler
• archiver_flags (varsa) özelliğini araç zincirinin başına ekler
• libraries_to_link (varsa) özelliğini araç zincirinin başına ekler
• force_pic_flags (varsa) özelliğini araç zincirinin başına ekler
• user_link_flags (varsa) özelliğini araç zincirinin başına ekler
• legacy_link_flags (varsa) özelliğini araç zincirinin başına ekler
• static_libgcc (varsa) özelliğini araç zincirinin başına ekler
• fission_support (varsa) özelliğini araç zincirinin başına ekler
• strip_debug_symbols (varsa) özelliğini araç zincirinin başına ekler
• coverage (varsa) özelliğini araç zincirinin başına ekler
• llvm_coverage_map_format (varsa) özelliğini araç zincirinin başına ekler
• gcc_coverage_map_format (varsa) özelliğini araç zincirinin başına 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
• sysroot (varsa) özelliğini araç zincirinin alt kısmına ekler
• unfiltered_compile_flags (varsa) özelliğini araç zincirinin alt kısmına ekler
• linker_param_file (varsa) özelliğini araç zincirinin alt kısmına ekler
• compiler_input_flags (varsa) özelliğini araç zincirinin alt kısmına ekler
• compiler_output_flags (varsa) özelliğini araç zincirinin alt kısmına 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.