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

ภาพรวม

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

บาเซลจำเป็นต้องทราบสิ่งต่อไปนี้

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

หากคอมไพเลอร์รองรับสถาปัตยกรรมหลายรายการ 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 ต้องมีข้อมูลต่อไปนี้

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

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

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

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

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

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

  2. เป้าหมาย cc_toolchain_suite อ้างอิง Toolchain หลายรายการ ค่าของแฟล็ก --cpu และ --compiler จะกําหนด Toolchain ที่เลือกไว้จะขึ้นอยู่กับค่าแฟล็ก --cpu เท่านั้น หรืออิงตามค่าร่วม --cpu | --compiler ขั้นตอนการคัดเลือกมีดังนี้

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

    • หากไม่ได้ระบุตัวเลือก --compiler บาเซลจะเลือกรายการที่เกี่ยวข้องจากแอตทริบิวต์ 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 จะมีรายการฟีเจอร์โดยที่แต่ละฟีเจอร์ประกอบด้วยกลุ่มแฟล็ก 1 กลุ่มขึ้นไป แต่ละรายการเป็นตัวกำหนดรายการแฟล็กที่ใช้กับการดำเนินการของ Bazel ที่เจาะจง

ฟีเจอร์หนึ่งได้รับการระบุตามชื่อ ซึ่งอนุญาตให้แยกการกำหนดค่ากฎ Starlark ออกจากรุ่นของ Bazel ได้โดยสมบูรณ์ กล่าวอีกนัยหนึ่งคือ รุ่น Bazel ไม่ส่งผลต่อลักษณะการทำงานของการกำหนดค่า CcToolchainConfigInfo ตราบใดที่การกำหนดค่าเหล่านั้นไม่จำเป็นต้องใช้ฟีเจอร์ใหม่

ฟีเจอร์จะเปิดใช้งานด้วยวิธีใดวิธีหนึ่งต่อไปนี้

  • ตั้งค่าฟิลด์ enabled ของจุดสนใจเป็น true
  • Bazel หรือเจ้าของกฎเปิดใช้อย่างชัดแจ้ง
  • และผู้ใช้เปิดใช้ผ่านตัวเลือก Bazel --feature หรือแอตทริบิวต์กฎ 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']

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

รวมถึงให้ความสามารถในการแยกชุดย่อยฟังก์ชันการทำงานทั่วไปออกจากชุดฟีเจอร์ด้วย เช่น ชิ้นส่วนทั่วไปของตัวทำความสะอาด ปิดใช้ฟีเจอร์โดยนัยไม่ได้

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 จะมีการกำหนดแฟล็กให้กับการดำเนินการแต่ละรายการ โดยการเชื่อมโยงเข้ากับฟีเจอร์

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

การทำงานของเครื่องมือประกอบ

การดำเนินการ คำอธิบาย
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 โดยระบุเครื่องมือ (ไบนารี) ที่จะเรียกใช้ระหว่างการทำงานและชุด Flag ที่กำหนดโดยฟีเจอร์ต่างๆ แฟล็กเหล่านี้มีข้อจำกัดกับการดำเนินการของการดำเนินการ

ตัวสร้าง 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() จะใช้ในพารามิเตอร์ต่อไปนี้

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

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

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

