การกำหนดค่าเชนเครื่องมือ C++

วันที่ รายงานปัญหา ดูแหล่งที่มา ตอนกลางคืน · 7.3 · 7.2 · 7.1 · 7.0 · 6.5

ภาพรวม

Bazel ต้องการความรู้เกี่ยวกับ ภายในของคอมไพเลอร์ เช่น ไดเรกทอรีและแฟล็กที่สำคัญ อีกนัยหนึ่งคือ Bazel ต้องการโมเดลแบบง่ายของคอมไพเลอร์เพื่อทำความเข้าใจ ที่มีประสิทธิภาพมากขึ้น

Bazel จำเป็นต้องทราบข้อมูลต่อไปนี้

• คอมไพเลอร์รองรับ ThinLTO, โมดูล, การลิงก์แบบไดนามิก หรือ PIC (โค้ดอิสระตามตำแหน่ง)
• เส้นทางไปยังเครื่องมือที่จำเป็น เช่น gcc, ld, ar, objcopy และอื่นๆ
• ระบบในตัวจะมีไดเรกทอรี Bazel ต้องการข้อมูลเหล่านี้เพื่อยืนยันว่า ส่วนหัวทั้งหมดที่รวมอยู่ในไฟล์ต้นฉบับได้รับการประกาศอย่างถูกต้องใน ไฟล์ BUILD
• sysroot เริ่มต้น
• แฟล็กใดที่จะใช้ในการคอมไพล์ การลิงก์ การเก็บ
• แฟล็กใดที่จะใช้สำหรับโหมดการคอมไพล์ที่รองรับ (opt, dbg, Fastbuild)
• ทำให้เป็นตัวแปรที่จำเป็นสำหรับคอมไพเลอร์โดยเฉพาะ

หากคอมไพเลอร์รองรับสถาปัตยกรรมหลายรายการ Bazel จะต้องกำหนดค่า แยกกัน

CcToolchainConfigInfo เป็นผู้ให้บริการที่ระบุระดับ สำหรับการกำหนดค่าลักษณะการทำงานของกฎ C++ ของ Bazel โดยค่าเริ่มต้น Bazel กำหนดค่า CcToolchainConfigInfo สำหรับบิลด์ของคุณโดยอัตโนมัติ แต่ จะมีตัวเลือกให้กำหนดค่าด้วยตนเอง คุณต้องมีกฎของ Starlark ซึ่งระบุ CcToolchainConfigInfo และคุณต้องชี้ toolchain_config ของแอตทริบิวต์ cc_toolchain ลงในกฎ คุณสร้าง CcToolchainConfigInfo ได้โดยโทร cc_common.create_cc_toolchain_config_info() คุณสามารถค้นหาตัวสร้าง Starlark สำหรับ Struct ทั้งหมดที่จำเป็นสำหรับกระบวนการนี้ใน @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 ต้องมีข้อมูลต่อไปนี้

• คอมไพเลอร์หรือ Linker ที่จะใช้
• แฟล็กบรรทัดคำสั่งสำหรับคอมไพเลอร์/Linker
• แฟล็กการกำหนดค่าที่ส่งผ่านตัวเลือก --copt/--linkopt
• ตัวแปรสภาพแวดล้อม
• อาร์ติแฟกต์ที่จำเป็นในแซนด์บ็อกซ์ที่มีการดำเนินการ

ข้อมูลทั้งหมดข้างต้น ยกเว้นอาร์ติแฟกต์ที่จําเป็นในแซนด์บ็อกซ์คือ ที่ระบุในเป้าหมาย Starlark ที่ cc_toolchain ชี้ไป

มีการประกาศอาร์ติแฟกต์ที่จะจัดส่งไปยังแซนด์บ็อกซ์ใน cc_toolchain เป้าหมาย เช่น คุณใช้แอตทริบิวต์ cc_toolchain.linker_files เพื่อทำสิ่งต่อไปนี้ได้ ระบุไลบรารีไบนารีของ Linker และ Toolchain เพื่อจัดส่งไปยังแซนด์บ็อกซ์

การเลือกเครื่องมือเชน

ตรรกะการเลือก Toolchain มีหน้าที่ดังต่อไปนี้

1. ผู้ใช้ระบุเป้าหมาย cc_toolchain_suite ในไฟล์และคะแนน BUILD Bazel ไปยังเป้าหมายโดยใช้ --crosstool_top ตัวเลือก

