ฟังก์ชัน

เนื้อหา

• แพ็กเกจ
• package_group
• exports_files
• glob
• เลือก
• แพ็กเกจย่อย

พัสดุ

package(default_deprecation, default_package_metadata, default_testonly, default_visibility, features)

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

ควรเรียกใช้ฟังก์ชัน package() ทันทีหลังจากคำสั่ง load() ทั้งหมดที่ด้านบนของ ไฟล์ ก่อนกฎใดๆ

อาร์กิวเมนต์

ตัวอย่าง

package(default_visibility = ["//foo:target"])

package_group

package_group(name, packages, includes)

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

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

ระบบจะถือว่าแพ็กเกจอยู่ในกลุ่มหากตรงกับแอตทริบิวต์ packages หรืออยู่ในกลุ่มแพ็กเกจอื่นๆ ที่ระบุไว้ในแอตทริบิวต์includes

ในทางเทคนิคแล้ว กลุ่มแพ็กเกจคือเป้าหมาย แต่ไม่ได้สร้างขึ้นโดยกฎ และไม่มีการป้องกันการมองเห็นด้วยตัวเอง

อาร์กิวเมนต์

ตัวอย่าง

ประกาศ package_group ต่อไปนี้ระบุ กลุ่มแพ็กเกจชื่อ "tropical" ซึ่งมีผลไม้เขตร้อน

package_group(
    name = "tropical",
    packages = [
        "//fruits/mango",
        "//fruits/orange",
        "//fruits/papaya/...",
    ],
)

การประกาศต่อไปนี้ระบุกลุ่มแพ็กเกจของแอปพลิเคชันสมมติ

package_group(
    name = "fooapp",
    includes = [
        ":controller",
        ":model",
        ":view",
    ],
)

package_group(
    name = "model",
    packages = ["//fooapp/database"],
)

package_group(
    name = "view",
    packages = [
        "//fooapp/swingui",
        "//fooapp/webui",
    ],
)

package_group(
    name = "controller",
    packages = ["//fooapp/algorithm"],
)

exports_files

exports_files([label, ...], visibility, licenses)

exports_files() ระบุรายการไฟล์ที่เป็นของ แพ็กเกจนี้ซึ่งส่งออกไปยังแพ็กเกจอื่นๆ

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

ตามลักษณะการทำงานเดิม ระบบจะส่งออกไฟล์ที่ระบุเป็นอินพุตของกฎด้วย โดยมีการมองเห็นเริ่มต้นจนกว่าจะมีการเปลี่ยนสถานะของฟีเจอร์ --incompatible_no_implicit_file_export อย่างไรก็ตาม ไม่ควรพึ่งพาพฤติกรรมนี้และควรย้ายข้อมูลออกจากพฤติกรรมนี้อย่างแข็งขัน

อาร์กิวเมนต์

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

ตัวอย่าง

ตัวอย่างต่อไปนี้จะส่งออก golden.txt ซึ่งเป็นไฟล์ข้อความจากแพ็กเกจ test_data เพื่อให้แพ็กเกจอื่นๆ ใช้ได้ เช่น ในแอตทริบิวต์ data ของการทดสอบ

# from //test_data/BUILD

exports_files(["golden.txt"])

glob

glob(include, exclude=[], exclude_directories=1, allow_empty=True)

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

ระบบจะรวมป้ายกำกับของไฟล์ต้นฉบับไว้ในผลลัพธ์หากเส้นทางที่สัมพันธ์กับแพ็กเกจของไฟล์ตรงกับinclude รูปแบบใดรูปแบบหนึ่งและไม่ตรงกับexclude รูปแบบใดเลย

รายการ include และ exclude มีรูปแบบเส้นทาง ที่สัมพันธ์กับแพ็กเกจปัจจุบัน รูปแบบทุกรูปแบบอาจประกอบด้วยกลุ่มเส้นทางอย่างน้อย 1 กลุ่ม เช่นเดียวกับเส้นทาง Unix ส่วนเหล่านี้จะคั่นด้วย / กลุ่มอาจมีไวลด์การ์ด * ซึ่งจะตรงกับสตริงย่อยใดก็ได้ในกลุ่มเส้นทาง (แม้จะเป็นสตริงย่อยที่ว่างเปล่า) ยกเว้นตัวคั่นไดเรกทอรี / คุณใช้ไวลด์การ์ดนี้ได้หลายครั้ง ภายในส่วนเส้นทางเดียว นอกจากนี้ ไวลด์การ์ด ** ยังสามารถจับคู่กับ ส่วนเส้นทางที่สมบูรณ์ตั้งแต่ 0 รายการขึ้นไป แต่ต้องประกาศเป็นส่วนเส้นทาง แบบสแตนด์อโลน

