إعداد سلسلة مفاتيح C++

نظرة عامة

لاستدعاء برنامج التجميع باستخدام الخيارات المناسبة، يحتاج Bazel إلى بعض المعرفة حول العناصر الداخلية للعارض، مثل تضمين الأدلة والعلامات المهمة. بعبارة أخرى، يحتاج Bazel إلى نموذج مبسّط للعارض ليفهم أداء عمله.

يحتاج Bazel إلى معرفة ما يلي:

  • ما إذا كان برنامج التجميع متوافقًا مع hinLTO أو الوحدات أو الربط الديناميكي أو PIC (الرمز المستقل لموضع الإعلان)
  • المسارات المؤدية إلى الأدوات المطلوبة، مثل gcc وld وar وobjcopy وما إلى ذلك
  • يتضمن النظام المُدمج أدلة. يحتاج Bazel إلى هذه الصفحات للتحقّق من أنّ جميع العناوين التي تم تضمينها في الملف المصدر قد تم الإعلان عنها بشكل صحيح في ملف BUILD.
  • سجلّ النظام التلقائي.
  • العلامات التي يمكن استخدامها للتجميع والربط والأرشفة.
  • العلامات التي يمكن استخدامها لأوضاع التجميع المتوافقة (opt وdbg وFastbuild)
  • إنشاء المتغيرات التي تطلبها برامج التجميع على وجه التحديد.

إذا كان مجمِّع الموسيقى يدعم بُنى متعدّدة، سيحتاج Bazel إلى ضبطها بشكلٍ منفصل.

CcToolchainConfigInfo هو موفّر يوفر المستوى الدقيق من الدقة لضبط سلوك قواعد Bazel's C++. وفقًا للإعدادات التلقائية، يعمل تطبيق Bazel على ضبط إصدار CcToolchainConfigInfo تلقائيًا، ولكن يتوفّر لك خيار ضبطه يدويًا. لإجراء ذلك، عليك استخدام قاعدة Starlark التي توفّر CcToolchainConfigInfo، ويجب توجيه السمة toolchain_config من cc_toolchain إلى القاعدة. يمكنك إنشاء CcToolchainConfigInfo من خلال الاتصال cc_common.create_cc_toolchain_config_info(). يمكنك العثور على مشغّلات Starlark لكلّ المباني التي ستحتاج إليها في هذه العملية. @rules_cc//cc:cc_toolchain_config_lib.bzl

عند دخول هدف C++ إلى مرحلة التحليل، يختار Bazel هدف cc_toolchain المناسب استنادًا إلى ملف BUILD، ويحصل على موفّر CcToolchainConfigInfo من الهدف المحدّد في سمة cc_toolchain.toolchain_config. يعمل الهدف cc_toolchain على تمرير هذه المعلومات إلى الهدف C++ من خلال CcToolchainProvider.

على سبيل المثال، يحتاج إجراء التجميع أو الرابط، الذي تم إنشاؤه بواسطة قاعدة مثل cc_binary أو cc_library، إلى المعلومات التالية:

  • برنامج التجميع أو الرابط المراد استخدامه
  • علامات سطر الأوامر في برنامج التجميع/الرابط
  • علامات الضبط التي تم تمريرها من خلال خيارات --copt/--linkopt
  • متغيرات البيئة
  • العناصر المطلوبة في وضع الحماية حيث يتم تنفيذ الإجراء

يتم تحديد جميع المعلومات الواردة أعلاه، باستثناء العناصر المطلوبة في وضع الحماية، في استهداف Starlark الذي تشير إليه السمة cc_toolchain.

يتمّ الإعلان عن العناصر التي سيتم شحنها إلى وضع الحماية في هدف cc_toolchain. على سبيل المثال، باستخدام السمة cc_toolchain.linker_files، يمكنك تحديد البرنامج الثنائي للرابط ومكتبات سلسلة الأدوات للشحن إلى وضع الحماية.

اختيار سلسلة الأدوات