2. เป้าหมาย cc_toolchain_suite อ้างอิง Toolchain หลายเชน ค่าของการแจ้ง --cpu และ --compiler จะเป็นตัวกำหนดว่าสิ่งใด เลือก Toolchains ตามค่าแฟล็ก --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 โดยไม่ต้องแก้ไข ไบนารี Bazel กฎ C++ รองรับการดำเนินการที่ไม่ซ้ำหลายรายการซึ่งจัดทำเป็นเอกสารโดยละเอียด ในซอร์สโค้ด Bazel

ฟีเจอร์

ฟีเจอร์เป็นเอนทิตีที่ต้องแฟล็กบรรทัดคำสั่ง การดำเนินการ ข้อจำกัดในสภาพแวดล้อมการดำเนินการหรือการเปลี่ยนแปลงทรัพยากร Dependency ฟีเจอร์ อาจเป็นการอนุญาตให้ไฟล์ BUILD เลือกการกำหนดค่า เช่น treat_warnings_as_errors หรือโต้ตอบกับกฎ C++ และ รวมการดำเนินการคอมไพล์ใหม่ๆ และอินพุตในการคอมไพล์ เช่น header_modules หรือ thin_lto

ตามหลักการแล้ว CcToolchainConfigInfo จะมีรายการฟีเจอร์ โดยแต่ละรายการ ประกอบด้วยกลุ่ม Flag อย่างน้อย 1 กลุ่ม โดยแต่ละกลุ่มกำหนดรายการ Flag ที่ใช้กับการกระทำเฉพาะของ 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) หาก "requires" มี "feature_set" หลายรายการ ระบบจะรองรับฟีเจอร์นี้หากมีคุณสมบัติตรงตาม "feature_set" (เมื่อเปิดใช้ฟีเจอร์ที่ระบุทั้งหมด)
implies = ['feature']	ระดับฟีเจอร์ ฟีเจอร์นี้บอกเป็นนัยถึงฟีเจอร์ที่ระบุ การเปิดใช้ฟีเจอร์จะเป็นการเปิดใช้ฟีเจอร์ทั้งหมดโดยปริยายโดยปริยาย (กล่าวคือ ทำงานซ้ำๆ) นอกจากนี้ ยังช่วยให้สามารถแยกคำนวณการทำงานส่วนย่อยที่พบได้ทั่วไปจาก ชุดฟีเจอร์ เช่น ส่วนประกอบทั่วไปของน้ำยาฆ่าเชื้อ โดยนัย ไม่สามารถปิดใช้งานฟีเจอร์ได้
provides = ['feature']	ระดับฟีเจอร์ ระบุว่าฟีเจอร์นี้เป็นหนึ่งในหลายรายการ คุณลักษณะสำรองพิเศษ เช่น สารฆ่าเชื้อทั้งหมดอาจ ระบุ provides = ["sanitizer"] ซึ่งจะช่วยปรับปรุงการจัดการข้อผิดพลาดด้วยการแสดงทางเลือกต่างๆ หากผู้ใช้ถามว่า สำหรับฟีเจอร์ที่ใช้แยกกัน 2 อย่างขึ้นไปได้ในคราวเดียว
with_features = [ with_feature_set( features = ['feature-1'], not_features = ['feature-2'], ), ]	ระดับชุดการแจ้งว่าไม่เหมาะสม ฟีเจอร์สามารถระบุชุดการตั้งค่าสถานะหลายชุดที่มีหลายชุดได้ เมื่อระบุ with_features ชุดธงจะขยายเท่านั้น ลงในคำสั่งบิลด์หากมี with_feature_set อย่างน้อย 1 รายการ ฟีเจอร์ทั้งหมดใน features ที่ระบุ เปิดใช้งานอยู่ และฟีเจอร์ทั้งหมดที่ระบุใน not_features ตั้งค่าแล้ว หากไม่ได้ระบุ with_features ชุดธงจะเป็น ใช้โดยไม่มีเงื่อนไขสำหรับการดำเนินการทั้งหมดที่ระบุ

การทำงาน

การดำเนินการมีความยืดหยุ่นในการปรับเปลี่ยนสถานการณ์ภายใต้ การดำเนินการที่จะดำเนินการโดยไม่คาดเดาว่าการดำเนินการนั้นจะทำงานอย่างไร CANNOT TRANSLATE action_config จะระบุไบนารีของเครื่องมือที่การดำเนินการทำ ขณะที่ feature ระบุการกำหนดค่า (แฟล็ก) ที่กำหนดวิธีการที่เครื่องมือดังกล่าว จะทำงานเมื่อมีการเรียกใช้การดำเนินการ

