ไฟล์ BUILD

ส่วนก่อนหน้าได้อธิบายแพ็กเกจ เป้าหมาย และป้ายกำกับ รวมถึงกราฟทรัพยากร Dependency ของบิลด์ในเชิงนามธรรม ส่วนนี้จะอธิบายไวยากรณ์ที่เฉพาะเจาะจง ที่ใช้ในการกำหนดแพ็กเกจ

ตามคำจำกัดความ ทุกแพ็กเกจจะมีไฟล์ BUILD ซึ่งเป็นโปรแกรมสั้นๆ

BUILD จะได้รับการประเมินโดยใช้ภาษาแบบคำสั่ง Starlark

ระบบจะตีความว่าเป็นรายการคำสั่งตามลำดับ

โดยทั่วไปแล้วลำดับมีความสำคัญ คุณต้องกำหนดตัวแปรก่อนที่จะใช้ตัวแปรนั้นๆ เป็นต้น อย่างไรก็ตาม ไฟล์ BUILD ส่วนใหญ่ประกอบด้วยการประกาศกฎการสร้างเท่านั้น และลำดับที่สัมพันธ์กันของคำสั่งเหล่านี้ไม่สำคัญ สิ่งที่สำคัญคือกฎใดที่ประกาศ และมีค่าใดบ้างเมื่อการประเมินแพ็กเกจเสร็จสมบูรณ์

เมื่อฟังก์ชันกฎบิลด์ เช่น cc_library ทำงาน ฟังก์ชันจะสร้างเป้าหมายใหม่ในกราฟ คุณอ้างอิงเป้าหมายนี้ได้ในภายหลังโดยใช้ป้ายกำกับ

ในไฟล์ BUILD แบบง่าย คุณสามารถจัดลำดับการประกาศกฎใหม่ได้อย่างอิสระโดยไม่ต้องเปลี่ยนลักษณะการทำงาน

เพื่อส่งเสริมการแยกโค้ดและข้อมูลอย่างชัดเจน ไฟล์ BUILD ต้องไม่มีคำจำกัดความฟังก์ชัน คำสั่ง for หรือคำสั่ง if (แต่จะอนุญาตให้ใช้ List Comprehension และนิพจน์ if) คุณสามารถประกาศฟังก์ชันในไฟล์ .bzl แทนได้ นอกจากนี้ ระบบไม่อนุญาตให้ใช้อาร์กิวเมนต์ *args และ **kwargs ในไฟล์ BUILD แต่ให้แสดงอาร์กิวเมนต์ทั้งหมดอย่างชัดเจนแทน

ที่สำคัญคือโปรแกรมใน Starlark จะดำเนินการ I/O โดยพลการไม่ได้ ค่าคงที่นี้ ทำให้การตีความไฟล์ BUILD เป็นแบบปิดสนิท ซึ่งขึ้นอยู่กับชุดอินพุตที่ทราบเท่านั้น ซึ่งจำเป็นอย่างยิ่งในการตรวจสอบว่าบิลด์สามารถทำซ้ำได้ ดูรายละเอียดเพิ่มเติมได้ที่Hermeticity

BUILD ควรเขียนไฟล์โดยใช้อักขระ ASCII เท่านั้น แม้ว่าในทางเทคนิคแล้วระบบจะตีความโดยใช้ชุดอักขระ Latin-1 ก็ตาม

เนื่องจากต้องอัปเดตไฟล์ 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

  ในบางภาษา กฎดังกล่าวจะสร้างไดเรกทอรี Runfiles ซึ่งมีไฟล์ทั้งหมดที่ระบุไว้ในแอตทริบิวต์ data ที่เป็นของกฎ หรือกฎใดๆ ในการปิดการเปลี่ยนผ่านของ Dependency ชุดไฟล์นี้จะรวบรวมไว้ในที่เดียวเพื่อให้ง่ายต่อการนำไปใช้ในการผลิต

• *_test เป็นกฎเฉพาะของกฎ *_binary ที่ใช้สำหรับการทดสอบอัตโนมัติ การทดสอบเป็นเพียงโปรแกรมที่แสดงผลเป็น 0 เมื่อสำเร็จ

  เช่นเดียวกับไบนารี การทดสอบก็มีโครงสร้างไฟล์ที่ใช้ในการรัน และไฟล์ที่อยู่ใต้โครงสร้างดังกล่าวเป็นไฟล์เดียวที่การทดสอบสามารถเปิดได้อย่างถูกต้องตามกฎหมายในเวลาที่รัน เช่น โปรแกรม cc_test(name='x', data=['//foo:bar']) อาจเปิดและอ่าน $TEST_SRCDIR/workspace/foo/bar ในระหว่างการดำเนินการ (ภาษาโปรแกรมแต่ละภาษาจะมีฟังก์ชันยูทิลิตีของตัวเองสำหรับ การเข้าถึงค่าของ $TEST_SRCDIR แต่ทั้งหมด เทียบเท่ากับการใช้ตัวแปรสภาพแวดล้อมโดยตรง) การไม่ปฏิบัติตามกฎจะทำให้การทดสอบล้มเหลวเมื่อมีการ เรียกใช้ในโฮสต์การทดสอบระยะไกล

• *_library ระบุโมดูลที่คอมไพล์แยกกันในภาษาโปรแกรมที่กำหนด ไลบรารีสามารถขึ้นอยู่กับไลบรารีอื่นๆ และไบนารีและการทดสอบสามารถขึ้นอยู่กับไลบรารีได้ โดยมีลักษณะการทำงานของการคอมไพล์แยกกันตามที่คาดไว้