يعمل منطق اختيار سلسلة الأدوات على النحو التالي:

  1. يحدّد المستخدم هدفًا cc_toolchain_suite في الملف BUILD ويوجّه Ballel إلى الهدف باستخدام الخيار --crosstool_top.

  2. يشير هدف cc_toolchain_suite إلى سلاسل أدوات متعددة. تحدّد قيم العلامات --cpu و--compiler أيًا من سلسلة الأدوات هذه التي يتم اختيارها، إما استنادًا إلى قيمة العلامة --cpu فقط، أو استنادًا إلى قيمة --cpu | --compiler مشتركة. في ما يلي خطوات عملية الاختيار:

    • إذا تم تحديد الخيار --compiler، يختار Bazel الإدخال المقابل من السمة cc_toolchain_suite.toolchains مع --cpu | --compiler. إذا لم يعثر Bazel على إدخال مقابل، سيتم عرض خطأ.

    • وإذا لم يتم تحديد الخيار --compiler، يختار Bazel الإدخال المقابل من السمة cc_toolchain_suite.toolchains مع تضمين --cpu فقط.

    • في حال عدم تحديد أي علامات، يفحص Bazel نظام المضيف ويختار القيمة --cpu استنادًا إلى النتائج. يُرجى الاطّلاع على رمز آلية الفحص.

وبعد اختيار سلسلة أدوات، تخضع العناصر feature وaction_config المقابلة في قاعدة Starlark لضبط الإصدار (أي العناصر الموضّحة لاحقًا). تسمح هذه الرسائل بتنفيذ ميزات C++ التي تم طرحها بالكامل في Bazel بدون تعديل برنامج ثنائية. تتيح قواعد C++ استخدام عدة إجراءات فريدة موثَّقة بالتفصيل في رمز مصدر Bazel.

الميزات

الميزة هي كيان يتطلب علامات سطر الأوامر أو الإجراءات أو القيود على بيئة التنفيذ أو تعديلات التبعية. يمكن أن تكون الميزة بسيطة مثل السماح لملفات BUILD باختيار عمليات ضبط العلامات، مثل treat_warnings_as_errors، أو التفاعل مع قواعد C++ وإضافة إجراءات التجميع وأساليب الإدخال الجديدة إلى التجميع، مثل header_modules أو thin_lto.

في الوضع المثالي، يتضمّن CcToolchainConfigInfo قائمة بالميزات التي تتألف منها كل ميزة من مجموعة الإبلاغ واحدة أو أكثر، حيث تحدِّد كل ميزة قائمة من العلامات التي تنطبق على إجراءات Bazel محدّدة.

يتم تحديد العنصر حسب الاسم، الذي يسمح بفصل ضبط قاعدة Starlark بالكامل عن إصدارات Bazel. وهذا يعني أنّ إصدار Bazel لا يؤثّر في أداء عمليات ضبط CcToolchainConfigInfo طالما أنّ تلك الإعدادات لا تتطلب استخدام ميزات جديدة.

يتم تفعيل الميزة بإحدى الطرق التالية:

  • تم ضبط حقل enabled للميزة على true.
  • Bazel أو مالك القاعدة تفعّلها صراحةً.
  • يمكن للمستخدم تفعيل الإضافة من خلال ميزة --feature Bazel أو سمة القاعدة features.

يمكن أن تعتمد الميزات على ارتباطات تعتمد على علامات سطر الأوامر وإعدادات ملفات BUILD وغيرها من المتغيرات.

علاقات الميزات

تتم إدارة المهام التابعة عادةً مباشرةً باستخدام Bazel الذي يطبّق المتطلبات ويدير الصراعات بشكل جوهري بسبب طبيعة الميزات المحدّدة في الإصدار. تسمح مواصفات سلسلة الأدوات بقيود أكثر دقة للاستخدام مباشرةً ضمن قاعدة Starlark التي تحكم دعم الميزات وتوسيع نطاقها. وهي كما يلي:

الشروط الوصف 
requires = [
   feature_set (features = [
       'feature-name-1',
       'feature-name-2'
   ]),
]
 على مستوى الميزة. ولا تتوفر الميزة إلا في حال تفعيل الميزات المطلوبة المحدّدة. على سبيل المثال، عندما تكون الميزة متوافقة فقط في أوضاع إنشاء معيّنة (opt أو dbg أو fastbuild)، إذا كانت"مطلوبة"تحتوي على عدة"feature_set" ، ستكون الميزة متاحة في حال تلبية أي من"feature_set" (عند تفعيل جميع الميزات المحدّدة). 