ฟีเจอร์ของการดําเนินการอ้างอิงเพื่อส่งสัญญาณการดําเนินการของ Bazel เนื่องจากการกระทำสามารถปรับเปลี่ยนกราฟการทำงานของ Bazel ได้ ผู้ให้บริการ CcToolchainConfigInfo รายมีการดำเนินการที่มีแฟล็กและเครื่องมือ ที่เกี่ยวข้อง เช่น c++-compile มีการกำหนดธงให้กับการดำเนินการแต่ละรายการ โดยการเชื่อมโยงพวกเขากับฟีเจอร์

ชื่อการกระทำแต่ละชื่อแสดงถึงการกระทำประเภทเดียวที่ดำเนินการโดย Bazel เช่น การคอมไพล์หรือการลิงก์ อย่างไรก็ตาม มีความสัมพันธ์แบบหลายคนต่อหนึ่ง การดำเนินการและประเภทการดำเนินการ Bazel โดยที่ประเภทการดำเนินการของ Bazel นั้นหมายถึงคลาส Java ที่ใช้การดำเนินการ (เช่น CppCompileAction) โดยเฉพาะอย่างยิ่ง ฟิลด์ "การดำเนินการของแอสเซมเมอร์" และ "การดำเนินการของคอมไพเลอร์" ในตารางด้านล่างคือ CppCompileAction ขณะที่การทำงานของลิงก์คือ CppLinkAction

การดำเนินการต่างๆ ของตัวประกอบ

การดำเนินการ	คำอธิบาย
preprocess-assemble	ประกอบพร้อมการประมวลผลล่วงหน้า โดยปกติมีไว้สำหรับ .S ไฟล์
assemble	ประกอบเองโดยไม่ประมวลผลล่วงหน้า โดยปกติมีไว้สำหรับ .s ไฟล์

การทำงานของคอมไพเลอร์

การดำเนินการ	คำอธิบาย
cc-flags-make-variable	เผยแพร่ CC_FLAGS ไปยัง Genrule
c-compile	คอมไพล์เป็น C
c++-compile	คอมไพล์เป็น C++
c++-header-parsing	เรียกใช้โปรแกรมแยกวิเคราะห์ของคอมไพเลอร์ในไฟล์ส่วนหัวเพื่อให้แน่ใจว่าส่วนหัว จะเกิดขึ้นได้ด้วยตัวเอง เพราะจะทำให้เกิดข้อผิดพลาดในการคอมไพล์ได้ มีผล กับ Toolchain ที่รองรับโมดูลเท่านั้น

การดำเนินของการลิงก์

การดำเนินการ	คำอธิบาย
c++-link-dynamic-library	ลิงก์ไลบรารีที่แชร์ซึ่งมีทรัพยากร Dependency ทั้งหมด
c++-link-nodeps-dynamic-library	ลิงก์ไลบรารีที่ใช้ร่วมกันซึ่งมีแหล่งที่มา cc_library รายการเท่านั้น
c++-link-executable	ลิงก์ไลบรารีที่พร้อมใช้งานขั้นสุดท้าย

การดำเนินการ AR

การดำเนินการ AR รวมไฟล์ออบเจ็กต์ลงในไลบรารีที่เก็บถาวร (.a ไฟล์) ผ่าน ar และเข้ารหัสความหมายบางอย่างไว้ในชื่อ

การดำเนินการ	คำอธิบาย
c++-link-static-library	สร้างไลบรารีแบบคงที่ (ที่เก็บถาวร)

การดำเนินการ LTO

การดำเนินการ	คำอธิบาย
lto-backend	การดำเนินการ ThinLTO คอมไพล์บิตโค้ดเป็นออบเจ็กต์ดั้งเดิม
lto-index	การดำเนินการ ThinLTO ที่สร้างดัชนีทั่วโลก

การใช้ action_config

action_config เป็นโครงสร้าง Starlark ที่อธิบาย Bazel การทำงานโดยระบุเครื่องมือ (ไบนารี) ที่จะเรียกใช้ระหว่างการดำเนินการและชุดของ สถานะที่กำหนดโดยฟีเจอร์ แฟล็กเหล่านี้จะใช้ข้อจำกัดกับแท็ก