• foo/bar.txt ตรงกับไฟล์ foo/bar.txt ในแพ็กเกจนี้
• foo/*.txt จะตรงกับทุกไฟล์ในไดเรกทอรี foo/ หากไฟล์ลงท้ายด้วย .txt (เว้นแต่ foo/ จะเป็นแพ็กเกจย่อย)
• foo/a*.htm* จะจับคู่ทุกไฟล์ในไดเรกทอรี foo/ ที่ขึ้นต้นด้วย a ตามด้วยสตริงใดก็ได้ (อาจเป็นสตริงว่าง) ตามด้วย .htm และลงท้ายด้วยสตริงใดก็ได้ เช่น foo/axx.htm และ foo/a.html หรือ foo/axxx.html
• **/a.txt จะตรงกับไฟล์ a.txt ทุกไฟล์ในทุก ไดเรกทอรีย่อยของแพ็กเกจนี้
• **/bar/**/*.txt จะตรงกับไฟล์ .txt ทุกไฟล์ในทุก ไดเรกทอรีย่อยของแพ็กเกจนี้ หากมีไดเรกทอรีอย่างน้อย 1 รายการในเส้นทางผลลัพธ์ที่ชื่อ bar เช่น xxx/bar/yyy/zzz/a.txt หรือ bar/a.txt (โปรดทราบว่า ** ยังตรงกับ 0 ส่วนด้วย) หรือ bar/zzz/a.txt
• ** จะตรงกับทุกไฟล์ในทุกไดเรกทอรีย่อยของแพ็กเกจนี้
• foo**/a.txt เป็นรูปแบบที่ไม่ถูกต้อง เนื่องจาก ** ต้อง เป็นกลุ่มของตัวเอง

หากเปิดใช้อาร์กิวเมนต์ exclude_directories (ตั้งค่าเป็น 1) ระบบจะละเว้นไฟล์ประเภทไดเรกทอรีจากผลลัพธ์ (ค่าเริ่มต้นคือ 1)

หากตั้งค่าอาร์กิวเมนต์ allow_empty เป็น False ฟังก์ชัน glob จะแสดงข้อผิดพลาดหากผลลัพธ์เป็นรายการว่าง

ข้อจำกัดและคำเตือนที่สำคัญมีดังนี้

1. เนื่องจาก glob() ทำงานระหว่างการประเมินไฟล์ BUILD glob() จะจับคู่ไฟล์ในโครงสร้างแหล่งที่มาเท่านั้น ไม่ใช่ไฟล์ที่สร้างขึ้น หากคุณกำลังสร้างเป้าหมายที่ต้องใช้ทั้งไฟล์ต้นฉบับและไฟล์ที่สร้างขึ้น คุณต้องต่อท้ายรายการไฟล์ที่สร้างขึ้นอย่างชัดเจน กับ Glob ดูตัวอย่าง ด้านล่างที่มี :mylib และ :gen_java_srcs

2. หากกฎมีชื่อเดียวกันกับไฟล์ต้นฉบับที่ตรงกัน กฎจะ "ซ่อน" ไฟล์

   หากต้องการทำความเข้าใจเรื่องนี้ โปรดทราบว่า glob() จะแสดงรายการเส้นทาง ดังนั้นการใช้ glob() ในแอตทริบิวต์ของกฎอื่นๆ (เช่น srcs = glob(["*.cc"])) จะมีผลเช่นเดียวกับการแสดงรายการเส้นทางที่ตรงกันอย่างชัดเจน เช่น หาก glob() ให้ผลลัพธ์เป็น ["Foo.java", "bar/Baz.java"] แต่ก็มีกฎใน แพ็กเกจที่ชื่อ "Foo.java" (ซึ่งอนุญาต แม้ว่า Bazel จะแจ้งเตือนเกี่ยวกับกฎนี้) ผู้ใช้ glob() จะใช้กฎ "Foo.java" (เอาต์พุตของกฎ) แทนไฟล์ "Foo.java" ดูรายละเอียดเพิ่มเติมได้ที่ปัญหา #10395 ใน GitHub