implies = ['feature']

على مستوى الميزة. تشير هذه الميزة إلى الميزات المحددة. يتيح تفعيل الميزة أيضًا ضمنيًا تفعيل جميع الميزات المضمّنة فيها (أي أنها تعمل بشكل متكرّر).

وتوفّر أيضًا إمكانية تحليل مجموعات فرعية مشتركة من الوظائف من مجموعة الميزات، مثل الأجزاء الشائعة المعقّمة. لا يمكن إيقاف الميزات الضمنية.

 
provides = ['feature']

على مستوى الميزة. تشير هذه السمة إلى أنّ هذه الميزة هي من الميزات البديلة الحصرية الحصرية. على سبيل المثال، يمكن لكل المعقّمات تحديد provides = ["sanitizer"].

يساهم ذلك في تحسين معالجة الأخطاء من خلال عرض البدائل إذا طلب المستخدم ميزتَين حصريتَين أو أكثر في آنٍ واحد.

 
with_features = [
  with_feature_set(
    features = ['feature-1'],
    not_features = ['feature-2'],
  ),
]
 على مستوى المجموعة المحدَّدة. يمكن للميزة تحديد مجموعات علامات متعددة متعددة. عند تحديد with_features، سيتم توسيع مجموعة العلامات فقط إلى أمر الإصدار إذا كان هناك with_feature_set واحدة على الأقل تم تفعيل جميع الميزات في المجموعة features المحدّدة عليها، وتم إيقاف جميع الميزات المحدّدة في مجموعة not_features. في حال عدم تحديد with_features، سيتم تطبيق مجموعة العلامات بدون شروط على كل إجراء محدّد.

الإجراءات

توفّر الإجراءات المرونة في تعديل الظروف التي يتم فيها تنفيذ الإجراء بدون افتراض كيفية تنفيذ الإجراء. يحدّد action_config البرنامج الثنائي الذي يستدعيه الإجراء، بينما يحدّد feature الإعدادات (العلامات) التي تحدّد كيفية عمل الأداة عند استدعاء الإجراء.

الميزات تشير إلى إجراءات Bazel وهي تؤثر في الإجراءات لأنّها يمكنها تعديل الرسم البياني لإجراء Bazel. يتضمّن موفّر CcToolchainConfigInfo الإجراءات التي تحتوي على علامات وأدوات مرتبطة به، مثل c++-compile. يتم تخصيص العلامات لكل إجراء من خلال ربطها بميزة.

يمثّل كل اسم إجراء نوعًا واحدًا من الإجراءات التي يؤديها تطبيق Bazel، مثل التجميع أو الربط. وهناك علاقة بين عدّة إجراءات

إجراءات التجميع

الإجراء الوصف
preprocess-assemble التجميع مع المعالجة المسبقة السعر المعتاد: .S ملف
assemble التجميع بدون معالجة مسبقة. السعر المعتاد: .s ملف

إجراءات التجميع

الإجراء الوصف
cc-flags-make-variable نشر CC_FLAGS في المجموعات الجينية.
c-compile التجميع بعد C.
c++-compile التجميع باستخدام C++.
c++-header-parsing تشغيل المحلل اللغوي' على ملف عنوان لضمان أن العنوان مستقل، لأن ذلك سيؤدي إلى أخطاء التجميع. لا تنطبق إلا على سلاسل الأدوات التي تتوافق مع الوحدات التنظيمية.
الإجراء الوصف
c++-link-dynamic-library ربط مكتبة مشتركة تحتوي على جميع العناصر التابعة لها
c++-link-nodeps-dynamic-library ربط مكتبة مشتركة تحتوي على مصدرَين (cc_library) فقط
c++-link-executable ربط مكتبة نهائية جاهزة للتشغيل

إجراءات الواقع المعزّز

تعمل إجراءات الواقع المعزّز على تجميع ملفات الكائنات في مكتبات الأرشيف (.a ملف) من خلال ar وترميز بعض الدلالة في الاسم.

الإجراء الوصف
c++-link-static-library أنشِئ مكتبة ثابتة (أرشيف).

إجراءات مبادرة LTO

