ป้ายกำกับ

ป้ายกำกับคือตัวระบุสำหรับเป้าหมาย ป้ายกำกับทั่วไปในรูปแบบ Canonical แบบเต็ม จะมีลักษณะดังนี้

@@myrepo//my/app/main:app_binary

ส่วนแรกของป้ายกำกับคือชื่อที่เก็บ @@myrepo ไวยากรณ์ @ double- แสดงว่านี่คือที่เก็บข้อมูล Canonical name ซึ่งไม่ซ้ำกันภายใน พื้นที่ทำงาน ป้ายกำกับที่มีชื่อที่เก็บ Canonical จะระบุเป้าหมายได้อย่างชัดเจน ไม่ว่าป้ายกำกับจะปรากฏในบริบทใดก็ตาม

โดยส่วนใหญ่ Canonical Name ของที่เก็บมักจะเป็นสตริงที่ซับซ้อนซึ่งมีลักษณะดังนี้ @@rules_java++toolchains+local_jdk สิ่งที่พบเห็นได้บ่อยกว่ามากคือ ป้ายกำกับที่มีชื่อที่เห็นได้ชัดของที่เก็บ ซึ่งมีลักษณะดังนี้

@myrepo//my/app/main:app_binary

โดยมีความแตกต่างเพียงเล็กน้อยคือชื่อที่เก็บจะนำหน้าด้วย @ 1 ตัวแทนที่จะเป็น 2 ตัว ซึ่งหมายถึงที่เก็บที่มีชื่อว่า myrepo ซึ่งอาจแตกต่างกัน โดยขึ้นอยู่กับบริบทที่ป้ายกำกับนี้ปรากฏ

ในกรณีทั่วไปที่ป้ายกำกับอ้างอิงถึงที่เก็บข้อมูลเดียวกันกับที่ใช้ ส่วนชื่อที่เก็บอาจละไว้ได้ ดังนั้น ภายใน @@myrepo ป้ายกำกับแรก มักจะเขียนเป็น

//my/app/main:app_binary

ส่วนที่ 2 ของป้ายกำกับคือชื่อแพ็กเกจที่ไม่ผ่านการรับรอง my/app/main เส้นทางไปยังแพ็กเกจ ที่สัมพันธ์กับรูทของที่เก็บ ชื่อที่เก็บและชื่อแพ็กเกจที่ไม่มีคุณสมบัติจะรวมกันเป็นชื่อแพ็กเกจที่มีคุณสมบัติครบถ้วน @@myrepo//my/app/main เมื่อป้ายกำกับอ้างอิงถึงแพ็กเกจเดียวกันกับที่ใช้ ชื่อแพ็กเกจ (และเครื่องหมายโคลอนหากมี) อาจถูกละไว้ ดังนั้น ใน @@myrepo//my/app/main ป้ายกำกับนี้อาจเขียนได้ด้วยวิธีใดวิธีหนึ่งต่อไปนี้

app_binary
:app_binary

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

ส่วนของป้ายกำกับหลังเครื่องหมายโคลอน app_binary คือชื่อเป้าหมายที่ไม่มีคุณสมบัติ เมื่อตรงกับคอมโพเนนต์สุดท้ายของเส้นทางแพ็กเกจ คุณอาจละเว้นคอมโพเนนต์ดังกล่าวและ โคลอนได้ ดังนั้น ป้ายกำกับ 2 รายการนี้จึงมีความหมายเหมือนกัน

//my/app/lib
//my/app/lib:lib

ชื่อของเป้าหมายไฟล์ในไดเรกทอรีย่อยของแพ็กเกจคือเส้นทางของไฟล์ ที่สัมพันธ์กับรูทของแพ็กเกจ (ไดเรกทอรีที่มีไฟล์ BUILD) ดังนั้น ไฟล์นี้จึงอยู่ในไดเรกทอรีย่อย my/app/main/testdata ของที่เก็บ

//my/app/main:testdata/input.txt

สตริง เช่น //my/app และ @@some_repo//my/app มี 2 ความหมายขึ้นอยู่กับบริบทที่ใช้ เมื่อ Bazel คาดหวังป้ายกำกับ สตริงเหล่านี้จะหมายถึง //my/app:app และ @@some_repo//my/app:app ตามลำดับ แต่เมื่อ Bazel คาดหวังแพ็กเกจ (เช่น ในpackage_groupข้อกำหนด) ระบบจะอ้างอิงแพ็กเกจที่มีป้ายกำกับนั้น

ข้อผิดพลาดที่พบบ่อยในไฟล์ BUILD คือการใช้ //my/app เพื่ออ้างอิงถึงแพ็กเกจ หรืออ้างอิงถึงเป้าหมายทั้งหมดในแพ็กเกจ ซึ่งไม่ถูกต้อง โปรดทราบว่า //my/app:app มีค่าเท่ากับ app ดังนั้นจึงตั้งชื่อเป้าหมาย app ในแพ็กเกจ my/app ของที่เก็บปัจจุบัน

