ภาพรวม
เมื่อต้องการเรียกใช้คอมไพเลอร์ด้วยตัวเลือกที่เหมาะสม 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 มีหน้าที่ดังต่อไปนี้
ผู้ใช้ระบุเป้าหมาย
cc_toolchain_suite
ในไฟล์BUILD
และชี้ Bazel ไปยังเป้าหมายโดยใช้ตัวเลือก--crosstool_top
เป้าหมาย
cc_toolchain_suite
อ้างอิง Toolchain หลายเชน ค่าของ Flag--cpu
และ--compiler
จะเป็นตัวกำหนดว่าจะเลือก Toolchain ใดบ้าง ซึ่งอาจอิงจากค่า Flag--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
ฟีเจอร์
ฟีเจอร์เป็นเอนทิตีที่ต้องแฟล็กบรรทัดคำสั่ง การดำเนินการ ข้อจำกัดในสภาพแวดล้อมการดำเนินการ หรือการปรับเปลี่ยนทรัพยากร 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
และตัวแปรอื่นๆ
ความสัมพันธ์ของฟีเจอร์
โดยทั่วไปแล้วทรัพยากร Dependency จะจัดการด้วย Bazel โดยตรง ซึ่งจะบังคับใช้ข้อกำหนดและจัดการความขัดแย้งตามลักษณะของฟีเจอร์ที่กำหนดไว้ในบิลด์ ข้อมูลจำเพาะของ Toolchain ทำให้มีข้อจํากัดที่ละเอียดยิ่งขึ้นสำหรับใช้ในกฎ Starlark ที่ควบคุมการรองรับและการขยายฟีเจอร์โดยตรง ได้แก่
ข้อจำกัด | คำอธิบาย |
requires = [ feature_set (features = [ 'feature-name-1', 'feature-name-2' ]), ] |
ระดับฟีเจอร์ ระบบจะรองรับฟีเจอร์นี้ก็ต่อเมื่อเปิดใช้ฟีเจอร์ที่จำเป็นที่ระบุไว้เท่านั้น เช่น เมื่อฟีเจอร์หนึ่งได้รับการสนับสนุนในบางโหมดบิลด์เท่านั้น (opt , dbg หรือ fastbuild ) หาก "ต้องการ" มี "feature_set" หลายรายการ ระบบจะรองรับฟีเจอร์นี้หากมีคุณสมบัติตรงตาม "feature_set" ใดๆ (เมื่อเปิดใช้ฟีเจอร์ที่ระบุทั้งหมด)
|
implies = ['feature'] |
ระดับฟีเจอร์ ฟีเจอร์นี้บอกเป็นนัยถึงฟีเจอร์ที่ระบุ การเปิดใช้ฟีเจอร์จะเป็นการเปิดใช้ฟีเจอร์ทั้งหมดที่กล่าวโดยนัยด้วย (กล่าวคือ ทำงานซ้ำๆ) นอกจากนี้ คุณยังแยกฟังก์ชันกลุ่มย่อยทั่วไปออกจากชุดฟีเจอร์ได้ด้วย เช่น ส่วนประกอบทั่วไปของเจลล้างทำความสะอาด ปิดใช้ฟีเจอร์โดยนัยไม่ได้ |
provides = ['feature'] |
ระดับฟีเจอร์ ระบุว่าฟีเจอร์นี้เป็นหนึ่งในฟีเจอร์ทางเลือกที่ใช้ไม่ได้เหมือนกันหลายรายการ เช่น เจลล้างทำความสะอาดทั้งหมดอาจระบุ ซึ่งจะช่วยปรับปรุงการจัดการข้อผิดพลาดด้วยการแสดงทางเลือกต่างๆ หากผู้ใช้ขอฟีเจอร์ที่เหมือนกัน 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
มีการดำเนินการที่มี Flag และเครื่องมือที่เชื่อมโยงกับผู้ให้บริการ เช่น 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
เดียวกันภายใน Toolchain เดียวกันไม่ได้ การดำเนินการนี้จะป้องกันความกำกวมในเส้นทางเครื่องมือและบังคับใช้เจตนาที่อยู่เบื้องหลัง 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_group (
flags = ["%{output_execpath}"],
)
ในกรณีนี้ เนื้อหาของแฟล็กจะแทนที่ด้วยเส้นทางไฟล์เอาต์พุตของการดำเนินการ
กลุ่มแฟล็กจะขยายออกเป็นคำสั่งบิลด์ตามลําดับที่ปรากฏในรายการ โดยเริ่มจากบนลงล่างและซ้ายไปขวา
สำหรับแฟล็กที่ต้องทำซ้ำด้วยค่าอื่นเมื่อเพิ่มลงในคำสั่งบิลด์ กลุ่มแฟล็กจะทำซ้ำตัวแปรประเภท list
ได้ ตัวอย่างเช่น ตัวแปร include_path
ของประเภท list
:
flag_group (
iterate_over = "include_paths",
flags = ["-I%{include_paths}"],
)
ขยายเป็น -I<path>
สำหรับองค์ประกอบเส้นทางแต่ละรายการในรายการ include_paths
ธงทั้งหมด (หรือ 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"],
),
],
),
],
)
ข้อมูลอ้างอิง CcToolchainConfigInfo
ส่วนนี้จะแสดงข้อมูลอ้างอิงของตัวแปรบิลด์ ฟีเจอร์ และข้อมูลอื่นๆ ที่จำเป็นในการกำหนดค่ากฎ C++ ให้สำเร็จ
ตัวแปรบิลด์ CcToolchainConfigInfo
ต่อไปนี้เป็นการอ้างอิงตัวแปรบิลด์ CcToolchainConfigInfo
ตัวแปร | การดำเนินการ | คำอธิบาย |
source_file
|
compile | ไฟล์ต้นฉบับที่จะคอมไพล์ |
input_file
|
แถบ | อาร์ติแฟกต์ที่จะตัด |
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
|
แถบ | ลำดับของ 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 | ลำดับการแจ้งจากช่อง 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
|
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 เพื่อลิงก์กับออบเจ็กต์โดยตรงแทน ซึ่งช่วยให้สร้างบิลด์ได้เร็วขึ้นเนื่องจาก 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
ไปที่ด้านบนสุดของ 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
เพื่อทำให้เชนเครื่องมือแบบสแตนด์อโลนมากขึ้น