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

รายงานปัญหา ดูแหล่งที่มา Nightly · 8.3 · 8.2 · 8.1 · 8.0 · 7.6

ภาพรวม

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 สำหรับโครงสร้างทั้งหมดที่จำเป็นในกระบวนการได้ที่ @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 ต้องมีข้อมูลต่อไปนี้

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

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

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

การเลือก Toolchain

ตรรกะการเลือกเชนเครื่องมือทํางานดังนี้

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

2. cc_toolchain_suite เป้าหมายอ้างอิงเชนเครื่องมือหลายรายการ ค่าของแฟล็ก --cpu และ --compiler จะกำหนดว่าระบบจะเลือก Toolchain ใด โดยอิงตามค่าของแฟล็ก --cpu เพียงอย่างเดียว หรือ อิงตามค่า --cpu | --compiler ร่วม กระบวนการเลือกมีดังนี้

   • หากระบุตัวเลือก --compiler Bazel จะเลือกรายการที่สอดคล้องกันจากแอตทริบิวต์ cc_toolchain_suite.toolchains ที่มี --cpu | --compiler หาก Bazel ไม่พบ รายการที่ตรงกัน ระบบจะแสดงข้อผิดพลาด

   • หากไม่ได้ระบุ--compiler Bazel จะเลือกรายการที่เกี่ยวข้องจากแอตทริบิวต์ cc_toolchain_suite.toolchains ที่มีเพียง --cpu

   • หากไม่ได้ระบุแฟล็ก Bazel จะตรวจสอบระบบโฮสต์และเลือกค่า --cpu ตามสิ่งที่พบ ดูโค้ดกลไกการตรวจสอบ

เมื่อเลือก Toolchain แล้ว ออบเจ็กต์ feature และ action_config ที่เกี่ยวข้องในกฎ Starlark จะควบคุมการกำหนดค่าของการสร้าง (นั่นคือ รายการที่อธิบายในภายหลัง) ข้อความเหล่านี้ช่วยให้สามารถใช้ฟีเจอร์ C++ ที่สมบูรณ์ใน Bazel โดยไม่ต้องแก้ไขไบนารีของ Bazel กฎ C++ รองรับการดำเนินการที่ไม่ซ้ำกันหลายรายการซึ่งมีรายละเอียดอยู่ใน ซอร์สโค้ดของ Bazel

ฟีเจอร์

ฟีเจอร์คือเอนทิตีที่ต้องใช้แฟล็กบรรทัดคำสั่ง การดำเนินการ ข้อจำกัดในสภาพแวดล้อมการดำเนินการ หรือการเปลี่ยนแปลงการขึ้นต่อกัน ฟีเจอร์ อาจเป็นอะไรที่เรียบง่าย เช่น การอนุญาตให้ไฟล์ 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 ซึ่งจะบังคับใช้ ข้อกำหนดและจัดการความขัดแย้งที่เกิดขึ้นตามลักษณะของฟีเจอร์ ที่กำหนดไว้ในการสร้าง ข้อกำหนดของ Toolchain ช่วยให้มีข้อจำกัดที่ละเอียดยิ่งขึ้น สำหรับการใช้งานโดยตรงภายในกฎ Starlark ที่ควบคุมการรองรับ และการขยายฟีเจอร์ ได้แก่

ข้อจำกัด	คำอธิบาย
requires = [ feature_set (features = [ 'feature-name-1', 'feature-name-2' ]), ]	ระดับฟีเจอร์ ฟีเจอร์นี้จะรองรับเฉพาะในกรณีที่เปิดใช้ฟีเจอร์ที่จำเป็นที่ระบุไว้ เท่านั้น เช่น เมื่อฟีเจอร์รองรับเฉพาะใน โหมดการสร้างบางโหมด (opt, dbg หรือ fastbuild) หาก `requires` มี `feature_set`หลายรายการ ระบบจะรองรับฟีเจอร์หากมี `feature_set`ใดรายการหนึ่งตรงตามเงื่อนไข (เมื่อเปิดใช้ฟีเจอร์ที่ระบุทั้งหมด)
implies = ['feature']	ระดับฟีเจอร์ ฟีเจอร์นี้หมายถึงฟีเจอร์ที่ระบุ การเปิดใช้ฟีเจอร์ยังเป็นการเปิดใช้ฟีเจอร์ทั้งหมดที่เกี่ยวข้องโดยนัยด้วย (กล่าวคือ ฟีเจอร์จะทำงานแบบเรียกซ้ำ) นอกจากนี้ ยังช่วยให้สามารถแยกฟังก์ชันการทำงานย่อยที่พบบ่อยออกจาก ชุดฟีเจอร์ เช่น ส่วนที่ใช้ร่วมกันของ Sanitizer ฟีเจอร์โดยนัย ปิดใช้ไม่ได้
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 ระบบจะใช้ชุดค่าสถานะ โดยไม่มีเงื่อนไขสำหรับการดำเนินการทุกอย่างที่ระบุ

การทำงาน

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

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

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

การดำเนินการของ Assembler

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

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

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

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

การดำเนินการ	คำอธิบาย
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	รายการ Flag ที่ใช้กับกลุ่มการกระทำ เช่นเดียวกับ ฟีเจอร์
env_sets	รายการข้อจำกัดด้านสภาพแวดล้อมที่ใช้กับกลุ่มการดำเนินการ เช่นเดียวกับฟีเจอร์

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

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

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

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

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

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

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

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