ตัวสร้าง action_config() มีพารามิเตอร์ต่อไปนี้:

แอตทริบิวต์	คำอธิบาย
action_name	การกระทำของ Bazel ที่สอดคล้องกับการดำเนินการนี้ Bazel ใช้แอตทริบิวต์นี้เพื่อสำรวจเครื่องมือและการดำเนินการตามการดำเนินการ
tools	ไฟล์ปฏิบัติการที่จะเรียกใช้ เครื่องมือที่ใช้กับการดำเนินการจะเป็น เครื่องมือแรกในรายการที่มีชุดฟีเจอร์ที่ตรงกับฟีเจอร์ การกำหนดค่า ต้องระบุค่าเริ่มต้น
flag_sets	รายการแฟล็กที่ใช้กับกลุ่มการดำเนินการ เหมือนกับ
env_sets	รายการข้อจำกัดของสภาพแวดล้อมที่ใช้กับกลุ่มการดำเนินการ เหมือนกับสำหรับฟีเจอร์

action_config สามารถกำหนดให้ใช้และกล่าวเป็นนัยถึงฟีเจอร์อื่นๆ และ action_config ตามที่ ความสัมพันธ์เกี่ยวกับฟีเจอร์ที่อธิบายก่อนหน้านี้ ลักษณะการทำงานนี้ นั้นคล้ายกับคุณลักษณะ

แอตทริบิวต์ 2 รายการสุดท้ายซ้ำซ้อนกับแอตทริบิวต์ที่เกี่ยวข้องใน และรวมไว้เนื่องจากการดำเนินการของ Bazel บางกรณีจำเป็นต้องมีการแจ้งว่าไม่เหมาะสม หรือ โดยมีเป้าหมายเพื่อหลีกเลี่ยง action_config+feature ที่ไม่จำเป็น คู่ โดยปกติแล้ว การแชร์ฟีเจอร์เดียวในหลายๆ action_config แนะนำ

คุณไม่สามารถกำหนด action_config มากกว่า 1 รายการด้วย action_name เดียวกัน ภายในเครื่องมือเดียวกัน วิธีนี้จะป้องกันความกำกวมในเส้นทางเครื่องมือ และบังคับใช้เจตนารมณ์เบื้องหลัง action_config ซึ่งก็คือคุณสมบัติของการดำเนินการ อธิบายไว้อย่างชัดเจนในที่เดียวใน Toolchain

การใช้เครื่องมือสร้างเครื่องมือ

action_config สามารถระบุชุดเครื่องมือผ่านพารามิเตอร์ tools ตัวสร้าง tool() จะรับพารามิเตอร์ต่อไปนี้

ฟิลด์	คำอธิบาย
path	เส้นทางไปยังเครื่องมือที่เป็นปัญหา (สัมพันธ์กับตำแหน่งปัจจุบัน)
with_features	รายการชุดฟีเจอร์ที่คุณต้องทำตามอย่างน้อย 1 รายการ ในการใช้เครื่องมือ

สำหรับ action_config หนึ่งๆ ระบบจะใช้ tool เพียงรายการเดียว เส้นทางเครื่องมือและข้อกำหนดการดำเนินการกับการดำเนินการของ Bazel เลือกเครื่องมือแล้ว โดยทำซ้ำผ่านแอตทริบิวต์ tools ใน action_config จนกว่าจะใช้เครื่องมือ ที่มีชุด with_feature ตรงกับการกำหนดค่าฟีเจอร์ (ดูความสัมพันธ์เกี่ยวกับฟีเจอร์ก่อนหน้าในหน้านี้ ) คุณควรสิ้นสุดรายการเครื่องมือด้วยค่าเริ่มต้น ที่สอดคล้องกับการกำหนดค่าฟีเจอร์ที่ว่างเปล่า

ตัวอย่างการใช้

ฟีเจอร์และการทำงานสามารถใช้งานร่วมกับการดำเนินการของ Bazel ได้ โดยใช้ความหมายข้ามแพลตฟอร์มที่หลากหลาย ตัวอย่างเช่น เปิดใช้การแก้ไขข้อบกพร่องในการสร้างสัญลักษณ์ macOS กำหนดให้สร้างสัญลักษณ์ในการดำเนินการคอมไพล์ จากนั้นเรียกใช้ เครื่องมือพิเศษในระหว่างการดำเนินการลิงก์เพื่อสร้างที่เก็บถาวรของ DS ที่บีบอัด จากนั้นคลายการบีบอัดไฟล์ที่เก็บถาวรนั้นเพื่อสร้าง Bundle แอปพลิเคชันและ .plist ที่ใช้ได้ด้วย Xcode