3. Glob อาจตรงกับไฟล์ในไดเรกทอรีย่อย และชื่อไดเรกทอรีย่อย อาจเป็นไวลด์การ์ด อย่างไรก็ตาม...

4. ป้ายกำกับต้องไม่ข้ามขอบเขตแพ็กเกจ และ Glob ต้องไม่ตรงกับไฟล์ในแพ็กเกจย่อย

   เช่น นิพจน์ Glob **/*.cc ในแพ็กเกจ x จะไม่รวม x/y/z.cc หาก x/y มีอยู่เป็นแพ็กเกจ (ไม่ว่าจะในรูปแบบ x/y/BUILD หรือที่อื่นในเส้นทางแพ็กเกจ) ซึ่งหมายความว่าผลลัพธ์ของนิพจน์ Glob จะขึ้นอยู่กับการมีอยู่ของไฟล์ BUILD กล่าวคือ นิพจน์ Glob เดียวกันจะรวม x/y/z.cc หากไม่มีแพ็กเกจที่ชื่อ x/y หรือมีการทำเครื่องหมายว่าลบแล้วโดยใช้แฟล็ก --deleted_packages

5. ข้อจำกัดข้างต้นมีผลกับนิพจน์ Glob ทั้งหมด ไม่ว่าจะใช้อักขระไวลด์การ์ดใดก็ตาม
6. ไฟล์ที่ซ่อนซึ่งมีชื่อไฟล์ขึ้นต้นด้วย . จะตรงกันกับไวลด์การ์ด ** และ * อย่างสมบูรณ์ หากต้องการจับคู่ไฟล์ที่ซ่อนอยู่ กับรูปแบบแบบผสม รูปแบบของคุณต้องเริ่มต้นด้วย . เช่น * และ .*.txt จะตรงกับ .foo.txt แต่ *.txt จะไม่ตรง ระบบจะจับคู่ไดเรกทอรีที่ซ่อนในลักษณะเดียวกันด้วย ไดเรกทอรีที่ซ่อนอยู่ อาจมีไฟล์ที่ไม่จำเป็นต้องใช้เป็นอินพุต และอาจเพิ่ม จำนวนไฟล์ที่ glob โดยไม่จำเป็นและการใช้หน่วยความจำ หากต้องการยกเว้น ไดเรกทอรีที่ซ่อน ให้เพิ่มไดเรกทอรีเหล่านั้นลงในอาร์กิวเมนต์รายการ "exclude"
7. ไวลด์การ์ด "**" มีกรณีพิเศษ 1 กรณีคือ รูปแบบ "**" ไม่ตรงกับเส้นทางไดเรกทอรีของแพ็กเกจ กล่าวคือ glob(["**"], exclude_directories = 0) จะตรงกับไฟล์ทั้งหมด และไดเรกทอรีที่อยู่ภายใต้ไดเรกทอรีของแพ็กเกจปัจจุบันอย่างเคร่งครัด (แต่จะไม่รวมไดเรกทอรีของแพ็กเกจย่อย ดูหมายเหตุก่อนหน้า เกี่ยวกับเรื่องนี้)

โดยทั่วไป คุณควรพยายามระบุส่วนขยายที่เหมาะสม (เช่น *.html) แทนการใช้ '*' เปล่าๆ สำหรับรูปแบบ Glob ชื่อที่ชัดเจนยิ่งขึ้น จะช่วยให้คุณไม่ต้องทำเอกสารประกอบและมั่นใจได้ว่าคุณจะไม่จับคู่ไฟล์สำรอง หรือไฟล์บันทึกอัตโนมัติของ emacs/vi/... โดยไม่ได้ตั้งใจ

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

ตัวอย่าง Glob

สร้างไลบรารี Java จากไฟล์ Java ทั้งหมดในไดเรกทอรีนี้ และไฟล์ทั้งหมดที่สร้างโดยกฎ :gen_java_srcs

java_library(
    name = "mylib",
    srcs = glob(["*.java"]) + [":gen_java_srcs"],
    deps = "...",
)

genrule(
    name = "gen_java_srcs",
    outs = [
        "Foo.java",
        "Bar.java",
    ],
    ...
)

รวมไฟล์ txt ทั้งหมดในไดเรกทอรี testdata ยกเว้น experimental.txt โปรดทราบว่าระบบจะไม่รวมไฟล์ในไดเรกทอรีย่อยของ testdata หากต้องการรวมไฟล์เหล่านั้น ให้ใช้ Glob แบบเรียกซ้ำ (**)

sh_test(
    name = "mytest",
    srcs = ["mytest.sh"],
    data = glob(
        ["testdata/*.txt"],
        exclude = ["testdata/experimental.txt"],
    ),
)

ตัวอย่าง Glob แบบเรียกซ้ำ

ทำให้การทดสอบขึ้นอยู่กับไฟล์ txt ทั้งหมดในไดเรกทอรี testdata และไดเรกทอรีย่อยใดๆ ของไดเรกทอรีนั้น (และไดเรกทอรีย่อยของไดเรกทอรีย่อย และอื่นๆ) ระบบจะไม่สนใจไดเรกทอรีย่อยที่มีไฟล์ BUILD (ดูข้อจำกัด และข้อควรระวังด้านบน)

sh_test(
    name = "mytest",
    srcs = ["mytest.sh"],
    data = glob(["testdata/**/*.txt"]),
)

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