الإجراء الوصف
lto-backend إجراء ThinLTO الذي يجمع الرموز البريدية في العناصر الأصلية
lto-index إجراء رقيقة على الأقل لإنشاء مؤشر عام

استخدام action_config

action_config هي بنية Starlark تصف إجراء Bazel من خلال تحديد الأداة (برنامج ثنائي) لاستدعاءه أثناء الإجراء ومجموعات العلامات، المحدّدة بالميزات. تُطبّق هذه العلامات قيودًا على تنفيذ الإجراء.

تتضمن دالة إنشاء action_config() المعلمات التالية:

السمة الوصف
action_name إجراء البازل الذي يتوافق معه هذا الإجراء. يستخدم Bazel هذه السمة لاكتشاف أداة كل إجراء ومتطلبات التنفيذ.
tools الملف التنفيذي المراد استدعاءه. ستكون الأداة المطبّقة على الإجراء هي الأداة الأولى في القائمة التي تتضمّن مجموعة ميزات تتطابق مع إعدادات الميزات. يجب تقديم القيمة التلقائية.
flag_sets قائمة بالعلامات التي تنطبق على مجموعة من الإجراءات. وينطبق الأمر نفسه على إحدى الميزات.
env_sets قائمة بقيود البيئة التي تنطبق على مجموعة من الإجراءات وينطبق الأمر نفسه على إحدى الميزات.

يمكن أن يطلب action_config ويلمّح ضمن الميزات الأخرى وaction_config وفقًا لما تفرضه علاقات الميزات الموضّحة سابقًا. هذا السلوك يشبه سلوك إحدى الميزات.

إنّ السمتَين الأخيرتَين غير متطابقتَين مع السمات المقابلة في الميزات، وهما مضمّنتان لأنّ بعض إجراءات Bazel تتطلّب علامات معيّنة أو متغيّرات بيئة معيّنة والهدف من ذلك هو عدم إقران action_config+feature. في العادة، يُفضَّل مشاركة ميزة واحدة في action_config متعددة.

لا يمكنك تحديد أكثر من action_config واحدة باستخدام action_name نفسها ضمن سلسلة الأدوات نفسها. ويؤدي ذلك إلى منع حدوث غموض في مسارات الأدوات وفرض ما ينفّذه action_config، أي أنّ سمات"الإجراءات"تظهر بوضوح في مكان واحد ضمن سلسلة الأدوات.

استخدام أداة إنشاء الأدوات

يمكن تحديد action_config لمجموعة من الأدوات من خلال معلّمتها tools. تأخذ دالة إنشاء tool() المعلمات التالية:

الحقل الوصف
tool_path المسار إلى الأداة المعنيّة (بالاستناد إلى الموقع الجغرافي الحالي)
with_features تعرض هذه السياسة قائمة بالميزات التي يجب أن تستوفي واحدة منها على الأقل حتى يتم تطبيق هذه الأداة.

بالنسبة إلى action_config، يطبّق tool واحد فقط مسار الأداة ومتطلبات التنفيذ على إجراء Bazel. يتم اختيار أداة من خلال تكرار السمة tools على action_config إلى أن يتم العثور على أداة تتضمن مجموعة with_feature مطابقة لضبط الميزة (يمكنك الاطّلاع على العلاقات المميّزة في وقت سابق في هذه الصفحة للحصول على مزيد من المعلومات). يجب إنهاء قوائم الأدوات بأداة تلقائية تتوافق مع إعدادات الميزة الفارغة.

مثال على الاستخدام

يمكن استخدام الميزات والإجراءات معًا لتنفيذ إجراءات Bazel باستخدام دلالات الألفاظ المتنوعة على المنصات. على سبيل المثال، يتطلب إنشاء رموز تصحيح الأخطاء على نظام التشغيل macOS إنشاء رموز في إجراء التجميع، ثم استدعاء أداة متخصّصة أثناء إجراء الرابط لإنشاء أرشيف dsm مضغوط، ثم فك ضغط هذا الأرشيف لإنشاء حِزمة التطبيق وملفات .plist التي يمكن استهلاكها بواسطة Xcode.

بدلاً من استخدام Bazel، يمكن تنفيذ هذه العملية على النحو التالي: يتمثّل الإجراء unbundle-debuginfo في Bazel:

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

