การอ้างอิง

รายงานปัญหา ดูแหล่งที่มา รุ่น Nightly · 7.4 7.3 · 7.2 · 7.1 · 7.0 · 6.5

A เป้าหมายขึ้นอยู่กับ B เป้าหมาย หาก A จำเป็นต้องใช้ B ในเวลาบิลด์หรือการดำเนินการ ความสัมพันธ์แบบขึ้นอยู่กับจะทําให้เกิด กราฟแบบ Acyclic โดยตรง (DAG) เหนือเป้าหมาย และเรียกว่ากราฟการขึ้นต่อ

ทรัพยากร Dependency โดยตรงของเป้าหมายคือเป้าหมายอื่นๆ ที่เข้าถึงได้ด้วยเส้นทางที่มีความยาว 1 ในกราฟทรัพยากร Dependency ทรัพยากร Dependency แบบสัญจร ของเป้าหมายคือเป้าหมายที่เป้าหมายพึ่งพิงผ่านเส้นทางที่มีความยาวเท่าใดก็ได้ผ่านกราฟ

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

ทรัพยากร Dependency จริงและที่ประกาศ

เป้าหมาย X ขึ้นอยู่กับเป้าหมาย Y จริงๆ หาก Y ต้องมีอยู่ สร้างขึ้น และอัปเดตแล้วเพื่อให้สร้าง X ได้อย่างถูกต้อง สร้างอาจหมายถึงสร้าง ประมวลผล คอมไพล์ ลิงก์ เก็บถาวร บีบอัด ดำเนินการ หรืองานประเภทอื่นๆ ที่เกิดขึ้นเป็นประจำระหว่างการสร้าง

เป้าหมาย X มีการขึ้นต่อกันที่ประกาศไว้กับเป้าหมาย Y หากมีขอบเขตการขึ้นต่อกันจาก X ไปยัง Y ในแพ็กเกจของ X

กราฟของ Dependency จริง A ต้องเป็นกราฟย่อยของกราฟ Dependency ที่ประกาศ D เพื่อให้บิลด์ถูกต้อง กล่าวคือ คู่โหนด x --> y ที่เชื่อมต่อโดยตรงทุกคู่ใน A จะต้องเชื่อมต่อโดยตรงใน D ด้วย กล่าวได้ว่า D เป็นการประมาณที่มากเกินไปของ A

ผู้เขียนไฟล์ BUILD ต้องประกาศการพึ่งพาโดยตรงจริงทั้งหมดสำหรับกฎทุกข้อต่อระบบบิลด์อย่างชัดเจน และห้ามประกาศเพิ่มเติม

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

คุณไม่จำเป็นต้อง (และไม่ควร) พยายามแสดงรายการทั้งหมดที่นำเข้าโดยอ้อม แม้ว่า A จะต้องการ ณ เวลาที่ดำเนินการก็ตาม

ระหว่างบิลด์ของเป้าหมาย X เครื่องมือสร้างจะตรวจสอบการปิดแบบทรานซิชันทั้งหมดของทรัพยากร Dependency ของ X เพื่อให้แน่ใจว่าการเปลี่ยนแปลงในเป้าหมายเหล่านั้นแสดงในผลลัพธ์สุดท้าย รวมถึงสร้างตัวกลางใหม่ตามที่จำเป็น

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

1. ทรัพยากร Dependency ที่ประกาศตรงกับทรัพยากร Dependency จริง

ตอนแรกทุกอย่างทำงานได้ตามปกติ โค้ดในแพ็กเกจ a ใช้โค้ดในแพ็กเกจ b โค้ดในแพ็กเกจ b ใช้โค้ดในแพ็กเกจ c ดังนั้น a จึงขึ้นอยู่กับ c โดยอ้อม

a/BUILD b/BUILD
rule(
    name = "a",
    srcs = "a.in",
    deps = "//b:b",
)
      
rule(
    name = "b",
    srcs = "b.in",
    deps = "//c:c",
)
      