สามารถใช้ฟีเจอร์และการดำเนินการร่วมกันเพื่อนำการทำงานของ Bazel ไปใช้ ด้วยอรรถศาสตร์ข้ามแพลตฟอร์มที่หลากหลาย เช่น การสร้างสัญลักษณ์การแก้ไขข้อบกพร่องใน macOS จําเป็นต้องมีการสร้างสัญลักษณ์ในการคอมไพล์ จากนั้นเรียกใช้เครื่องมือเฉพาะทางระหว่างการดำเนินการลิงก์เพื่อสร้างที่เก็บถาวรของ dsym ที่บีบอัด จากนั้นจึงแตกไฟล์ที่เก็บถาวรนั้นเพื่อสร้าง Bundle แอปพลิเคชันและไฟล์ .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 จะขยายเป็นหน่วยหนึ่ง เช่น

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 compile ไฟล์ต้นฉบับที่คอมไพล์
input_file Strip อาร์ติแฟกต์เพื่อตัดข้อมูล
output_file compile เอาต์พุตการคอมไพล์
output_assembly_file compile ไฟล์แอสเซมบลีที่ส่งออกแล้ว ใช้เฉพาะเมื่อการดำเนินการ compile ปล่อยข้อความแอสเซมบลี ซึ่งโดยปกติจะใช้แฟล็ก --save_temps เนื้อหาจะเหมือนกับของ output_file
output_preprocess_file compile ผลลัพธ์ที่ประมวลผลล่วงหน้า มีผลกับการดำเนินการคอมไพล์ที่ประมวลผลไฟล์ต้นฉบับล่วงหน้าเท่านั้น โดยทั่วไปเมื่อใช้แฟล็ก --save_temps เนื้อหาจะเหมือนกับของ output_file
includes compile ลำดับของไฟล์ที่คอมไพเลอร์ต้องรวมอยู่ในแหล่งที่มาที่คอมไพล์อย่างไม่มีเงื่อนไข
include_paths compile ไดเรกทอรีลำดับที่คอมไพเลอร์ค้นหาส่วนหัวที่รวมโดยใช้ #include<foo.h> และ #include "foo.h"
quote_include_paths compile ลำดับของ -iquote ประกอบด้วย - ไดเรกทอรีที่คอมไพเลอร์ค้นหาส่วนหัวที่รวมโดยใช้ #include "foo.h"
system_include_paths compile ลำดับของ -isystem ประกอบด้วย - ไดเรกทอรีที่คอมไพเลอร์ค้นหาส่วนหัวที่รวมโดยใช้ #include <foo.h>
dependency_file compile ไฟล์ทรัพยากร Dependency .d ที่คอมไพเลอร์สร้างขึ้น
preprocessor_defines compile ลำดับของ defines เช่น --DDEBUG
pic compile คอมไพล์เอาต์พุตเป็นโค้ดที่ไม่ขึ้นกับตำแหน่ง
gcov_gcno_file compile ไฟล์การครอบคลุมของ gcov
per_object_debug_info_file compile ไฟล์ข้อมูลการแก้ไขข้อบกพร่องต่อออบเจ็กต์ (.dwp)
stripotps Strip ลำดับของ stripopts
legacy_compile_flags compile ลำดับแฟล็กจากช่อง CROSSTOOL เดิม เช่น compiler_flag, optional_compiler_flag, cxx_flag และ optional_cxx_flag
user_compile_flags compile ลำดับของแฟล็กจากแอตทริบิวต์กฎ copt หรือแฟล็ก --copt, --cxxopt และ --conlyopt
unfiltered_compile_flags compile ลำดับการแจ้งว่าไม่เหมาะสมจากช่อง CROSSTOOL เดิมของ unfiltered_cxx_flag หรือฟีเจอร์ 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 ลิงก์ Execpath ของเอาต์พุตของ Linker
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 ลิงก์ แฟล็ก Linker ที่มาจากแอตทริบิวต์ --linkopt หรือ linkopts
symbol_counts_output ลิงก์ เส้นทางที่จะเขียนจำนวนสัญลักษณ์
linkstamp_paths ลิงก์ ตัวแปรบิลด์ที่ให้เส้นทาง Linktamp
force_pic ลิงก์ การมีอยู่ของตัวแปรนี้บ่งชี้ว่าควรสร้างโค้ด PIC/PIE (ส่งผ่านตัวเลือกแบบเบเซล "--force_pic")
strip_debug_symbols ลิงก์ การมีอยู่ของตัวแปรนี้บ่งชี้ว่าควรนำสัญลักษณ์การแก้ไขข้อบกพร่องออก
is_cc_test ลิงก์ ความจริงเมื่อการดำเนินการปัจจุบันเป็นการดำเนินการลิงก์ cc_test หากไม่เป็น "เท็จ"
is_using_fission คอมไพล์, ลิงก์ การมีอยู่ของตัวแปรนี้บ่งบอกว่ามีการเปิดใช้งานฟิชชัน (ข้อมูลการแก้ไขข้อบกพร่องต่อออบเจ็กต์) ข้อมูลการแก้ไขข้อบกพร่องจะอยู่ใน .dwo ไฟล์แทนที่จะเป็น .o ไฟล์ ซึ่งคอมไพเลอร์และ Linker จำเป็นต้องทราบข้อมูลนี้
fdo_instrument_path คอมไพล์, ลิงก์ เส้นทางไปยังไดเรกทอรีที่เก็บโปรไฟล์การวัดคุม FDO
fdo_profile_path compile เส้นทางไปยังโปรไฟล์ FDO
fdo_prefetch_hints_path compile เส้นทางไปยังโปรไฟล์การดึงข้อมูลแคชล่วงหน้า
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 นำการเปลี่ยนแปลงต่อไปนี้ไปใช้กับฟีเจอร์ของ 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 (หากไม่มี) ที่ด้านบนของเครื่องมือเชน
  • เพิ่มฟีเจอร์ symbol_counts (หากไม่มี) ที่ด้านบนของเครื่องมือเชน
  • เพิ่มฟีเจอร์ 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 เพื่อทำให้เชนเครื่องมือทำงานได้แบบสแตนด์อโลนมากขึ้น