ส่วนก่อนหน้าได้อธิบายแพ็กเกจ เป้าหมาย และป้ายกำกับ รวมถึงกราฟการขึ้นต่อกันของบิลด์ในเชิงนามธรรม ส่วนนี้จะอธิบายไวยากรณ์ที่ชัดเจน ซึ่งใช้ในการกำหนดแพ็กเกจ
ตามคำจำกัดความ ทุกแพ็กเกจจะมีไฟล์ BUILD ซึ่งเป็นโปรแกรมสั้นๆ
BUILD จะได้รับการประเมินโดยใช้ภาษาแบบคำสั่ง Starlark
โดยจะตีความเป็นการดำเนินการตามคำสั่งตามลำดับ
โดยทั่วไปแล้วลำดับมีความสำคัญ กล่าวคือ ต้องกำหนดตัวแปรก่อนจึงจะใช้ได้ เป็นต้น อย่างไรก็ตาม ไฟล์ BUILD ส่วนใหญ่ประกอบด้วยการประกาศกฎการสร้างเท่านั้น และลำดับที่สัมพันธ์กันของคำสั่งเหล่านี้ไม่สำคัญ สิ่งที่สำคัญคือกฎใดที่ประกาศ และมีค่าใดบ้างเมื่อการประเมินแพ็กเกจเสร็จสมบูรณ์
เมื่อฟังก์ชันกฎบิลด์ เช่น cc_library ทำงาน ฟังก์ชันจะสร้างเป้าหมายใหม่ในกราฟ คุณอ้างอิงเป้าหมายนี้ได้ในภายหลังโดยใช้ป้ายกำกับ
ในไฟล์ BUILD แบบง่าย คุณสามารถจัดลำดับการประกาศกฎใหม่ได้อย่างอิสระโดยไม่ต้องเปลี่ยนลักษณะการทำงาน
เพื่อส่งเสริมการแยกโค้ดและข้อมูลอย่างชัดเจน ไฟล์ BUILD ต้องไม่มีคำจำกัดความฟังก์ชัน คำสั่ง for หรือคำสั่ง if (แต่จะอนุญาตให้ใช้การทำความเข้าใจรายการและนิพจน์ if) คุณสามารถประกาศฟังก์ชันในไฟล์ .bzl แทนได้ นอกจากนี้ ระบบไม่อนุญาตให้ใช้อาร์กิวเมนต์ *args และ **kwargs ในไฟล์ BUILD แต่ให้แสดงอาร์กิวเมนต์ทั้งหมดอย่างชัดเจนแทน
ที่สำคัญคือโปรแกรมใน Starlark จะดำเนินการ I/O โดยพลการไม่ได้ ค่าคงที่นี้
ทำให้การตีความไฟล์ BUILD เป็นแบบปิดสนิท ซึ่งขึ้นอยู่กับชุดอินพุตที่ทราบเท่านั้น
ซึ่งจำเป็นอย่างยิ่งในการตรวจสอบว่าบิลด์สามารถทำซ้ำได้
ดูรายละเอียดเพิ่มเติมได้ที่Hermeticity
เนื่องจากต้องอัปเดตไฟล์ BUILD ทุกครั้งที่มีการเปลี่ยนแปลงการขึ้นต่อกันของโค้ดพื้นฐาน โดยปกติแล้วจึงมีหลายคนในทีมที่ดูแลไฟล์เหล่านี้ ผู้เขียนไฟล์ BUILD ควรแสดงความคิดเห็นอย่างอิสระเพื่อบันทึกบทบาท
ของเป้าหมายการสร้างแต่ละรายการ ไม่ว่าจะตั้งใจให้ใช้แบบสาธารณะหรือไม่ก็ตาม และเพื่อ
บันทึกบทบาทของแพ็กเกจเอง
การโหลดส่วนขยาย
ส่วนขยาย Bazel คือไฟล์ที่ลงท้ายด้วย .bzl ใช้คำสั่ง load เพื่อนำเข้าสัญลักษณ์จากส่วนขยาย
load("//foo/bar:file.bzl", "some_library")
โค้ดนี้จะโหลดไฟล์ foo/bar/file.bzl และเพิ่มสัญลักษณ์ some_library
ลงในสภาพแวดล้อม ซึ่งใช้เพื่อโหลดกฎ ฟังก์ชัน หรือค่าคงที่ใหม่ได้
(เช่น สตริงหรือรายการ) คุณสามารถนำเข้าสัญลักษณ์หลายรายการได้โดยใช้
อาร์กิวเมนต์เพิ่มเติมในการเรียกใช้ load อาร์กิวเมนต์ต้องเป็นค่าสตริง
(ไม่มีตัวแปร) และคำสั่ง load ต้องปรากฏที่ระดับบนสุด โดยจะอยู่ในเนื้อหาของฟังก์ชันไม่ได้
อาร์กิวเมนต์แรกของ load คือป้ายกำกับที่ระบุไฟล์
.bzl หากเป็นป้ายกำกับแบบสัมพัทธ์ ระบบจะแก้ไขป้ายกำกับดังกล่าวโดยอ้างอิงถึง
แพ็กเกจ (ไม่ใช่ไดเรกทอรี) ที่มีไฟล์ bzl ปัจจุบัน ป้ายกำกับแบบสัมพัทธ์ในคำสั่ง load ควรใช้ : นำหน้า
load ยังรองรับชื่อแทนด้วย คุณจึงกำหนดชื่ออื่นให้กับสัญลักษณ์ที่นำเข้าได้
load("//foo/bar:file.bzl", library_alias = "some_library")
คุณกำหนดชื่อแทนได้หลายรายการภายในคำสั่ง load เดียว นอกจากนี้ รายการอาร์กิวเมนต์ยังสามารถมีทั้งชื่อแทนและชื่อสัญลักษณ์ปกติได้ ตัวอย่างต่อไปนี้
เป็นตัวอย่างที่ถูกต้องตามกฎหมาย (โปรดทราบว่าเมื่อใดควรใช้เครื่องหมายคำพูด)
load(":my_rules.bzl", "some_rule", nice_alias = "some_other_rule")
ในไฟล์ .bzl ระบบจะไม่ส่งออกสัญลักษณ์ที่ขึ้นต้นด้วย _ และโหลดจากไฟล์อื่นไม่ได้
คุณใช้ระดับการมองเห็นของโหลดเพื่อจำกัด
ผู้ที่โหลดไฟล์ .bzl ได้
ประเภทของกฎการสร้าง
กฎการสร้างส่วนใหญ่จะอยู่ในตระกูล โดยจัดกลุ่มตามภาษา เช่น cc_binary, cc_library
และ cc_test คือกฎการสร้างสำหรับไบนารี C++
ไลบรารี และการทดสอบ ตามลำดับ ภาษาอื่นๆ จะใช้รูปแบบการตั้งชื่อเดียวกัน
โดยมีคำนำหน้าที่แตกต่างกัน เช่น java_* สำหรับ
Java ฟังก์ชันบางอย่างเหล่านี้มีอยู่ในเอกสารสารานุกรมการสร้าง แต่ทุกคนก็สร้างกฎใหม่ได้
*_binaryกฎจะสร้างโปรแกรมที่เรียกใช้งานได้ในภาษาที่กำหนด หลังจาก บิลด์แล้ว ไฟล์ที่เรียกใช้งานได้จะอยู่ในทรีเอาต์พุตไบนารีของเครื่องมือบิลด์ ที่ชื่อที่สอดคล้องกับป้ายกำกับของกฎ ดังนั้น//my:programจะปรากฏที่ (เช่น)$(BINDIR)/my/programในบางภาษา กฎดังกล่าวจะสร้างไดเรกทอรีไฟล์ที่เรียกใช้ได้ด้วย ซึ่งมีไฟล์ทั้งหมดที่ระบุไว้ในแอตทริบิวต์
dataที่เป็นของกฎ หรือกฎใดๆ ในการปิดการพึ่งพาอาศัยกันแบบทรานซิทีฟ ชุดไฟล์นี้จะรวบรวมไว้ใน ที่เดียวเพื่อให้ง่ายต่อการนำไปใช้ในการผลิต*_testเป็นการเฉพาะเจาะจงของ*_binaryใช้สำหรับการทดสอบอัตโนมัติ การทดสอบเป็นเพียงโปรแกรมที่แสดงผลเป็น 0 เมื่อสำเร็จเช่นเดียวกับไบนารี การทดสอบก็มีโครงสร้าง runfiles และไฟล์ ที่อยู่ใต้โครงสร้างนี้เป็นไฟล์เดียวที่การทดสอบอาจเปิดได้อย่างถูกต้อง ในรันไทม์ เช่น โปรแกรม
cc_test(name='x', data=['//foo:bar'])อาจเปิดและอ่าน$TEST_SRCDIR/workspace/foo/barในระหว่างการดำเนินการ (ภาษาโปรแกรมแต่ละภาษาจะมีฟังก์ชันยูทิลิตีของตัวเองสำหรับ การเข้าถึงค่าของ$TEST_SRCDIRแต่ทั้งหมด เทียบเท่ากับการใช้ตัวแปรสภาพแวดล้อมโดยตรง) การไม่ปฏิบัติตามกฎจะทำให้การทดสอบล้มเหลวเมื่อมีการ เรียกใช้ในโฮสต์การทดสอบระยะไกล*_libraryระบุโมดูลที่คอมไพล์แยกกันในภาษาโปรแกรมที่กำหนด ไลบรารีสามารถขึ้นอยู่กับไลบรารีอื่นๆ และไบนารีและการทดสอบสามารถขึ้นอยู่กับไลบรารีได้ โดยมีลักษณะการทำงานของการคอมไพล์แยกกันตามที่คาดไว้
| ป้ายกำกับ | Dependencies |
การเข้ารหัสไฟล์
ไฟล์ BUILD และ .bzl ควรเข้ารหัสในรูปแบบ UTF-8 ซึ่ง ASCII เป็นชุดย่อยที่ถูกต้อง
ปัจจุบันระบบอนุญาตให้ใช้ลำดับไบต์ที่กำหนดเอง แต่ในอนาคตอาจหยุดรองรับ