a / a.in b / b.in
import b;
b.foo();
    
import c;
function foo() {
  c.bar();
}
      
กราฟทรัพยากร Dependency ที่ประกาศซึ่งมีลูกศรเชื่อม a, b และ c
กราฟทรัพยากร Dependency ที่ประกาศ
กราฟทรัพยากร Dependency จริงที่ตรงกับกราฟทรัพยากร Dependency ที่ประกาศไว้ซึ่งมีลูกศรเชื่อม a, b และ c
กราฟทรัพยากร Dependency ตามจริง

ทรัพยากร Dependency ที่ประกาศไว้ใกล้เคียงกับทรัพยากร Dependency จริงมากเกินไป ทุกอย่างเรียบร้อยดี

2. การเพิ่มการพึ่งพาที่ไม่ได้ประกาศ

เกิดอันตรายแฝงเมื่อมีคนเพิ่มโค้ดไปยัง a ที่สร้างทรัพยากร Dependency จริง โดยตรงใน c แต่ลืมประกาศในไฟล์บิลด์ a/BUILD

a / a.in  
        import b;
        import c;
        b.foo();
        c.garply();
      
 
กราฟทรัพยากร Dependency ที่ประกาศซึ่งมีลูกศรเชื่อม a, b และ c
กราฟทรัพยากร Dependency ที่ประกาศไว้
กราฟ Dependency จริงที่มีลูกศรเชื่อม a, b และ c ตอนนี้ลูกศรจะเชื่อมต่อ A กับ C ด้วย ซึ่งไม่ตรงกับกราฟทรัพยากร Dependency ที่ประกาศไว้
กราฟทรัพยากร Dependency จริง

Dependency ที่ประกาศจะไม่ประมาณค่า Dependency จริงมากเกินไปอีกต่อไป วิธีนี้อาจถือว่าเป็นปัญหา เนื่องจากการปิดแบบสับเปลี่ยนของกราฟทั้ง 2 แบบเท่ากัน แต่มาสก์มีปัญหา นั่นคือ a มีการขึ้นต่อกันจริงแต่ไม่ได้ประกาศใน c

3. ความคลาดเคลื่อนระหว่างกราฟความเกี่ยวข้องที่ประกาศไว้กับกราฟความเกี่ยวข้องจริง

อันตรายจะปรากฏขึ้นเมื่อมีคนรีแฟกทอริง b เพื่อไม่ให้ขึ้นอยู่กับ c อีกต่อไป ซึ่งทำให้ a ใช้งานไม่ได้โดยไม่ตั้งใจ

  b/BUILD
 
rule(
    name = "b",
    srcs = "b.in",
    deps = "//d:d",
)
      
  b / b.in
 
      import d;
      function foo() {
        d.baz();
      }
      
กราฟทรัพยากร Dependency ที่ประกาศซึ่งมีลูกศรเชื่อมระหว่าง a กับ b
                  b ไม่ได้เชื่อมต่อกับ c อีกต่อไป ซึ่งทำให้การเชื่อมต่อของ a กับ c ขาดหายไป
กราฟทรัพยากร Dependency ที่ประกาศไว้
กราฟความเกี่ยวข้องจริงที่แสดงการเชื่อมต่อ a กับ b และ c แต่ b ไม่ได้เชื่อมต่อกับ c อีกต่อไป
กราฟทรัพยากร Dependency ตามจริง

ตอนนี้กราฟทรัพยากร Dependency ที่ประกาศไว้จะประมาณทรัพยากร Dependency จริงต่ำเกินไป แม้ว่าจะปิดแบบทรานซิทีฟแล้วก็ตาม บิลด์มีแนวโน้มที่จะดำเนินการไม่สำเร็จ

ปัญหาอาจได้รับการแก้ไขได้ด้วยการตรวจสอบว่ามีการประกาศทรัพยากร Dependency จริงจาก a ถึง c ในขั้นตอนที่ 2 อย่างถูกต้องในไฟล์ BUILD

ประเภทของทรัพยากร Dependency

