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 thinLTO, modül, dinamik bağlantı veya PIC (konumdan bağımsız kod) destekleyip desteklemediği.
• gcc, ld, ar, objcopy gibi gerekli araçlara giden yollar.
• Yerleşik sistemde dizinler bulunur. 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ğlantı oluşturma, 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ırmak için gerekli ayrıntı düzeyini sağlayan 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 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'de bulabilirsiniz.

C++ hedefi analiz aşamasına geçtiğ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ısını edinir. cc_toolchain hedefi, bu bilgiyi 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üleceği korumalı alanda gereken yapılar

Korumalı alanda gerekli olan yapılar dışında yukarıdaki bilgilerin tümü, cc_toolchain öğesinin işaret ettiği Starlark hedefinde belirtilmiştir.

Korumalı alana gönderilecek yapılar cc_toolchain hedefinde tanımlanır. Örneğin, cc_toolchain.linker_files özelliğiyle korumalı alana gönderilecek bağlayıcı ikili program ve araç zinciri kitaplıklarını belirtebilirsiniz.

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'ı 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ğinden ilgili girişi seçer. Bazel, karşılık gelen bir giriş bulamazsa hata verir.

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

   • Hiç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ında karşılık gelen feature ve action_config nesneleri derlemenin yapılandırmasını (yani daha sonra açıklanan öğeler) 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 izin vermek veya C++ kurallarıyla etkileşim kurmak ve derlemeye header_modules ya da thin_lto gibi yeni derleme işlemleri ve girişleri eklemek gibi basit bir şey olabilir.

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

Özellikler adlarıyla belirtilir. Bu sayede Starlark kural yapılandırması, Bazel sürümlerinden tamamen ayrılabilir. Başka bir deyişle, Bazel sürümü yeni özelliklerin kullanımı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ış.
• Bazel veya kural sahibi bu özelliği açıkça etkinleştirir.
• Kullanıcı, bu özelliği --feature Bazel seçeneği veya features kural özelliğiyle etkinleştirir.

Özellikler birbirine bağlı 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 zorunlu kılar ve derlemede tanımlanan özelliklerin doğasına özgü çakışmaları 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, nasıl çalışacağını varsaymadan eylemin 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ısı, ilişkilendirilmiş işaret ve araçlar içeren işlemler (ör. c++-compile) içeriyor. İş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, eylemler ile Bazel işlem türleri arasında bire bir ilişki vardır. Bazel işlem türü, bir işlem (CppCompileAction gibi) uygulayan Java sınıfını belirtir. Özellikle, aşağıdaki tabloda yer alan "derleyici işlemleri" ve "derleyici işlemleri" CppCompileAction, bağlantı işlemleri ise CppLinkAction'dır.

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ı) birleştirir ve bazı anlamları ada kodlar.

LTO işlemleri

action_config'i kullanma

action_config, işlem sırasında çağrılacak aracı (ikili) ve özelliklerle tanımlanan işaret gruplarını belirterek Bazel işlemini tanımlayan bir Starlark yapısıdır. Bu işaretler, işlemin yürütülmesine kısıtlamalar uygular.

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

action_config, daha önce açıklanan özellik ilişkilerinde belirtildiği şekilde diğer özellikleri ve action_config'leri gerektirebilir ve ifade edebilir. Bu davranış, bir özelliğin davranışına 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ş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 bir tool kendi araç yolu ve yürütme gerekliliklerini Bazel işlemine uygular. Özellik yapılandırmasıyla eşleşen with_feature grubuna sahip bir araç bulunana kadar action_config üzerinde tools özelliği aracılığıyla bir araç seçilir (daha fazla bilgi için bu sayfanın önceki kısımları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 sonlandırmanız gerekir.

Ö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'de bu süreç, 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"],
   ),
]

Bu özellik, fission kullanan Linux veya .pdb dosyaları oluşturan Windows için tamamen farklı bir şekilde uygulanabilir. Örneğin, fission tabanlı hata ayıklama sembolü oluşturma uygulaması 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 değeri içindeki önceden tanımlanmış değişkenleri kullanarak bir işaret belirtebilirsiniz. İşaretçi, işareti derleme komutuna eklerken derleyici tarafından genişletilir. Örneğin:

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

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

İşaretleme grupları derleme komutuna, yukarıdan aşağıya, soldan sağa doğru yukarıda göründükleri sırayla 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> değerine 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ş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 sıralar da içerebilir. Ad çakışmalarını önlemek 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 C++ kurallarını başarıyla yapılandırmak için gereken derleme değişkenleri, özellikler ve diğer bilgilere ilişkin bir referans sunulmaktadır.

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 ö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
• Araç zincirinin en üstüne dependency_file (mevcut değilse) özelliği ekler
• pic (varsa) özelliğini araç zincirinin başına ekler
• per_object_debug_info (varsa) özelliğini araç zincirinin en üstüne ekler
• preprocessor_defines (varsa) özelliğini araç zincirinin en üstüne ekler
• includes (varsa) özelliğini araç zincirinin en üstüne ekler
• Araç zincirinin en üstüne include_paths (mevcut değilse) özelliği ekler
• fdo_instrument (varsa) özelliğini araç zincirinin başına ekler
• Araç zincirinin en üstüne fdo_optimize (mevcut değilse) özelliği ekler
• Araç zincirinin en üstüne cs_fdo_instrument (mevcut değilse) özelliği ekler
• cs_fdo_optimize (varsa) özelliğini araç zincirinin en üstüne ekler
• fdo_prefetch_hints (varsa) özelliğini araç zincirinin başına 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
• Araç zincirinin en üstüne shared_flag (mevcut değilse) özelliği ekler
• linkstamps (varsa) özelliğini araç zincirinin en üstüne ekler
• Araç zincirinin en üstüne output_execpath_flags (mevcut değilse) özelliği ekler
• Araç zincirinin en üstüne runtime_library_search_directories (mevcut değilse) özelliği 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
• 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
• Araç zincirinin en üstüne static_libgcc (mevcut değilse) özelliği ekler
• Araç zincirinin en üstüne fission_support (mevcut değilse) özelliği ekler
• Araç zincirinin en üstüne strip_debug_symbols (mevcut değilse) özelliği ekler
• Araç zincirinin en üstüne coverage (mevcut değilse) özelliği 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
• Araç zincirinin en altına fully_static_link (mevcut değilse) özelliği ekler
• Araç zincirinin en altına user_compile_flags (mevcut değilse) özelliği 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
• compiler_input_flags (varsa) özelliğini araç zincirinin alt kısmına ekler
• Araç zincirinin en altına compiler_output_flags (mevcut değilse) özelliği ekler

Bu, uzun bir özellik listesidir. Planlanan, Starlark'ta Crosstool tamamlandığında bunlardan kurtulmak. Meraklı okuyucular için uygulamayı CppActionConfigs'de görebilir, üretim araç zincirleri için ise araç zincirini daha bağımsız hale getirmek amacıyla no_legacy_features öğesini eklemeyi düşünebilirsiniz.