ไฟล์ BUILD

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

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

ระบบจะประเมินไฟล์ BUILD โดยใช้ภาษาบังคับ ซึ่งก็คือ Starlark

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

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

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

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

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

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

เนื่องจากไฟล์ 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 แต่ทุกคนสามารถสร้างกฎใหม่ได้

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

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

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

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

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

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

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