กฎการสร้างส่วนใหญ่มีแอตทริบิวต์ 3 รายการสําหรับระบุข้อกําหนดทั่วไปประเภทต่างๆ ได้แก่ srcs, deps และ data โปรดดูคำอธิบายด้านล่าง โปรดดูรายละเอียดเพิ่มเติมที่หัวข้อแอตทริบิวต์ที่มีอยู่ในกฎทั้งหมด

กฎจํานวนมากยังมีแอตทริบิวต์เพิ่มเติมสําหรับประเภทของข้อกําหนดเฉพาะของกฎ เช่น compiler หรือ resources โปรดดูรายละเอียดในสารานุกรมเกี่ยวกับการสร้าง

ทรัพยากร Dependency srcs

ไฟล์ที่กฎหรือกฎที่ใช้เอาต์พุตไฟล์ต้นฉบับใช้โดยตรง

deps Dependency

กฎที่ชี้ไปยังโมดูลที่คอมไพล์แยกต่างหากซึ่งให้ไฟล์ส่วนหัว สัญลักษณ์ ไลบรารี ข้อมูล ฯลฯ

data Dependency

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

ระบบบิลด์จะทำการทดสอบในไดเรกทอรีแยกต่างหากที่มีเฉพาะไฟล์ที่แสดงเป็น data เท่านั้น ดังนั้น หากไบนารี/ไลบรารี/การทดสอบต้องใช้ไฟล์บางไฟล์เพื่อทำงาน ให้ระบุไฟล์เหล่านั้น (หรือกฎการสร้างที่มีไฟล์เหล่านั้น) ใน data เช่น

# I need a config file from a directory named env:
java_binary(
    name = "setenv",
    ...
    data = [":env/default_env.txt"],
)

# I need test data from another directory
sh_test(
    name = "regtest",
    srcs = ["regtest.sh"],
    data = [
        "//data:file1.txt",
        "//data:file2.txt",
        ...
    ],
)

ไฟล์เหล่านี้พร้อมใช้งานโดยใช้เส้นทางที่เกี่ยวข้อง path/to/data/file ในการทดสอบ คุณสามารถอ้างอิงไฟล์เหล่านี้ได้โดยรวมเส้นทางของไดเรกทอรีต้นทางของการทดสอบเข้ากับเส้นทางแบบสัมพัทธ์กับ Workspace เช่น ${TEST_SRCDIR}/workspace/path/to/data/file

การใช้ป้ายกำกับเพื่ออ้างอิงไดเรกทอรี

ขณะที่ดูไฟล์ BUILD คุณอาจเห็นว่าป้ายกำกับ data บางป้ายอ้างถึงไดเรกทอรี ป้ายกำกับเหล่านี้ลงท้ายด้วย /. หรือ / ดังตัวอย่างต่อไปนี้ ซึ่งคุณไม่ควรใช้

ไม่แนะนำdata = ["//data/regression:unittest/."]

ไม่แนะนำdata = ["testdata/."]

ไม่แนะนำdata = ["testdata/"]

วิธีนี้ดูจะสะดวกดี โดยเฉพาะสำหรับการทดสอบ เนื่องจากช่วยให้การทดสอบใช้ไฟล์ข้อมูลทั้งหมดในไดเรกทอรีได้

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

แนะนำdata = glob(["testdata/**"])

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

หากต้องใช้ป้ายกำกับไดเรกทอรี โปรดทราบว่าคุณอ้างอิงแพ็กเกจหลักด้วยเส้นทาง ../ แบบสัมพัทธ์ไม่ได้ แต่ให้ใช้เส้นทางสัมบูรณ์ เช่น //data/regression:unittest/. แทน

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

filegroup(
        name = 'my_data',
        srcs = glob(['my_unittest_data/*'])
)

จากนั้นคุณจะอ้างอิงป้ายกํากับ my_data เป็นการพึ่งพาข้อมูลในการทดสอบได้

ไฟล์ BUILD ระดับการเข้าถึง