action_configs = [
    action_config (
        config_name = ACTION_NAMES.cpp_link_executable,
        action_name = ACTION_NAMES.cpp_link_executable,
        tools = [
            tool(
                with_features = [
                    with_feature(features=["generate-debug-symbols"]),
                ],
                tool_path = "toolchain/mac/ld-with-dsym-packaging",
            ),
            tool (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"],
   ),
]

يمكن تنفيذ هذه الميزة نفسها بشكل مختلف تمامًا لنظام التشغيل Linux الذي يستخدم fission أو لنظام التشغيل Windows، ما يؤدي إلى إنشاء .pdb ملف. على سبيل المثال، قد يظهر عملية تنفيذ رمز تصحيح الأخطاء المستند إلى fission على النحو التالي:

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

action_configs = [
    action_config (
        name = ACTION_NAMES.cpp_compile,
        tools = [
            tool(
                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"],
                    ),
                ],
            ),
      ],
    ),
]

الإبلاغ عن المجموعات

تتيح لك CcToolchainConfigInfo تجميع العلامات في مجموعات لها غرض محدّد. يمكنك تحديد علامة باستخدام متغيرات محددة مسبقًا ضمن قيمة العلامة، والتي توسعها أداة التجميع عند إضافة العلامة إلى أمر الإصدار. مثلاً:

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

في هذه الحالة، سيتم استبدال محتوى العلامة بمسار ملف الإخراج للإجراء.

يتم توسيع مجموعات العلامات إلى أمر الإصدار بالترتيب الذي تظهر به في القائمة، من أعلى إلى أسفل، من اليسار إلى اليمين.

بالنسبة إلى العلامات التي تحتاج إلى تكرارها بقيم مختلفة عند إضافتها إلى أمر الإصدار، يمكن لمجموعة العلامات تكرار المتغيرات من النوع list. على سبيل المثال، المتغير include_path من النوع list:

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

توسيع إلى -I<path> لكل عنصر مسار في قائمة include_paths. يتم توسيع كل العلامات (أو flag_group) في نص بيان مجموعة الإبلاغات كوحدة. مثلاً:

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

توسيع إلى -I <path> لكل عنصر مسار في قائمة include_paths.

يمكن تكرار المتغير عدة مرات. مثلاً:

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

تتوسّع إلى:

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

يمكن أن تتوافق المتغيّرات مع البُنى التي يمكن الوصول إليها باستخدام رمز النقطة. على سبيل المثال:

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

يمكن دمج البنى وقد تحتوي أيضًا على تسلسلات. لمنع تضارب الأسماء، ولتكون واضحًا، يجب تحديد المسار الكامل عبر الحقول. على سبيل المثال:

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

توسيع شرطي

تتيح مجموعات العلامات توسيعًا مشروطًا استنادًا إلى وجود متغيّر معيّن أو حقله باستخدام السمات expand_if_available أو expand_if_not_available أو expand_if_true أو expand_if_false أو expand_if_equal. مثلاً:

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

يقدم هذا القسم مرجعًا لمتغيّرات الإصدار وميزاته ومعلومات أخرى مطلوبة لضبط قواعد C++ بنجاح.

متغيرات أداة CCToolchainConfigInfo

في ما يلي مرجع لمتغيّرات الإصدار CcToolchainConfigInfo.