อย่างไรก็ตาม เราขอแนะนำให้ใช้ //my/app เพื่ออ้างอิงถึงแพ็กเกจใน ข้อกำหนดของ package_group หรือในไฟล์ .bzl เนื่องจากจะสื่อให้เห็นอย่างชัดเจนว่าชื่อแพ็กเกจเป็นแบบสัมบูรณ์และอยู่ในไดเรกทอรีระดับบนสุดของพื้นที่ทำงาน

ใช้ป้ายกำกับแบบสัมพัทธ์เพื่ออ้างอิงเป้าหมายในแพ็กเกจอื่นไม่ได้ ในกรณีนี้ต้องระบุตัวระบุที่เก็บและชื่อแพ็กเกจเสมอ เช่น หากโครงสร้างแหล่งที่มามีทั้งแพ็กเกจ my/app และแพ็กเกจ my/app/testdata (แต่ละไดเรกทอรีมีไฟล์ BUILD ของตัวเอง) แพ็กเกจหลังจะมีไฟล์ชื่อ testdepot.zip ต่อไปนี้ คือ 2 วิธี (วิธีหนึ่งไม่ถูกต้อง อีกวิธีหนึ่งถูกต้อง) ในการอ้างอิงไฟล์นี้ภายใน //my/app:BUILD

ไม่ถูกต้อง — testdata เป็นแพ็กเกจอื่น คุณจึงใช้เส้นทางแบบสัมพัทธ์ไม่ได้

testdata/testdepot.zip

ถูกต้อง - อ้างอิงถึง testdata พร้อมเส้นทางแบบเต็ม

//my/app/testdata:testdepot.zip

ป้ายกำกับที่ขึ้นต้นด้วย @@// คือการอ้างอิงถึงที่เก็บหลัก ซึ่งจะยังคงใช้งานได้แม้จะมาจากที่เก็บภายนอกก็ตาม ดังนั้น @@//a/b/c จึงแตกต่างจาก //a/b/c เมื่ออ้างอิงจากที่เก็บข้อมูลภายนอก โดยตัวเลือกแรกจะอ้างอิงกลับไปยังที่เก็บข้อมูลหลัก ส่วนตัวเลือกที่สองจะค้นหา //a/b/c ในที่เก็บข้อมูลภายนอก โดยเฉพาะอย่างยิ่งเมื่อเขียนกฎในที่เก็บหลักที่อ้างอิงถึงเป้าหมายในที่เก็บหลัก และจะใช้จากที่เก็บภายนอก

ดูข้อมูลเกี่ยวกับวิธีต่างๆ ที่คุณใช้เพื่ออ้างอิงเป้าหมายได้ที่ รูปแบบเป้าหมาย

ข้อกำหนดทางคำศัพท์ของป้ายกำกับ

ไวยากรณ์ของป้ายกำกับไม่แนะนำให้ใช้อักขระเมตาที่มีความหมายพิเศษสำหรับเชลล์ ซึ่งจะช่วยหลีกเลี่ยงปัญหาการอ้างอิงโดยไม่ตั้งใจ และช่วยให้สร้างเครื่องมือและสคริปต์ที่จัดการป้ายกำกับได้ง่ายขึ้น เช่น ภาษาการค้นหาของ Bazel

รายละเอียดที่แน่นอนของชื่อเป้าหมายที่อนุญาตมีดังนี้

ชื่อเป้าหมาย - package-name:target-name

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

ชื่อเป้าหมายต้องประกอบด้วยอักขระจากชุด a–z, A–Z, 0–9 และสัญลักษณ์เครื่องหมายวรรคตอน !%-@^_"#$&'()*-+,;<=>?[]{|}~/. ทั้งหมด