Bazel ใช้วิธีการต่อไปนี้ unbundle-debuginfo เป็นการกระทำของ Bazel:

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

คุณลักษณะเดียวกันนี้สามารถใช้ได้แตกต่างกันโดยสิ้นเชิงสำหรับ Linux ซึ่งใช้ fission หรือสำหรับ Windows ที่สร้าง .pdb ไฟล์ ตัวอย่างเช่น พารามิเตอร์ การใช้งานสำหรับการสร้างสัญลักษณ์การแก้ไขข้อบกพร่องแบบ fission อาจมีลักษณะดังนี้ ดังต่อไปนี้:

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

รายงานกลุ่ม

CcToolchainConfigInfo ให้คุณรวมกลุ่มแฟล็กไว้ในกลุ่มที่แสดง วัตถุประสงค์ที่เฉพาะเจาะจง คุณสามารถระบุแฟล็กภายในโดยใช้ตัวแปรที่กำหนดไว้ล่วงหน้า ภายในค่า Flag ซึ่งคอมไพเลอร์จะขยายเมื่อเพิ่ม Flag ลงใน คำสั่งบิลด์ เช่น

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

ในกรณีนี้ เนื้อหาของแฟล็กจะแทนที่ด้วยเส้นทางไฟล์เอาต์พุต ของการดำเนินการ

ระบบจะขยายกลุ่มแฟล็กไปยังคำสั่งบิลด์ตามลำดับที่ปรากฏ ไว้ในรายการ ซึ่งได้แก่ จากบนลงล่าง ซ้ายไปขวา

สำหรับแฟล็กที่ต้องทำซ้ำด้วยค่าอื่นเมื่อเพิ่มลงในบิลด์ กลุ่มแฟล็กจะทำซ้ำตัวแปรประเภท list ได้ ตัวอย่างเช่น พารามิเตอร์ ตัวแปร include_path ของประเภท list:

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

ขยายเป็น -I<path> สำหรับองค์ประกอบเส้นทางแต่ละรายการในรายการ include_paths ทั้งหมด Flag (หรือ flag_group) ในเนื้อหาของการประกาศกลุ่ม Flag จะขยายออกเป็น หน่วย เช่น

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

ขยายเป็น -I <path> สำหรับองค์ประกอบเส้นทางแต่ละรายการในรายการ include_paths

ตัวแปร 1 ตัวแสดงซ้ำได้หลายครั้ง เช่น

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

