ไฟล์ BUILD

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

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

ระบบจะประเมินไฟล์ BUILD โดยใช้ภาษาที่จำเป็นต้องทำตามขั้นตอนที่กำหนดไว้ (Imperative Language) อย่าง Starlark

โดยจะตีความไฟล์เหล่านี้เป็นรายการคำสั่งตามลำดับ

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

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

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

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

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

เนื่องจากต้องอัปเดตไฟล์ BUILD ทุกครั้งที่ทรัพยากร Dependency ของโค้ดพื้นฐานมีการเปลี่ยนแปลง โดยปกติแล้วจะมีผู้ดูแลไฟล์ 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 ฟังก์ชันบางอย่างเหล่านี้มีอธิบายไว้ใน Build Encyclopedia แต่ทุกคนสามารถสร้างกฎใหม่ได้

• กฎ *_binary จะสร้างโปรแกรมที่เรียกใช้งานได้ในภาษาที่กำหนด หลังจากบิลด์ โปรแกรมที่เรียกใช้งานได้จะอยู่ในแผนผังเอาต์พุตไบนารีของเครื่องมือบิลด์ที่ชื่อที่สอดคล้องกับป้ายกำกับของกฎ ดังนั้น //my:program จะปรากฏที่ (เช่น) $(BINDIR)/my/program

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

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

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

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

การเข้ารหัสไฟล์

ไฟล์ BUILD และ .bzl ควรเข้ารหัสเป็น UTF-8 ซึ่ง ASCII เป็นชุดย่อยที่ใช้ได้ ปัจจุบันระบบอนุญาตให้ใช้ลำดับไบต์ที่กำหนดเอง แต่ในอนาคตอาจหยุดรองรับ