ชื่อไฟล์ต้องเป็นชื่อเส้นทางแบบสัมพัทธ์ในรูปแบบปกติ ซึ่งหมายความว่าต้องไม่ขึ้นต้นหรือลงท้ายด้วยเครื่องหมายทับ (เช่น /foo และ foo/ จะใช้ไม่ได้) และต้องไม่มีเครื่องหมายทับหลายรายการติดต่อกันเป็นตัวคั่นเส้นทาง (เช่น foo//bar) ในทำนองเดียวกัน การอ้างอิงระดับบน (..) และการอ้างอิงไดเรกทอรีปัจจุบัน (./) จะใช้ไม่ได้

ไม่ถูกต้อง — ห้ามใช้ .. เพื่ออ้างอิงไฟล์ในแพ็กเกจอื่นๆ

ถูกต้อง - ใช้ //package-name:filename

แม้ว่าโดยทั่วไปจะใช้ / ในชื่อของเป้าหมายไฟล์ แต่ก็ควรหลีกเลี่ยงการใช้ / ในชื่อของกฎ โดยเฉพาะอย่างยิ่งเมื่อใช้รูปแบบย่อของป้ายกำกับ ผู้อ่านอาจสับสนได้ ป้ายกำกับ //foo/bar/wiz เป็นรูปแบบย่อของ //foo/bar/wiz:wiz เสมอ แม้ว่าจะไม่มีแพ็กเกจ foo/bar/wiz ก็ตาม โดยจะไม่ อ้างอิงถึง //foo:bar/wiz แม้ว่าจะมีเป้าหมายดังกล่าวอยู่ก็ตาม

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

ชื่อแพ็กเกจ - //package-name:target-name

ชื่อของแพ็กเกจคือชื่อของไดเรกทอรีที่มีไฟล์ BUILD ซึ่งสัมพันธ์กับไดเรกทอรีระดับบนสุดของที่เก็บที่มีแพ็กเกจ ตัวอย่างเช่น my/app

ในระดับเทคนิค Bazel จะบังคับใช้สิ่งต่อไปนี้

• อักขระที่อนุญาตในชื่อแพ็กเกจคือตัวอักษรพิมพ์เล็ก a ถึง z ตัวอักษรพิมพ์ใหญ่ A ถึง Z ตัวเลข 0 ถึง 9 อักขระ ! \"#$%&'()*+,-.;<=>?@[]^_`{|} (ใช่ มีอักขระช่องว่าง อยู่ด้วย) และแน่นอนว่ามีเครื่องหมายทับ / (เนื่องจากเป็นตัวคั่น ไดเรกทอรี)
• ชื่อแพ็กเกจต้องไม่ขึ้นต้นหรือลงท้ายด้วยอักขระเครื่องหมายทับ /
• ชื่อแพ็กเกจต้องไม่มีสตริงย่อย // ซึ่งไม่สมเหตุสมผล เพราะเส้นทางไดเรกทอรีที่สอดคล้องกันจะเป็นอะไร
• ชื่อแพ็กเกจต้องไม่มีสตริงย่อย /./ หรือ /../ หรือ /.../ เป็นต้น การบังคับใช้นี้มีขึ้นเพื่อหลีกเลี่ยงความสับสนเมื่อแปลระหว่างชื่อแพ็กเกจเชิงตรรกะ กับชื่อไดเรกทอรีจริง เนื่องจากความหมายเชิงความหมายของ อักขระจุดในสตริงเส้นทาง

ในทางปฏิบัติ

• สำหรับภาษาที่มีโครงสร้างไดเรกทอรีที่สำคัญต่อระบบโมดูล (เช่น Java) คุณควรเลือกชื่อไดเรกทอรีที่เป็นตัวระบุที่ถูกต้องในภาษาดังกล่าว เช่น อย่าขึ้นต้นด้วยตัวเลขและหลีกเลี่ยงสัญลักษณ์พิเศษ โดยเฉพาะขีดล่างและขีดกลาง
• แม้ว่า Bazel จะรองรับเป้าหมายในแพ็กเกจรูทของพื้นที่ทำงาน (เช่น //:foo) แต่ควรปล่อยให้แพ็กเกจนั้นว่างไว้เพื่อให้แพ็กเกจที่มีความหมายทั้งหมด มีชื่อที่สื่อความหมาย

กฎ

กฎจะระบุความสัมพันธ์ระหว่างอินพุตและเอาต์พุต รวมถึง ขั้นตอนในการสร้างเอาต์พุต กฎอาจเป็นหนึ่งในหลายประเภทที่แตกต่างกัน (บางครั้งเรียกว่าคลาสของกฎ) ซึ่งสร้างไฟล์ปฏิบัติการและไลบรารีที่คอมไพล์แล้ว ไฟล์ปฏิบัติการทดสอบ และเอาต์พุตอื่นๆ ที่รองรับตามที่อธิบายไว้ในสารานุกรมการสร้าง

ไฟล์ BUILD จะประกาศเป้าหมายโดยการเรียกใช้กฎ

ในตัวอย่างด้านล่าง เราจะเห็นการประกาศเป้าหมาย my_app โดยใช้กฎ cc_binary

cc_binary(
    name = "my_app",
    srcs = ["my_app.cc"],
    deps = [
        "//absl/base",
        "//absl/strings",
    ],
)

การเรียกใช้กฎทุกครั้งจะมีแอตทริบิวต์ name (ซึ่งต้องเป็นชื่อเป้าหมายที่ถูกต้อง) ซึ่งประกาศเป้าหมายภายในแพ็กเกจของไฟล์ BUILD

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

แอตทริบิวต์ srcs ที่มีอยู่ในหลายกฎมีประเภทเป็น "รายการป้ายกำกับ" และค่าของแอตทริบิวต์ (หากมี) คือรายการป้ายกำกับ โดยแต่ละป้ายกำกับเป็นชื่อของเป้าหมายที่เป็นอินพุตของกฎนี้

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

ในกรณีอื่นๆ ชื่อมีความสำคัญ เช่น สำหรับกฎ *_binary และ *_test ชื่อกฎจะกำหนดชื่อของไฟล์ที่เรียกใช้งานได้ซึ่งสร้างขึ้นโดย การบิลด์

กราฟแบบมีทิศทางแบบไม่มีวงจรเหนือเป้าหมายนี้เรียกว่ากราฟเป้าหมายหรือ กราฟทรัพยากร Dependency ของบิลด์ และเป็นโดเมนที่เครื่องมือ Bazel Query ทำงาน