java_library(
    name = "mylib",
    srcs = glob(
        ["**/*.java"],
        exclude = ["**/testing/**"],
    ),
)

ตัวอย่าง Glob ที่ขยาย

สร้าง genrule แต่ละรายการสำหรับ *_test.cc ในไดเรกทอรีปัจจุบัน ที่นับจำนวนบรรทัดในไฟล์

# Conveniently, the build language supports list comprehensions.
[genrule(
    name = "count_lines_" + f[:-3],  # strip ".cc"
    srcs = [f],
    outs = ["%s-linecount.txt" % f[:-3]],
    cmd = "wc -l $< >$@",
 ) for f in glob(["*_test.cc"])]

หากไฟล์ BUILD ด้านบนอยู่ในแพ็กเกจ //foo และแพ็กเกจมีไฟล์ที่ตรงกัน 3 ไฟล์ ได้แก่ a_test.cc, b_test.cc และ c_test.cc การเรียกใช้ bazel query '//foo:all' จะแสดงรายการกฎทั้งหมดที่สร้างขึ้น

$ bazel query '//foo:all' | sort
//foo:count_lines_a_test
//foo:count_lines_b_test
//foo:count_lines_c_test

เลือก

select(
    {conditionA: valuesA, conditionB: valuesB, ...},
    no_match_error = "custom message"
)

select() คือฟังก์ชันตัวช่วยที่ทำให้แอตทริบิวต์กฎกำหนดค่าได้ โดยสามารถแทนที่ด้านขวาของ เกือบ การกําหนดแอตทริบิวต์ใดก็ได้เพื่อให้ค่าขึ้นอยู่กับแฟล็ก Bazel ในบรรทัดคำสั่ง คุณสามารถใช้สิ่งนี้เพื่อกำหนดการอ้างอิงเฉพาะแพลตฟอร์มหรือเพื่อ ฝังทรัพยากรต่างๆ โดยขึ้นอยู่กับว่ากฎนั้นสร้างขึ้นในโหมด "นักพัฒนาซอฟต์แวร์" หรือโหมด "รุ่นที่เผยแพร่"

การใช้งานพื้นฐานมีดังนี้

sh_binary(
    name = "mytarget",
    srcs = select({
        ":conditionA": ["mytarget_a.sh"],
        ":conditionB": ["mytarget_b.sh"],
        "//conditions:default": ["mytarget_default.sh"]
    })
)

