สร้างตัวแปร

รายงานปัญหา ดูแหล่งที่มา Nightly · 8.4 · 8.3 · 8.2 · 8.1 · 8.0 · 7.6

ตัวแปร "ยี่ห้อ" เป็นตัวแปรสตริงที่ขยายได้ประเภทพิเศษซึ่งใช้ได้กับ แอตทริบิวต์ที่ทําเครื่องหมายเป็น"ขึ้นอยู่กับการแทนที่ "ตัวแปรยี่ห้อ""

ซึ่งสามารถใช้ได้ เช่น เพื่อแทรกเส้นทาง Toolchain ที่เฉพาะเจาะจงลงในการดำเนินการบิลด์ที่ผู้ใช้สร้างขึ้น

Bazel มีทั้งตัวแปรที่กำหนดไว้ล่วงหน้า ซึ่งใช้ได้กับเป้าหมายทั้งหมด และตัวแปรที่กำหนดเอง ซึ่งกำหนดไว้ในเป้าหมายการขึ้นต่อกันและใช้ได้เฉพาะกับเป้าหมายที่ขึ้นต่อกัน

เหตุผลที่ใช้คำว่า "Make" เป็นเพราะประวัติศาสตร์: เดิมทีไวยากรณ์และความหมายของ ตัวแปรเหล่านี้ตั้งใจให้ตรงกับ GNU Make

ใช้

แอตทริบิวต์ที่ทำเครื่องหมายเป็น "ขึ้นอยู่กับการแทนที่ 'สร้างตัวแปร'" สามารถ อ้างอิงตัวแปร "สร้าง" FOO ได้ดังนี้

my_attr = "prefix $(FOO) suffix"

กล่าวคือ สตริงย่อยใดๆ ที่ตรงกับ $(FOO) จะได้รับการขยาย เป็นค่าของ FOO หากค่าดังกล่าวเป็น "bar" สตริงสุดท้าย จะเป็นดังนี้

my_attr = "prefix bar suffix"

หาก FOO ไม่สอดคล้องกับตัวแปรที่เป้าหมายที่ใช้รู้จัก Bazel จะล้มเหลวพร้อมข้อผิดพลาด

ตัวแปร "Make" ที่มีชื่อเป็นสัญลักษณ์ที่ไม่ใช่ตัวอักษร เช่น @ สามารถอ้างอิงได้โดยใช้เครื่องหมายดอลลาร์เพียงอย่างเดียวโดยไม่ต้องมี วงเล็บ เช่น

my_attr = "prefix $@ suffix"

หากต้องการเขียน $ เป็นสตริงตามตัวอักษร (เช่น เพื่อป้องกันการขยายตัวแปร ) ให้เขียน $$

ตัวแปรที่กำหนดไว้ล่วงหน้า

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

หากต้องการดูรายการตัวแปรเหล่านี้และค่าของตัวแปรสำหรับชุดตัวเลือกการสร้างที่กำหนด ให้เรียกใช้

bazel info --show_make_env [build options]

และดูบรรทัดเอาต์พุตด้านบนด้วยตัวอักษรพิมพ์ใหญ่

ดูตัวอย่างตัวแปรที่กำหนดไว้ล่วงหน้า

ตัวแปรตัวเลือก Toolchain

ตัวแปรเส้นทาง

  • BINDIR: ฐานของไบนารีทรีที่สร้างขึ้นสำหรับสถาปัตยกรรมเป้าหมาย

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

    หากต้องการเรียกใช้เครื่องมือจากภายใน genrule วิธีที่แนะนำในการรับเส้นทางคือ $(execpath toolname) โดย toolname ต้องแสดงอยู่ในแอตทริบิวต์ tools ของ genrule

  • GENDIR: ฐานของโครงสร้างโค้ดที่สร้างขึ้นสำหรับสถาปัตยกรรมเป้าหมาย

ตัวแปรสถาปัตยกรรมของเครื่อง

  • TARGET_CPU: CPU ของสถาปัตยกรรมเป้าหมาย เช่น k8

ตัวแปร genrule ที่กำหนดไว้ล่วงหน้า

