ภาพรวม
หากต้องการเรียกใช้คอมไพเลอร์ด้วยตัวเลือกที่เหมาะสม 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 ที่จะจัดส่งไปยังแซนด์บ็อกซ์
การเลือกเชนเครื่องมือ
ตรรกะการเลือกเครื่องมือเชนมีการทำงานดังนี้
ผู้ใช้ระบุเป้าหมาย
cc_toolchain_suite
ในไฟล์BUILD
และชี้ Bazel ไปยังเป้าหมายโดยใช้ ตัวเลือก--crosstool_top
เป้าหมาย
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'] |
ระดับฟีเจอร์ ระบุว่าฟีเจอร์นี้เป็นหนึ่งในฟีเจอร์ทางเลือกที่ใช้พร้อมกันไม่ได้หลายรายการ เช่น เจลล้างมือทั้งหมดระบุ การดำเนินการนี้จะช่วยปรับปรุงการจัดการข้อผิดพลาดด้วยการแสดงตัวเลือกทางเลือกหากผู้ใช้ขอฟีเจอร์ที่ใช้พร้อมกันไม่ได้อย่างน้อย 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
เพื่อทำให้เชนเครื่องมือทำงานได้แบบสแตนด์อโลนมากขึ้น