อย่าลืมนัดของเรา: BazelCon 2023 จะจัดขึ้นในวันที่ 24-25 ตุลาคมที่ Google ที่มิวนิก ดูข้อมูลเพิ่มเติม

ป้ายกำกับ

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

เป้าหมายทั้งหมดอยู่ในแพ็กเกจเดียว ชื่อของเป้าหมายเรียกว่าป้ายกํากับ ทุกป้ายกํากับจะระบุเป้าหมายที่ไม่ซ้ํา ป้ายกํากับทั่วไปในรูปแบบ 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 คือชื่อเป้าหมายที่ขาดคุณสมบัติ เมื่อจับคู่กับคอมโพเนนต์สุดท้ายของเส้นทางแพ็กเกจ ระบบอาจละเว้นและโคลอน ดังนั้น ป้ายกํากับทั้งสองนี้เทียบเท่ากัน

//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 (ไดเรกทอรี 2 รายการนี้มีไฟล์ BUILD ของตัวเอง) แพ็กเกจรายการหลังจะมีไฟล์ชื่อ testdepot.zip ดู 2 วิธีดังนี้ (วิธีหนึ่งไม่ถูกต้อง 1) เพื่ออ้างถึงไฟล์นี้ภายใน //my/app:BUILD

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

testdata/testdepot.zip

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

//my/app/testdata:testdepot.zip

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

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

ข้อกําหนดป้ายกํากับ

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

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

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

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

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

ชื่อไฟล์ต้องเป็นชื่อเส้นทางแบบสัมพัทธ์ในรูปแบบปกติ ซึ่งหมายความว่าห้ามขึ้นต้นหรือลงท้ายด้วยเครื่องหมายทับ (เช่น /foo และ foo/) หรือมีเครื่องหมายทับ (3) คั่นระหว่างตัวคั่นเส้นทาง (เช่น 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, az, 09, '/', '-', '.', '@' และ '_' และต้องไม่ขึ้นต้นด้วยเครื่องหมายทับ

สําหรับภาษาที่มีโครงสร้างไดเรกทอรีที่สําคัญต่อระบบโมดูล (เช่น 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 ที่แสดงในกฎจํานวนมากมีประเภท "รายการป้ายกํากับ" แต่หากมี จะเป็นรายการป้ายกํากับ โดยแต่ละกฎจะมีชื่อเป้าหมายเป็นอินพุตสําหรับกฎนี้

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

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

กราฟวงกลมสําหรับชี้ที่อยู่เหนือเป้าหมายเรียกว่ากราฟเป้าหมายหรือสร้างกราฟทรัพยากร Dependency และเป็นโดเมนที่เครื่องมือ Query ของ Bazel ทํางาน

เป้าหมาย ไฟล์ BUILD