ไฟล์ BUILD

รายงานปัญหา ดูแหล่งที่มา

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

ป้ายกำกับ การขึ้นต่อกัน