หมายเหตุ: ตัวเลือก --whole_archive และ --no_whole_archive จะถูกเพิ่มลงใน คำสั่งบิลด์เฉพาะเมื่อไลบรารีที่ทำซ้ำในปัจจุบันมี ช่อง is_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	คอมไพล์	ไฟล์ทรัพยากร Dependency ของ .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	ลิงก์	รายการในเส้นทางการค้นหาแบบรันไทม์ของ Linker (โดยปกติ ที่ตั้งไว้ด้วยธง -rpath)
library_search_directories	ลิงก์	รายการในเส้นทางการค้นหา Linker (โดยปกติจะตั้งค่าด้วย ธง-L)
libraries_to_link	ลิงก์	แฟล็กที่ให้ไฟล์เพื่อลิงก์เป็นอินพุตในการเรียกใช้ Linker
def_file_path	ลิงก์	ตำแหน่งของไฟล์ def ที่ใช้ใน Windows ที่มี MSVC
linker_param_file	ลิงก์	ตำแหน่งของไฟล์พารามิเตอร์ Linker ที่สร้างโดย bazel ไปยัง เกินขีดจำกัดของความยาวของบรรทัดคำสั่ง
output_execpath	ลิงก์	ยกเว้นเอาต์พุตของ Linker
generate_interface_library	ลิงก์	"yes" หรือ "no" ขึ้นอยู่กับว่าไลบรารีอินเทอร์เฟซควร ได้
interface_library_builder_path	ลิงก์	เส้นทางไปยังเครื่องมือสร้างไลบรารีอินเทอร์เฟซ
interface_library_input_path	ลิงก์	อินพุตสำหรับเครื่องมือสร้างไลบรารีอินเทอร์เฟซ ifso
interface_library_output_path	ลิงก์	เส้นทางที่ใช้สร้างไลบรารีอินเทอร์เฟซโดยใช้เครื่องมือสร้าง ifso
legacy_link_flags	ลิงก์	แฟล็ก Linker มาจากช่อง CROSSTOOL เดิม
user_link_flags	ลิงก์	แฟล็ก Linker มาจาก --linkopt หรือ linkopts
linkstamp_paths	ลิงก์	ตัวแปรบิลด์ที่มีเส้นทางลิงก์สแตมป์
force_pic	ลิงก์	การมีอยู่ของตัวแปรนี้บ่งชี้ว่าโค้ด PIC/PIE ควร ขึ้น (มีการส่งตัวเลือก Bazel "--force_pic")
strip_debug_symbols	ลิงก์	การมีอยู่ของตัวแปรนี้บ่งชี้ว่าการแก้ไขข้อบกพร่อง สัญลักษณ์ควรถูกตัดออก
is_cc_test	ลิงก์	เป็นจริงเมื่อการดำเนินการปัจจุบันเป็น cc_test การดำเนินการลิงก์ หรือเป็นเท็จ
is_using_fission	คอมไพล์, ลิงก์	การมีอยู่ของตัวแปรนี้บ่งชี้ว่าฟิชชัน (ข้อมูลการแก้ไขข้อบกพร่องต่อออบเจ็กต์) แล้ว ข้อมูลการแก้ไขข้อบกพร่องจะอยู่ในไฟล์ .dwo แทน จาก .o ไฟล์ และคอมไพเลอร์และ Linker จำเป็นต้องทราบเรื่องนี้
fdo_instrument_path	คอมไพล์, ลิงก์	เส้นทางไปยังไดเรกทอรีที่เก็บโปรไฟล์การใช้เครื่องมือ FDO
fdo_profile_path	คอมไพล์	เส้นทางไปยังโปรไฟล์ FDO
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 ตัวเลือก Linker เพื่อลิงก์กับวัตถุ โดยตรง วิธีนี้จะช่วยให้สร้างได้เร็วขึ้นเนื่องจาก Bazel ไม่จำเป็นต้องสร้าง และไลบรารีแบบคงที่
supports_interface_shared_libraries	หากเปิดใช้ (และตัวเลือก --interface_shared_objects คือ ) Bazel จะลิงก์เป้าหมายที่มีการตั้งค่า linkstatic เป็น เท็จ (ค่าเริ่มต้นคือ cc_test) เทียบกับอินเทอร์เฟซที่แชร์ ห้องสมุด ซึ่งจะทำให้เพิ่มการลิงก์ใหม่ได้เร็วขึ้น
supports_dynamic_linker	หากเปิดใช้ กฎ C++ จะทราบว่า Toolchain สร้างการแชร์ได้ ห้องสมุด
static_link_cpp_runtimes	หากเปิดใช้ Bazel จะลิงก์รันไทม์ของ C++ แบบคงที่ในการลิงก์แบบคงที่ และแบบไดนามิกในโหมดการลิงก์แบบไดนามิก สิ่งประดิษฐ์ ที่ระบุไว้ใน cc_toolchain.static_runtime_lib หรือ แอตทริบิวต์ cc_toolchain.dynamic_runtime_lib (ขึ้นอยู่กับ โหมดการลิงก์) จะได้รับการเพิ่มลงในการดำเนินการลิงก์
supports_pic	หากเปิดใช้ Toolchain จะทราบว่าใช้ออบเจ็กต์ 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 ไปที่ด้านบนสุดของ Toolchain
• ย้ายฟีเจอร์ default_compile_flags ไปที่ด้านบนสุดของ Toolchain
• เพิ่มฟีเจอร์ dependency_file (หากไม่มี) ที่ด้านบนของ Toolchain
• เพิ่มฟีเจอร์ pic (หากไม่มี) ที่ด้านบนของ Toolchain
• เพิ่มฟีเจอร์ per_object_debug_info (หากไม่มี) ที่ด้านบนของ Toolchain
• เพิ่มฟีเจอร์ preprocessor_defines (หากไม่มี) ที่ด้านบนของ Toolchain
• เพิ่มฟีเจอร์ includes (หากไม่มี) ที่ด้านบนของ Toolchain
• เพิ่มฟีเจอร์ include_paths (หากไม่มี) ที่ด้านบนของ Toolchain
• เพิ่มฟีเจอร์ fdo_instrument (หากไม่มี) ที่ด้านบนของ Toolchain
• เพิ่มฟีเจอร์ fdo_optimize (หากไม่มี) ที่ด้านบนของ Toolchain
• เพิ่มฟีเจอร์ cs_fdo_instrument (หากไม่มี) ที่ด้านบนของ Toolchain
• เพิ่มฟีเจอร์ cs_fdo_optimize (หากไม่มี) ที่ด้านบนของ Toolchain
• เพิ่มฟีเจอร์ fdo_prefetch_hints (หากไม่มี) ที่ด้านบนของ Toolchain
• เพิ่มฟีเจอร์ autofdo (หากไม่มี) ที่ด้านบนของ Toolchain
• เพิ่มฟีเจอร์ build_interface_libraries (หากไม่มี) ที่ด้านบนของ Toolchain
• เพิ่มฟีเจอร์ dynamic_library_linker_tool (หากไม่มี) ที่ด้านบนของ Toolchain
• เพิ่มฟีเจอร์ shared_flag (หากไม่มี) ที่ด้านบนของ Toolchain
• เพิ่มฟีเจอร์ linkstamps (หากไม่มี) ที่ด้านบนของ Toolchain
• เพิ่มฟีเจอร์ output_execpath_flags (หากไม่มี) ที่ด้านบนของ Toolchain
• เพิ่มฟีเจอร์ runtime_library_search_directories (หากไม่มี) ที่ด้านบนของ Toolchain
• เพิ่มฟีเจอร์ library_search_directories (หากไม่มี) ที่ด้านบนของ Toolchain
• เพิ่มฟีเจอร์ archiver_flags (หากไม่มี) ที่ด้านบนของ Toolchain
• เพิ่มฟีเจอร์ libraries_to_link (หากไม่มี) ที่ด้านบนของ Toolchain
• เพิ่มฟีเจอร์ force_pic_flags (หากไม่มี) ที่ด้านบนของ Toolchain
• เพิ่มฟีเจอร์ user_link_flags (หากไม่มี) ที่ด้านบนของ Toolchain
• เพิ่มฟีเจอร์ legacy_link_flags (หากไม่มี) ที่ด้านบนของ Toolchain
• เพิ่มฟีเจอร์ static_libgcc (หากไม่มี) ที่ด้านบนของ Toolchain
• เพิ่มฟีเจอร์ fission_support (หากไม่มี) ที่ด้านบนของ Toolchain
• เพิ่มฟีเจอร์ strip_debug_symbols (หากไม่มี) ที่ด้านบนของ Toolchain
• เพิ่มฟีเจอร์ coverage (หากไม่มี) ที่ด้านบนของ Toolchain
• เพิ่มฟีเจอร์ llvm_coverage_map_format (หากไม่มี) ที่ด้านบนของ Toolchain
• เพิ่มฟีเจอร์ gcc_coverage_map_format (หากไม่มี) ที่ด้านบนของ Toolchain
• เพิ่มฟีเจอร์ fully_static_link (หากไม่มี) ที่ด้านล่างของ Toolchain
• เพิ่มฟีเจอร์ user_compile_flags (หากไม่มี) ที่ด้านล่างของ Toolchain
• เพิ่มฟีเจอร์ sysroot (หากไม่มี) ที่ด้านล่างของ Toolchain
• เพิ่มฟีเจอร์ unfiltered_compile_flags (หากไม่มี) ที่ด้านล่างของ Toolchain
• เพิ่มฟีเจอร์ linker_param_file (หากไม่มี) ที่ด้านล่างของ Toolchain
• เพิ่มฟีเจอร์ compiler_input_flags (หากไม่มี) ที่ด้านล่างของ Toolchain
• เพิ่มฟีเจอร์ compiler_output_flags (หากไม่มี) ที่ด้านล่างของ Toolchain

เราจะพูดถึงฟีเจอร์ต่างๆ จำนวนมาก แผนการคือการกำจัดไฟล์ทิ้งเพียงครั้งเดียว เครื่องมือข้ามใน Starlark คือ เสร็จสิ้น สำหรับผู้ที่ต้องการอ่าน ดูการใช้งานได้ใน CppActionConfigs, และสำหรับ Toolchain เวอร์ชันที่ใช้งานจริง ให้พิจารณาเพิ่ม no_legacy_features เพื่อให้ เชนเครื่องมือแบบสแตนด์อโลนมากขึ้น