ฟีเจอร์และการดำเนินการสามารถใช้ร่วมกันเพื่อใช้การดำเนินการของ Bazel กับความหมายข้ามแพลตฟอร์มที่หลากหลาย ตัวอย่างเช่น การสร้างสัญลักษณ์การแก้ไขข้อบกพร่องใน macOS ต้องสร้างสัญลักษณ์ในการดำเนินการคอมไพล์ จากนั้นเรียกใช้เครื่องมือเฉพาะในระหว่างการดำเนินการลิงก์เพื่อสร้างที่เก็บถาวร dsym ที่บีบอัด แล้วจึงคลายการบีบอัดที่เก็บถาวรนั้นเพื่อสร้างชุดแอปพลิเคชันและไฟล์ .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_group (
    flags = ["%{output_execpath}"],
)

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

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

สําหรับแฟล็กที่ต้องทําซ้ำโดยมีค่าต่างกันเมื่อเพิ่มลงในคําสั่ง build กลุ่มแฟล็กจะวนซ้ำตัวแปรประเภท 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}"],
        ),
    ],
)

การขยายแบบมีเงื่อนไข

กลุ่ม Flag รองรับการขยายแบบมีเงื่อนไขตามการมีตัวแปรหรือฟิลด์ใดฟิลด์หนึ่งโดยใช้แอตทริบิวต์ 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	คอมไพล์	เอาต์พุตที่ประมวลผลล่วงหน้า ใช้กับการดำเนินการ compile ที่ประมวลผลล่วงหน้าเฉพาะไฟล์ต้นฉบับเท่านั้น โดยปกติเมื่อใช้ --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)
stripopts	แถบ	ลำดับของ 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ฟีเจอร์CROSSTOOL โดยไม่ได้กรองตาม nocoptsแอตทริบิวต์ของกฎ
sysroot		sysroot
runtime_library_search_directories	ลิงก์	รายการในเส้นทางการค้นหาที่รันไทม์ของ Linker (โดยปกติจะตั้งค่าด้วยแฟล็ก -rpath)
library_search_directories	ลิงก์	รายการในเส้นทางการค้นหาของ Linker (โดยปกติจะตั้งค่าด้วย แฟล็ก -L)
libraries_to_link	ลิงก์	Flags ที่ระบุไฟล์เพื่อลิงก์เป็นอินพุตในการเรียกใช้ Linker
def_file_path	ลิงก์	ตำแหน่งของไฟล์ def ที่ใช้ใน Windows กับ MSVC
linker_param_file	ลิงก์	ตำแหน่งของไฟล์พารามิเตอร์ลิงก์ที่ Bazel สร้างขึ้นเพื่อ แก้ไขปัญหาความยาวของบรรทัดคำสั่ง
output_execpath	ลิงก์	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	ลิงก์	ตัวแปรบิลด์ที่ให้เส้นทาง Linkstamp
force_pic	ลิงก์	การมีตัวแปรนี้บ่งชี้ว่าควรสร้างโค้ด PIC/PIE (ส่งตัวเลือก Bazel `--force_pic`)
strip_debug_symbols	ลิงก์	การมีอยู่ของตัวแปรนี้บ่งบอกว่าควรนำสัญลักษณ์การแก้ไขข้อบกพร่องออก
is_cc_test	ลิงก์	เป็นจริงเมื่อการดำเนินการปัจจุบันเป็นการดำเนินการลิงก์ cc_test มิเช่นนั้นจะเป็นเท็จ
is_using_fission	คอมไพล์ ลิงก์	การมีตัวแปรนี้บ่งชี้ว่ามีการเปิดใช้งานฟิชชัน (ข้อมูลการแก้ไขข้อบกพร่องต่อออบเจ็กต์) ข้อมูลการแก้ไขข้อบกพร่องจะอยู่ในไฟล์ .dwo แทนไฟล์ .o และคอมไพเลอร์และลิงเกอร์ต้องทราบเรื่องนี้
fdo_instrument_path	คอมไพล์ ลิงก์	เส้นทางไปยังไดเรกทอรีที่จัดเก็บโปรไฟล์การวัดผล FDO
fdo_profile_path	คอมไพล์	เส้นทางไปยังโปรไฟล์ FDO
fdo_prefetch_hints_path	คอมไพล์	เส้นทางไปยังโปรไฟล์การดึงข้อมูลล่วงหน้าของแคช
cs_fdo_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 เป็น False (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++ เมื่อมีอยู่ ดูรายการฟีเจอร์ทั้งหมดได้ที่ด้านล่าง
shorten_virtual_includes	หากเปิดใช้ ระบบจะลิงก์ไฟล์ส่วนหัวที่รวมเสมือนไว้ใน bin/_virtual_includes/<hash of target path> แทน bin/<target package path>/_virtual_includes/<target name> มีประโยชน์ใน Windows เพื่อหลีกเลี่ยงปัญหาเส้นทางยาวกับ MSVC

ตรรกะการแก้ไขฟีเจอร์เดิม

Bazel จะทำการเปลี่ยนแปลงต่อไปนี้กับฟีเจอร์ของ Toolchain เพื่อให้เข้ากันได้แบบย้อนหลัง

• ย้ายฟีเจอร์ 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 (หากไม่มี) ที่ด้านล่างของ Toolchain
• เพิ่มฟีเจอร์ user_compile_flags (หากไม่มี) ที่ด้านล่างของ Toolchain
• เพิ่มฟีเจอร์ sysroot (หากไม่มี) ที่ด้านล่างของ Toolchain
• เพิ่มฟีเจอร์ unfiltered_compile_flags (หากไม่มี) ที่ด้านล่างของ Toolchain
• เพิ่มฟีเจอร์ linker_param_file (หากไม่มี) ที่ด้านล่างของ Toolchain
• เพิ่มฟีเจอร์ compiler_input_flags (หากไม่มี) ที่ด้านล่างของ Toolchain
• เพิ่มฟีเจอร์ compiler_output_flags (หากไม่มี) ที่ด้านล่างของ Toolchain

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