ป้ายกำกับ

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

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

@myrepo//my/app/main:app_binary

ส่วนแรกของป้ายกำกับคือชื่อที่เก็บ @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 ในแพ็กเกจ my/app ของที่เก็บปัจจุบัน

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

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

ไม่ถูกต้อง — 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

ชื่อแพ็กเกจต้องประกอบไปด้วยอักขระทั้งหมดที่มาจากชุด A-Z, a–z, 0–9, "/", "-", ".", "@" และ "_" และต้องไม่ขึ้นต้นด้วยเครื่องหมายทับ

สำหรับภาษาที่มีโครงสร้างไดเรกทอรีที่สำคัญต่อระบบโมดูล (เช่น Java) คุณควรเลือกชื่อไดเรกทอรีที่เป็นตัวระบุที่ถูกต้องในภาษานั้นๆ

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

ชื่อแพ็กเกจต้องไม่มีสตริงย่อย // หรือลงท้ายด้วยเครื่องหมายทับ

กฎ

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

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

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

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

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

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

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

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

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

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

เป้าหมาย

ไฟล์บิลด์