المتغيّر الإجراء الوصف
source_file تجميع ملف المصدر المراد تجميعه.
input_file شريط قطع العناصر على شكل شريط.
output_file تجميع تجميع المحتوى.
output_assembly_file تجميع ملف التجميع الصادر. ينطبق ذلك فقط عندما ينتج عن الإجراء compile نص تجميع، ويتم ذلك عادةً عند استخدام العلامة --save_temps. المحتوى مماثل للخاصية output_file.
output_preprocess_file تجميع النتائج المُعالَجة مسبقًا. ينطبق فقط على تجميع الإجراءات التي تعالج الملفات المصدر فقط مسبقًا، وعادةً عند استخدام العلامة --save_temps. المحتوى مماثل للخاصية output_file.
includes تجميع يجب أن يتضمّن تسلسل الملفات المصدر غير المجمَّع بدون شرط.
include_paths تجميع أدلة التسلسل التي يبحث فيها المُجمِّع عن العناوين المضمّنة باستخدام #include<foo.h> و#include "foo.h".
quote_include_paths تجميع يتضمن تسلسل -iquote - الأدلة التي يبحث فيها المُجمِّع عن العناوين المضمّنة باستخدام #include "foo.h".
system_include_paths تجميع يتضمن تسلسل -isystem - الأدلة التي يبحث فيها المُجمِّع عن العناوين المضمّنة باستخدام #include <foo.h>.
dependency_file تجميع ملف التبعية .d الذي أنشأه برنامج التجميع.
preprocessor_defines تجميع تسلسل defines، مثل --DDEBUG
pic تجميع تجميع النتائج في رمز مستقل عن الموضع.
gcov_gcno_file تجميع ملف التغطية gcov.
per_object_debug_info_file تجميع ملف معلومات تصحيح الأخطاء لكل كائن (.dwp).
stripotps شريط تسلسل stripopts.
legacy_compile_flags تجميع تسلسل العلامات من الحقل CROSSTOOL القديم، مثل compiler_flag وoptional_compiler_flag وcxx_flag وoptional_cxx_flag
user_compile_flags تجميع تسلسل العلامات من السمة للقاعدة copt أو من العلامات --copt و--cxxopt و--conlyopt
unfiltered_compile_flags تجميع تسلسل العلامات من الحقل unfiltered_cxx_flag القديم CROSSTOOL أو الميزة unfiltered_compile_flags لا تتم فلترة هذه العناصر باستخدام سمة القاعدة nocopts.
sysroot sysroot.
runtime_library_search_directories الرابط الإدخالات في مسار البحث وقت تشغيل الرابط (عادةً ما يتم ضبطها باستخدام العلامة -rpath).
library_search_directories الرابط الإدخالات في مسار البحث عن رابط (يتم عادةً ضبطها باستخدام العلامة -L).
libraries_to_link الرابط العلامات التي توفّر ملفات لربطها كإدخالات في استدعاء الرابط
def_file_path الرابط موقع ملف def المستخدم في نظام التشغيل Windows مع MSVC.
linker_param_file الرابط موقع ملف رابط الرابط الذي تم إنشاؤه بواسطة bazel للتغلب على الحد الأقصى لطول سطر الأوامر.
output_execpath الرابط تنفيذ مخرجات الرابط.
generate_interface_library الرابط "yes" أو "no" حسب ما إذا كان يجب إنشاء مكتبة الواجهة أم لا.
interface_library_builder_path الرابط المسار إلى أداة إنشاء مكتبة الواجهة.
interface_library_input_path الرابط مُدخلات أداة إنشاء ifso مكتبة المكتبة.
interface_library_output_path الرابط المسار الذي يجب إنشاء مكتبة واجهة فيه باستخدام أداة الإنشاء ifso.
legacy_link_flags الرابط علامات الرابط الواردة من حقول CROSSTOOL القديمة
user_link_flags الرابط علامات الرابط الواردة من السمة --linkopt أو linkopts
linkstamp_paths الرابط متغير إصدار يمنح مسارات link.
force_pic الرابط يشير توفّر هذا المتغيّر إلى أنّه يجب إنشاء رمز PIC/PIE (تم تمرير خيار البازل `--force_pic`).
strip_debug_symbols الرابط ويشير توفّر هذا المتغيّر إلى أنه يجب إزالة رموز تصحيح الأخطاء.
is_cc_test الرابط موثوق به عندما يكون الإجراء الحالي هو إجراء ربط cc_test، أو خطأ، بخلاف ذلك.
is_using_fission تجميع، رابط ويشير توفّر هذا المتغيّر إلى أنه تم تفعيل الاختراق (معلومات تصحيح الأخطاء لكل عنصر). ستظهر معلومات تصحيح الأخطاء في ملفَين (.dwo) بدلاً من .o ملف، ويجب أن يعرف برنامج التجميع والرابط ذلك.
fdo_instrument_path تجميع، رابط المسار إلى الدليل الذي يخزِّن الملف الشخصي لآلة التوقف عن العمل.
fdo_profile_path تجميع المسار إلى الملف الشخصي لإدارة الأغذية والدواء
fdo_prefetch_hints_path تجميع المسار إلى الملف الشخصي للاسترجاع المسبق لذاكرة التخزين المؤقت.
csfdo_instrument_path تجميع، رابط المسار إلى الدليل الذي يخزّن ملف تعريف أداة FDO الحساس للسياق.