แอตทริบิวต์ต่อไปนี้ใช้ได้กับแอตทริบิวต์ genrule's cmd โดยเฉพาะ และโดยทั่วไปแล้วมีความสำคัญต่อการทำให้แอตทริบิวต์ดังกล่าวทำงานได้

ดูตัวอย่างตัวแปร genrule ที่กำหนดไว้ล่วงหน้า

  • OUTS: รายการoutsของ genrule หากมีไฟล์เอาต์พุตเพียงไฟล์เดียว คุณจะใช้ $@ ก็ได้
  • SRCS: รายการ genrulesrcs (หรือพูดให้ ถูกต้องยิ่งขึ้นคือชื่อเส้นทางของไฟล์ที่สอดคล้องกับป้ายกำกับในรายการ srcs) หากมีไฟล์ต้นฉบับเพียงไฟล์เดียว คุณก็ใช้ $< ได้เช่นกัน
  • <: SRCS หากเป็นไฟล์เดียว ไม่เช่นนั้นจะทริกเกอร์ ข้อผิดพลาดในการสร้าง
  • @: OUTS หากเป็นไฟล์เดียว ไม่เช่นนั้นจะทริกเกอร์ ข้อผิดพลาดในการสร้าง

  • RULEDIR: ไดเรกทอรีเอาต์พุตของเป้าหมาย ซึ่งก็คือไดเรกทอรีที่สอดคล้องกับชื่อของแพ็กเกจที่มีเป้าหมายอยู่ภายใต้ทรี genfiles หรือ bin สำหรับ //my/pkg:my_genrule จะลงท้ายด้วย my/pkg เสมอ แม้ว่าเอาต์พุตของ //my/pkg:my_genrule จะอยู่ในไดเรกทอรีย่อยก็ตาม

  • @D: ไดเรกทอรีเอาต์พุต หาก outs มีรายการเดียว การดำเนินการนี้จะขยายไปยังไดเรกทอรีที่มีไฟล์นั้น หากมีหลายรายการ รายการนี้จะขยายเป็นไดเรกทอรีรากของแพ็กเกจใน genfiles tree แม้ว่าไฟล์เอาต์พุตทั้งหมดจะอยู่ใน ไดเรกทอรีย่อยเดียวกันก็ตาม

    หมายเหตุ: ใช้ RULEDIR แทน @D เนื่องจาก RULEDIR มีความหมายที่ง่ายกว่าและทำงานในลักษณะเดียวกัน ไม่ว่าจะมีไฟล์เอาต์พุตจำนวนเท่าใดก็ตาม

    หาก genrule ต้องสร้างไฟล์ชั่วคราวระดับกลาง (อาจเป็นผลมาจากการใช้เครื่องมืออื่นๆ เช่น คอมไพเลอร์) ก็ควรพยายามเขียนไฟล์เหล่านั้นลงใน @D (แม้ว่า /tmp จะเขียนได้เช่นกัน) และนำออกก่อนที่จะเสร็จสิ้น

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

ตัวแปรเส้นทางแหล่งที่มา/เอาต์พุตที่กำหนดไว้ล่วงหน้า