ซึ่งจะทำให้แอตทริบิวต์ srcs ของ sh_binary กำหนดค่าได้โดยการแทนที่การกำหนดรายการป้ายกำกับปกติ ด้วยการเรียก select ที่แมป เงื่อนไขการกำหนดค่ากับค่าที่ตรงกัน แต่ละเงื่อนไขคือป้ายกำกับ การอ้างอิงถึง config_setting หรือ constraint_value ซึ่งจะ "ตรงกัน" หากการกำหนดค่าของเป้าหมายตรงกับชุดค่าที่คาดไว้ จากนั้นค่าของ mytarget#srcs จะกลายเป็นรายการป้ายกำกับที่ตรงกับการเรียกใช้ปัจจุบัน

หมายเหตุ:

• มีการเลือกเงื่อนไขเพียง 1 รายการในการเรียกใช้
• หากมีหลายเงื่อนไขที่ตรงกันและมีเงื่อนไขหนึ่งเป็นความเชี่ยวชาญพิเศษของเงื่อนไขอื่นๆ ความเชี่ยวชาญพิเศษจะมีลำดับความสำคัญสูงกว่า เงื่อนไข B ถือเป็น ความเชี่ยวชาญพิเศษของเงื่อนไข A หาก B มีค่าแฟล็กและค่าข้อจำกัด เหมือนกับ A ทั้งหมด รวมถึงมีค่าแฟล็กหรือค่าข้อจำกัดเพิ่มเติม นอกจากนี้ยังหมายความว่าการแก้ปัญหาความเชี่ยวชาญไม่ได้ออกแบบมาเพื่อสร้างลำดับตามที่แสดงในตัวอย่างที่ 2 ด้านล่าง
• หากมีหลายเงื่อนไขที่ตรงกันและมีเงื่อนไขหนึ่งที่ไม่ใช่การเฉพาะเจาะจงของเงื่อนไขอื่นๆ ทั้งหมด Bazel จะล้มเหลวพร้อมข้อผิดพลาด เว้นแต่เงื่อนไขทั้งหมดจะให้ค่าเดียวกัน
• ระบบจะถือว่าป้ายกำกับเสมือนพิเศษ //conditions:default ตรงกัน หากไม่มีเงื่อนไขอื่นตรงกัน หากไม่มีเงื่อนไขนี้ กฎอื่นๆ ต้องตรงกันเพื่อหลีกเลี่ยงข้อผิดพลาด
• select สามารถฝังภายในการกำหนดแอตทริบิวต์ที่ใหญ่กว่าได้ ดังนั้น srcs = ["common.sh"] + select({ ":conditionA": ["myrule_a.sh"], ...}) และ srcs = select({ ":conditionA": ["a.sh"]}) + select({ ":conditionB": ["b.sh"]}) จึงเป็นนิพจน์ที่ถูกต้อง
• select ใช้ได้กับแอตทริบิวต์ส่วนใหญ่ แต่ไม่ใช่ทั้งหมด แอตทริบิวต์ที่ไม่เข้ากัน จะมีการทำเครื่องหมาย nonconfigurable ในเอกสารประกอบ

  แพ็กเกจย่อย

  subpackages(include, exclude=[], allow_empty=True)

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

  รายการแพ็กเกจย่อยที่ได้จะเรียงตามลำดับและมีเส้นทางที่สัมพันธ์กับแพ็กเกจที่โหลดอยู่ในปัจจุบันซึ่งตรงกับรูปแบบที่ระบุใน include และไม่ใช่เส้นทางใน exclude

  ตัวอย่าง

  ตัวอย่างต่อไปนี้แสดงรายการแพ็กเกจย่อยโดยตรงทั้งหมดสำหรับแพ็กเกจ foo/BUILD

  # The following BUILD files exist:
  # foo/BUILD
  # foo/bar/baz/BUILD
  # foo/sub/BUILD
  # foo/sub/deeper/BUILD
  #
  # In foo/BUILD a call to
  subs = subpackages(include = ["**"])
  
  # results in subs == ["sub", "bar/baz"]
  #
  # 'sub/deeper' is not included because it is a subpackage of 'foo/sub' not of
  # 'foo'
  

  โดยทั่วไปแล้ว เราขอแนะนำให้ผู้ใช้ใช้โมดูล "แพ็กเกจย่อย" ของ skylib แทนการเรียกใช้ฟังก์ชันนี้โดยตรง