الميزات المعروفة

في ما يلي مرجع للميزات وشروط التفعيل.

الميزة الوثائق
opt | dbg | fastbuild يتم تفعيله تلقائيًا استنادًا إلى وضع التجميع.
static_linking_mode | dynamic_linking_mode ويتم تفعيل هذه الميزة تلقائيًا استنادًا إلى وضع الربط.
per_object_debug_info يتم تفعيل هذه السياسة إذا تم تحديد الميزة supports_fission وتفعيلها، وسيتم تحديد وضع التجميع الحالي في العلامة --fission.
supports_start_end_lib في حال تفعيل السياسة (وضبط الخيار --start_end_lib)، لن يتم ربط Bazel بالمكتبات الثابتة، بل سيتم استخدام خيارات الرابط --start-lib/--end-lib لربط العناصر مباشرةً. وذلك يؤدي إلى تسريع عملية الإنشاء لأنّ Bazel لا يحتاج إلى إنشاء مكتبات ثابتة.
supports_interface_shared_libraries إذا تم تفعيل Bazel (وتم ضبط الخيار --interface_shared_objects)، سيتم ربط الأهداف التي تم ضبط linkstatic على False (cc_tests تلقائيًا) مقابل المكتبات المشتركة للواجهة. ويساهم ذلك في زيادة سرعة إعادة الربط.
supports_dynamic_linker عند التفعيل، ستعرف قواعد C++ أن سلسلة الأدوات يمكنها إنشاء مكتبات مشتركة.
static_link_cpp_runtimes في حال تفعيل هذه الميزة، سيعمل Bazel على ربط وقت تشغيل C++ بشكل ثابت في وضع الربط الثابت وديناميكيًا في وضع الربط الديناميكي. ستتم إضافة العناصر المحدّدة في السمة cc_toolchain.static_runtime_lib أو cc_toolchain.dynamic_runtime_lib (بناءً على وضع الربط) إلى إجراءات الربط.
supports_pic في حال تفعيل هذا الإعداد، ستعرف سلسلة الأدوات أن تستخدم كائنات PIC للمكتبات الديناميكية. يكون متغير "الصورة" متاحًا عند الحاجة إلى تجميع مفاتيح PIC. وإذا لم يتم تفعيل الإعداد تلقائيًا، وتم تمرير "--force_pic"، سيطلب تطبيق Bazel إدخال `supports_pic` ويتحقّق من تفعيل الميزة. إذا كانت الميزة غير متوفّرة أو يتعذّر تفعيلها، لا يمكن استخدام "--force_pic".
static_linking_mode | dynamic_linking_mode ويتم تفعيل هذه الميزة تلقائيًا استنادًا إلى وضع الربط.
no_legacy_features يمنع Bazel من إضافة الميزات القديمة إلى إعداد C++ عند توفره. يمكنك الاطّلاع على القائمة الكاملة بالميزات.

منطق تصحيح الميزات القديمة