ตัวแปรที่กำหนดไว้ล่วงหน้า execpath, execpaths, rootpath, rootpaths, location และ locations จะใช้พารามิเตอร์ป้ายกำกับ (เช่น $(execpath //foo:bar)) และแทนที่เส้นทางไฟล์ที่ระบุโดยป้ายกำกับนั้น

สำหรับไฟล์ต้นฉบับ นี่คือเส้นทางที่สัมพันธ์กับรูทของพื้นที่ทำงาน สำหรับไฟล์ที่เป็นเอาต์พุตของกฎ นี่คือเส้นทางเอาต์พุตของไฟล์ (ดูคำอธิบายไฟล์เอาต์พุตด้านล่าง)

ดูตัวอย่างตัวแปรเส้นทางที่กำหนดไว้ล่วงหน้า

  • execpath: ระบุเส้นทางใต้ execroot ที่ Bazel เรียกใช้การดำเนินการบิลด์

    ในตัวอย่างข้างต้น Bazel จะเรียกใช้การดำเนินการบิลด์ทั้งหมดในไดเรกทอรีที่ลิงก์ โดยbazel-myprojectลิงก์สัญลักษณ์ในรูทของพื้นที่ทำงาน ระบบได้ลิงก์ ไฟล์ต้นฉบับempty.sourceที่เส้นทาง bazel-myproject/testapp/empty.source เส้นทางที่เรียกใช้ (ซึ่งเป็นเส้นทางย่อยใต้รูท) จึงเป็น testapp/empty.source นี่คือเส้นทางที่การดำเนินการสร้างใช้เพื่อค้นหาไฟล์ได้

    ไฟล์เอาต์พุตจะจัดเตรียมในลักษณะเดียวกัน แต่จะมีคำนำหน้าเป็นเส้นทางย่อย bazel-out/cpu-compilation_mode/bin (หรือสำหรับเอาต์พุตของเครื่องมือ bazel-out/cpu-opt-exec-hash/bin) ในตัวอย่างข้างต้น //testapp:app เป็นเครื่องมือเนื่องจากปรากฏในแอตทริบิวต์ tools ของ show_app_output ดังนั้นระบบจะเขียนไฟล์เอาต์พุต app ไปยัง bazel-myproject/bazel-out/cpu-opt-exec-hash/bin/testapp/app ดังนั้นเส้นทางการดำเนินการจึงเป็น bazel-out/cpu-opt-exec-hash/bin/testapp/app คำนำหน้าเพิ่มเติมนี้ ช่วยให้สร้างเป้าหมายเดียวกันสำหรับ CPU 2 ตัวที่แตกต่างกันใน บิลด์เดียวกันได้โดยไม่ทำให้ผลลัพธ์ทับซ้อนกัน

    ป้ายกำกับที่ส่งไปยังตัวแปรนี้ต้องแสดงไฟล์เพียงไฟล์เดียว สำหรับ ป้ายกำกับที่แสดงไฟล์ต้นฉบับ จะเป็นจริงโดยอัตโนมัติ สำหรับป้ายกำกับ ที่แสดงถึงกฎ กฎต้องสร้างเอาต์พุต 1 รายการเท่านั้น หากเป็น false หรือป้ายกำกับมีรูปแบบไม่ถูกต้อง บิลด์จะล้มเหลวพร้อมข้อผิดพลาด

  • rootpath: ระบุเส้นทางที่ไบนารีที่สร้างขึ้นใช้เพื่อค้นหาทรัพยากร Dependency ในรันไทม์ที่สัมพันธ์กับไดเรกทอรีย่อยของไดเรกทอรี Runfiles ซึ่งสอดคล้องกับที่เก็บหลัก หมายเหตุ: วิธีนี้ใช้ได้เฉพาะในกรณีที่เปิดใช้ --enable_runfiles ซึ่งไม่ได้เปิดไว้โดยค่าเริ่มต้นใน Windows โปรดใช้ rlocationpath แทนเพื่อ รองรับหลายแพลตฟอร์ม

    ซึ่งคล้ายกับ execpath แต่จะนำคำนำหน้าการกำหนดค่า ที่อธิบายไว้ข้างต้นออก ในตัวอย่างจากด้านบน หมายความว่าทั้ง empty.source และ app ใช้เส้นทางที่สัมพันธ์กับพื้นที่ทำงานโดยสมบูรณ์: testapp/empty.source และ testapp/app

    rootpath ของไฟล์ในที่เก็บข้อมูลภายนอก repo จะเริ่มต้นด้วย ../repo/ ตามด้วย เส้นทางที่เกี่ยวข้องกับที่เก็บข้อมูล

    โดยมีข้อกำหนด "เอาต์พุตเดียวเท่านั้น" เหมือนกับ execpath

  • rlocationpath: เส้นทางที่ไบนารีที่สร้างขึ้นสามารถส่งไปยังฟังก์ชัน Rlocation ของไลบรารีไฟล์ที่เรียกใช้เพื่อค้นหาทรัพยากร Dependency ที่ รันไทม์ ไม่ว่าจะอยู่ในไดเรกทอรีไฟล์ที่เรียกใช้ (หากมี) หรือใช้ ไฟล์ Manifest ของไฟล์ที่เรียกใช้

    ซึ่งคล้ายกับ rootpath ตรงที่ไม่มี คำนำหน้าการกำหนดค่า แต่แตกต่างกันตรงที่ขึ้นต้นด้วย ชื่อของที่เก็บเสมอ ในตัวอย่างจากด้านบน หมายความว่า empty.source และ app จะทำให้เกิดเส้นทาง myproject/testapp/empty.source และ myproject/testapp/app

    rlocationpath ของไฟล์ในที่เก็บข้อมูลภายนอก repo จะเริ่มต้นด้วย repo/ ตามด้วย เส้นทางที่เกี่ยวข้องกับที่เก็บข้อมูล

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

    โดยมีข้อกำหนด "เอาต์พุตเดียวเท่านั้น" เหมือนกับ execpath

  • location: คำพ้องความหมายของ execpath หรือ rootpath ขึ้นอยู่กับแอตทริบิวต์ที่ขยาย นี่คือลักษณะการทำงานแบบเดิมก่อน Starlark และไม่แนะนำให้ใช้เว้นแต่คุณจะทราบจริงๆ ว่าลักษณะการทำงานนี้มีผลต่อกฎใดกฎหนึ่ง ดูรายละเอียดได้ที่ #2475

execpaths, rootpaths, rlocationpaths และ locations เป็นรูปแบบพหูพจน์ของ execpath, rootpath, rlocationpaths และ location ตามลำดับ โดยจะรองรับค่ายเพลงที่ผลิตผลงานหลายรายการ ในกรณีนี้ แต่ละผลงานจะแสดงโดยคั่นด้วยช่องว่าง กฎที่ไม่มีเอาต์พุตและป้ายกำกับที่รูปแบบไม่ถูกต้อง จะทำให้เกิดข้อผิดพลาดในการบิลด์

ป้ายกำกับที่อ้างอิงทั้งหมดต้องปรากฏใน srcs, ไฟล์เอาต์พุตของเป้าหมายที่ใช้ หรือ deps มิฉะนั้นการสร้างจะล้มเหลว เป้าหมาย C++ ยังอ้างอิงป้ายกำกับใน data ได้ด้วย

ป้ายกำกับไม่จำเป็นต้องอยู่ในรูปแบบ Canonical เช่น foo, :foo และ //somepkg:foo ก็ใช้ได้

ตัวแปรที่กำหนดเอง

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

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

ตัวแปร Toolchain ของ C++

ต่อไปนี้เป็นสิ่งที่กำหนดไว้ในกฎของเครื่องมือ C++ และพร้อมใช้งานสำหรับกฎใดก็ตาม ที่ตั้งค่า toolchains = ["@bazel_tools//tools/cpp:current_cc_toolchain"] กฎบางอย่าง เช่น java_binary จะรวมเครื่องมือ C++ ไว้ในการกำหนดกฎโดยนัย โดยจะรับค่าตัวแปรเหล่านี้ โดยอัตโนมัติ

กฎ C++ ในตัวมีความซับซ้อนมากกว่า "เรียกใช้คอมไพเลอร์ใน นั้น" มาก เพื่อให้รองรับโหมดการคอมไพล์ที่หลากหลาย เช่น *SAN, ThinLTO ที่มี/ไม่มีโมดูล และไบนารีที่ได้รับการเพิ่มประสิทธิภาพอย่างรอบคอบ พร้อมๆ กับ การทดสอบที่รวดเร็วบนหลายแพลตฟอร์ม กฎในตัวจึงต้องใช้ความพยายามอย่างมาก เพื่อให้มั่นใจว่าได้ตั้งค่าอินพุต เอาต์พุต และแฟล็กบรรทัดคำสั่งที่ถูกต้อง ในการดำเนินการแต่ละอย่างที่อาจมีหลายรายการซึ่งสร้างขึ้นภายใน

ตัวแปรเหล่านี้เป็นกลไกสำรองที่ผู้เชี่ยวชาญด้านภาษาใช้ในกรณีที่พบได้ยาก หากคุณต้องการใช้ฟีเจอร์เหล่านี้ โปรดติดต่อผู้พัฒนา Bazel ก่อน

  • ABI: เวอร์ชัน ABI ของ C++
  • AR: คำสั่ง "ar" จาก crosstool
  • C_COMPILER: ตัวระบุคอมไพเลอร์ C/C++ เช่น llvm

  • CC: คำสั่งคอมไพเลอร์ C และ C++

    เราขอแนะนำอย่างยิ่งให้ใช้ CC_FLAGS ร่วมกับ CC เสมอ คุณต้องยอมรับความเสี่ยงเองหากไม่ทำตาม

  • CC_FLAGS: ชุดแฟล็กขั้นต่ำสำหรับคอมไพเลอร์ C/C++ เพื่อให้ genrules ใช้ได้ โดยเฉพาะอย่างยิ่ง ตัวแปรนี้มีแฟล็กสำหรับ เลือกสถาปัตยกรรมที่ถูกต้องหาก CC รองรับหลายสถาปัตยกรรม
  • NM: คำสั่ง "nm" จาก crosstool
  • OBJCOPY: คำสั่ง objcopy จากชุดเดียวกันกับคอมไพเลอร์ C/C++
  • STRIP: คำสั่ง strip จากชุดเดียวกันกับคอมไพเลอร์ C/C++

ตัวแปรของชุดเครื่องมือ Java

รายการต่อไปนี้กำหนดไว้ในกฎของเครื่องมือเชน Java และใช้ได้กับกฎใดก็ตาม ที่ตั้งค่า toolchains = ["@bazel_tools//tools/jdk:current_java_runtime"] (หรือ "@bazel_tools//tools/jdk:current_host_java_runtime" สำหรับเครื่องมือเชนโฮสต์ที่เทียบเท่า)

ไม่ควรใช้เครื่องมือส่วนใหญ่ใน JDK โดยตรง กฎ Java ในตัวใช้แนวทางที่ซับซ้อนกว่ามากในการคอมไพล์และแพ็กเกจ Java กว่าที่เครื่องมือต้นทางจะแสดงได้ เช่น JAR ของอินเทอร์เฟซ, JAR ของอินเทอร์เฟซส่วนหัว และแพ็กเกจ JAR ที่ได้รับการเพิ่มประสิทธิภาพอย่างมาก รวมถึงการผสานรวม

ตัวแปรเหล่านี้เป็นกลไกสำรองที่ผู้เชี่ยวชาญด้านภาษาใช้ในกรณีที่พบได้ยาก หากคุณต้องการใช้ฟีเจอร์เหล่านี้ โปรดติดต่อผู้พัฒนา Bazel ก่อน

  • JAVA: คำสั่ง "java" (เครื่องเสมือน Java ) โปรดหลีกเลี่ยงการดำเนินการนี้และใช้กฎ java_binary แทนหากเป็นไปได้ อาจเป็นเส้นทางแบบสัมพัทธ์ หากต้องเปลี่ยน ไดเรกทอรี ก่อนเรียกใช้ java คุณจะต้องบันทึก ไดเรกทอรีการทำงานก่อนที่จะเปลี่ยน
  • JAVABASE: ไดเรกทอรีฐานที่มี ยูทิลิตี Java อาจเป็นเส้นทางแบบสัมพัทธ์ จะมีไดเรกทอรีย่อย "bin"

ตัวแปรที่กำหนดโดย Starlark

ผู้เขียนกฎและชุดเครื่องมือสามารถกำหนดตัวแปรที่กำหนดเองทั้งหมดได้โดยการส่งคืนผู้ให้บริการ TemplateVariableInfo กฎใดๆ ที่ขึ้นอยู่กับแอตทริบิวต์เหล่านี้ผ่านแอตทริบิวต์ toolchains จะอ่านค่าได้

ดูตัวอย่างตัวแปรที่กำหนดโดย Starlark