يطبِّق Bazel التغييرات التالية على ميزات سلسلة الأدوات من أجل التوافق مع الأنظمة القديمة:

  • نقل ميزة legacy_compile_flags إلى أعلى سلسلة الأدوات
  • نقل ميزة default_compile_flags إلى أعلى سلسلة الأدوات
  • لإضافة ميزة dependency_file (إذا لم تكن موجودة) إلى أعلى سلسلة الأدوات
  • لإضافة ميزة pic (إذا لم تكن موجودة) إلى أعلى سلسلة الأدوات
  • لإضافة ميزة per_object_debug_info (إذا لم تكن موجودة) إلى أعلى سلسلة الأدوات
  • لإضافة ميزة preprocessor_defines (إذا لم تكن موجودة) إلى أعلى سلسلة الأدوات
  • لإضافة ميزة includes (إذا لم تكن موجودة) إلى أعلى سلسلة الأدوات
  • لإضافة ميزة include_paths (إذا لم تكن موجودة) إلى أعلى سلسلة الأدوات
  • لإضافة ميزة fdo_instrument (إذا لم تكن موجودة) إلى أعلى سلسلة الأدوات
  • لإضافة ميزة fdo_optimize (إذا لم تكن موجودة) إلى أعلى سلسلة الأدوات
  • لإضافة ميزة cs_fdo_instrument (إذا لم تكن موجودة) إلى أعلى سلسلة الأدوات
  • لإضافة ميزة cs_fdo_optimize (إذا لم تكن موجودة) إلى أعلى سلسلة الأدوات
  • لإضافة ميزة fdo_prefetch_hints (إذا لم تكن موجودة) إلى أعلى سلسلة الأدوات
  • لإضافة ميزة autofdo (إذا لم تكن موجودة) إلى أعلى سلسلة الأدوات
  • لإضافة ميزة build_interface_libraries (إذا لم تكن موجودة) إلى أعلى سلسلة الأدوات
  • لإضافة ميزة dynamic_library_linker_tool (إذا لم تكن موجودة) إلى أعلى سلسلة الأدوات
  • لإضافة ميزة shared_flag (إذا لم تكن موجودة) إلى أعلى سلسلة الأدوات
  • لإضافة ميزة linkstamps (إذا لم تكن موجودة) إلى أعلى سلسلة الأدوات
  • لإضافة ميزة output_execpath_flags (إذا لم تكن موجودة) إلى أعلى سلسلة الأدوات
  • لإضافة ميزة runtime_library_search_directories (إذا لم تكن موجودة) إلى أعلى سلسلة الأدوات
  • لإضافة ميزة library_search_directories (إذا لم تكن موجودة) إلى أعلى سلسلة الأدوات
  • لإضافة ميزة archiver_flags (إذا لم تكن موجودة) إلى أعلى سلسلة الأدوات
  • لإضافة ميزة libraries_to_link (إذا لم تكن موجودة) إلى أعلى سلسلة الأدوات
  • لإضافة ميزة force_pic_flags (إذا لم تكن موجودة) إلى أعلى سلسلة الأدوات
  • لإضافة ميزة user_link_flags (إذا لم تكن موجودة) إلى أعلى سلسلة الأدوات
  • لإضافة ميزة legacy_link_flags (إذا لم تكن موجودة) إلى أعلى سلسلة الأدوات
  • لإضافة ميزة static_libgcc (إذا لم تكن موجودة) إلى أعلى سلسلة الأدوات
  • لإضافة ميزة fission_support (إذا لم تكن موجودة) إلى أعلى سلسلة الأدوات
  • لإضافة ميزة strip_debug_symbols (إذا لم تكن موجودة) إلى أعلى سلسلة الأدوات
  • لإضافة ميزة coverage (إذا لم تكن موجودة) إلى أعلى سلسلة الأدوات
  • لإضافة ميزة llvm_coverage_map_format (إذا لم تكن موجودة) إلى أعلى سلسلة الأدوات
  • لإضافة ميزة gcc_coverage_map_format (إذا لم تكن موجودة) إلى أعلى سلسلة الأدوات
  • لإضافة ميزة fully_static_link (إذا لم تكن موجودة) في أسفل سلسلة الأدوات
  • لإضافة ميزة user_compile_flags (إذا لم تكن موجودة) في أسفل سلسلة الأدوات
  • لإضافة ميزة sysroot (إذا لم تكن موجودة) في أسفل سلسلة الأدوات
  • لإضافة ميزة unfiltered_compile_flags (إذا لم تكن موجودة) في أسفل سلسلة الأدوات
  • لإضافة ميزة linker_param_file (إذا لم تكن موجودة) في أسفل سلسلة الأدوات
  • لإضافة ميزة compiler_input_flags (إذا لم تكن موجودة) في أسفل سلسلة الأدوات
  • لإضافة ميزة compiler_output_flags (إذا لم تكن موجودة) في أسفل سلسلة الأدوات

هذه قائمة طويلة بالميزات. وتتمثّل الخطة في التخلص منها بعد الانتهاء من استخدام أداة Crosslar in Starlark. بالنسبة إلى القارئ المهتم، يُرجى الاطّلاع على عملية التنفيذ في CppActionConfigs، وبالنسبة إلى سلاسل أدوات الإنتاج، يمكنك إضافة no_legacy_features لجعل سلسلة الأدوات أكثر مستقلة.