คําจํากัดความที่พบบ่อย

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

ส่วนนี้จะกําหนดคําศัพท์และแนวคิดต่างๆ ที่พบได้ทั่วไปในฟังก์ชันหรือกฎการสร้างหลายรายการ

เนื้อหา

การแปลงข้อมูลเป็นโทเค็นของ Bourne Shell

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

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

โดยปกติแล้วแอตทริบิวต์ที่อยู่ภายใต้การขยายตัวแปร "Make" และการจัดทําโทเค็นของ Bourne shell จะใช้สำหรับการส่งตัวเลือกที่ไม่เจาะจงไปยังคอมไพเลอร์และเครื่องมืออื่นๆ ตัวอย่างแอตทริบิวต์ดังกล่าว ได้แก่ cc_library.copts และ java_library.javacopts การใช้แทนเหล่านี้ช่วยให้ตัวแปรสตริงเดียวขยายเป็นรายการคำตัวเลือกเฉพาะการกำหนดค่าได้

การขยายป้ายกำกับ

แอตทริบิวต์สตริงบางรายการของกฎเพียงไม่กี่รายการจะขึ้นอยู่กับการขยายป้ายกำกับ: หากสตริงเหล่านั้นมีป้ายกำกับที่ถูกต้องเป็นสตริงย่อย เช่น //mypkg:target และป้ายกำกับนั้นเป็นข้อกําหนดเบื้องต้นที่ประกาศไว้ของกฎปัจจุบัน ระบบจะขยายป้ายกำกับนั้นให้เป็นเส้นทางของไฟล์ที่แสดงโดย target //mypkg:target

ตัวอย่างแอตทริบิวต์ ได้แก่ genrule.cmd และ cc_binary.linkopts รายละเอียดอาจแตกต่างกันอย่างมากในแต่ละกรณี เช่น มีการขยายป้ายกำกับแบบสัมพัทธ์หรือไม่ วิธีจัดการป้ายกำกับที่ขยายไปยังหลายไฟล์ เป็นต้น โปรดดูรายละเอียดในเอกสารประกอบของแอตทริบิวต์กฎ

แอตทริบิวต์ทั่วไปที่กฎการสร้างส่วนใหญ่กำหนด

ส่วนนี้อธิบายแอตทริบิวต์ที่กฎการสร้างหลายข้อกำหนดไว้ แต่ไม่ใช่ทั้งหมด

แอตทริบิวต์ คำอธิบาย
data

รายการป้ายกํากับ ค่าเริ่มต้นคือ []

ไฟล์ที่จําเป็นสําหรับกฎนี้เมื่อรันไทม์ อาจแสดงรายการเป้าหมายของไฟล์หรือกฎ โดยทั่วไปแล้วอนุญาตให้ใช้เป้าหมายใดก็ได้

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

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

deps

รายการป้ายกํากับ ค่าเริ่มต้นคือ []

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

โดยทั่วไป กฎเฉพาะภาษาจะจํากัดเป้าหมายที่แสดงไว้ให้ผู้ให้บริการที่เฉพาะเจาะจงเท่านั้น

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

ส่วนใหญ่แล้ว จะใช้ deps Dependency เพื่ออนุญาตให้โมดูลหนึ่งใช้สัญลักษณ์ที่กําหนดไว้ในโมดูลอื่นซึ่งเขียนด้วยภาษาโปรแกรมเดียวกันและคอมไพล์แยกกัน นอกจากนี้ ระบบยังอนุญาตให้ใช้การพึ่งพาข้ามภาษาในหลายกรณี เช่น เป้าหมาย java_library อาจใช้โค้ด C++ ในเป้าหมาย cc_library โดยระบุเป้าหมายหลังในแอตทริบิวต์ deps ดูข้อมูลเพิ่มเติมได้ที่คำจำกัดความของทรัพยากร Dependencies

licenses

รายการสตริง ไม่สามารถกําหนดค่าได้ ค่าเริ่มต้นคือ ["none"]

รายการสตริงประเภทใบอนุญาตที่จะใช้กับเป้าหมายนี้ ซึ่งเป็นส่วนหนึ่งของ API การอนุญาตให้ใช้สิทธิที่เลิกใช้งานแล้วซึ่ง Bazel ไม่ได้ใช้อีกต่อไป อย่าใช้

srcs

รายการป้ายกํากับ ค่าเริ่มต้นคือ []

ไฟล์ที่กฎนี้ประมวลผลหรือรวมไว้ โดยทั่วไปจะแสดงไฟล์โดยตรง แต่อาจแสดงเป้าหมายของกฎ (เช่น filegroup หรือ genrule) เพื่อรวมเอาเอาต์พุตเริ่มต้นของกฎ

กฎสำหรับภาษาใดภาษาหนึ่งมักกำหนดให้ไฟล์ที่ระบุมีส่วนขยายไฟล์ที่เฉพาะเจาะจง

แอตทริบิวต์ที่ใช้ร่วมกันสำหรับกฎการสร้างทั้งหมด

ส่วนนี้อธิบายแอตทริบิวต์ที่เพิ่มโดยนัยลงในกฎการสร้างทั้งหมด

แอตทริบิวต์ คำอธิบาย
compatible_with

รายการป้ายกํากับ; ไม่สามารถกําหนดค่าได้; ค่าเริ่มต้นคือ []

รายการสภาพแวดล้อมที่สร้างเป้าหมายนี้ได้ นอกเหนือจากสภาพแวดล้อมที่รองรับโดยค่าเริ่มต้น

ซึ่งเป็นส่วนหนึ่งของระบบข้อจำกัดของ Bazel ซึ่งช่วยให้ผู้ใช้ประกาศว่าเป้าหมายใดบ้างที่สามารถใช้ร่วมกันได้และไม่ได้ เช่น ไฟล์ไบนารีที่นำไปใช้งานได้ภายนอกไม่ควรขึ้นอยู่กับไลบรารีที่มีโค้ดลับของบริษัท ดูรายละเอียดได้ที่ ConstraintSemantics

deprecation

สตริง ไม่สามารถกําหนดค่าได้ ค่าเริ่มต้นคือ None

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

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

ไลบรารีภายในแพ็กเกจจะได้รับการยกเว้นจากคำเตือนนี้ เช่น การสร้างการทดสอบของกฎที่เลิกใช้งานจะไม่แสดงคำเตือน

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

เมื่อผู้ใช้หยุดใช้แล้ว คุณก็นำเป้าหมายออกได้

distribs

รายการสตริง ไม่สามารถกําหนดค่าได้ ค่าเริ่มต้นคือ []

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

exec_compatible_with

รายการป้ายกํากับ; ไม่สามารถกําหนดค่าได้; ค่าเริ่มต้นคือ []

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

exec_properties

พจนานุกรมสตริง โดยค่าเริ่มต้นคือ {}

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

หากคีย์มีอยู่ในทั้งพร็อพเพอร์ตี้ระดับแพลตฟอร์มและระดับเป้าหมาย ระบบจะนำค่าจากเป้าหมาย
features

รายการสตริงฟีเจอร์ ค่าเริ่มต้นคือ []

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

ระบบจะรวมแอตทริบิวต์ features นี้เข้ากับแอตทริบิวต์ features ระดับ แพ็กเกจ เช่น หากเปิดใช้ฟีเจอร์ ["a", "b"] ที่ระดับแพ็กเกจ และแอตทริบิวต์ features ของเป้าหมายมี ["-a", "c"] ฟีเจอร์ที่เปิดใช้สำหรับกฎจะเป็น "b" และ "c" ดูตัวอย่าง

restricted_to

รายการป้ายกํากับ; ไม่สามารถกําหนดค่าได้; ค่าเริ่มต้นคือ []

รายการสภาพแวดล้อมที่สามารถสร้างเป้าหมายนี้ได้แทนสภาพแวดล้อมที่รองรับโดยค่าเริ่มต้น

ซึ่งเป็นส่วนหนึ่งของระบบข้อจำกัดของ Bazel ดูรายละเอียดได้ที่ compatible_with

tags

รายการสตริง ไม่สามารถกําหนดค่าได้ ค่าเริ่มต้นคือ []

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

Bazel จะแก้ไขลักษณะการทํางานของโค้ดแซนด์บ็อกซ์หากพบคีย์เวิร์ดต่อไปนี้ในแอตทริบิวต์ tags ของการทดสอบหรือเป้าหมาย genrule หรือคีย์ของ execution_requirements สําหรับการดำเนินการ Starlark

  • คีย์เวิร์ด no-sandbox จะทำให้การดำเนินการหรือการทดสอบไม่อยู่ในแซนด์บ็อกซ์ การดำเนินการหรือทดสอบดังกล่าวจะยังคงแคชหรือทำงานจากระยะไกลได้ ใช้ no-cache หรือ no-remote เพื่อป้องกันการดําเนินการหรือทดสอบดังกล่าว
  • คีย์เวิร์ด no-cache ส่งผลให้การดําเนินการหรือการทดสอบไม่มีการแคชไว้ (ทั้งแบบในเครื่องหรือจากระยะไกล) หมายเหตุ: สําหรับวัตถุประสงค์ของแท็กนี้ ระบบจะถือว่าแคชดิสก์เป็นแคชในเครื่อง ส่วนแคช HTTP และ gRPC จะถือว่าอยู่ระยะไกล แคชอื่นๆ เช่น Skyframe หรือแคชการดำเนินการถาวรจะไม่ได้รับผลกระทบ
  • คีย์เวิร์ด no-remote-cache ส่งผลให้การดำเนินการหรือการทดสอบไม่ได้รับการแคชจากระยะไกล (แต่อาจมีการแคชในเครื่องและอาจดำเนินการจากระยะไกลได้) หมายเหตุ: สําหรับวัตถุประสงค์ของแท็กนี้ ระบบจะถือว่าแคชดิสก์เป็นแคชในเครื่อง ส่วนแคช HTTP และ gRPC จะถือว่าอยู่ระยะไกล แคชอื่นๆ เช่น Skyframe หรือแคชการดำเนินการถาวรจะไม่ได้รับผลกระทบ หากใช้แคชในดิสก์ในเครื่องและแคชระยะไกลร่วมกัน (แคชแบบรวม) ระบบจะถือว่าแคชดังกล่าวเป็นแคชระยะไกลและปิดใช้โดยสมบูรณ์ เว้นแต่จะมีการตั้งค่า --incompatible_remote_results_ignore_disk ซึ่งในกรณีนี้ระบบจะใช้คอมโพเนนต์ในเครื่อง
  • คีย์เวิร์ด no-remote-exec ทําให้การดำเนินการหรือการทดสอบไม่ทํางานจากระยะไกล (แต่อาจแคชไว้จากระยะไกล)
  • คีย์เวิร์ด no-remote ป้องกันไม่ให้ดำเนินการหรือทดสอบจากระยะไกลหรือแคชจากระยะไกล ซึ่งเทียบเท่ากับการใช้ทั้ง no-remote-cache และ no-remote-exec
  • คีย์เวิร์ด no-remote-cache-upload ปิดใช้การอัปโหลดส่วนหนึ่งของแคชระยะไกลของการเกิด แต่จะไม่ได้ปิดใช้การเรียกใช้จากระยะไกล
  • คีย์เวิร์ด local ป้องกันไม่ให้ระบบแคชการดำเนินการหรือการทดสอบจากระยะไกล เรียกใช้จากระยะไกล หรือเรียกใช้ภายในแซนด์บ็อกซ์ สําหรับ genrules และการทดสอบ การทําเครื่องหมายกฎด้วยแอตทริบิวต์ local = True จะมีผลเหมือนกัน
  • คีย์เวิร์ด requires-network อนุญาตให้เข้าถึงเครือข่ายภายนอกจากภายในแซนด์บ็อกซ์ แท็กนี้จะมีผลก็ต่อเมื่อเปิดใช้แซนด์บ็อกซ์เท่านั้น
  • คีย์เวิร์ด block-network จะบล็อกการเข้าถึงเครือข่ายภายนอกจากภายในแซนด์บ็อกซ์ ในกรณีนี้ ระบบจะอนุญาตเฉพาะการสื่อสารกับ localhost เท่านั้น แท็กนี้จะมีผลก็ต่อเมื่อเปิดใช้แซนด์บ็อกซ์เท่านั้น
  • requires-fakeroot เรียกใช้การทดสอบหรือการดำเนินการโดย uid และ gid 0 (เช่น ผู้ใช้รูท) การดำเนินการนี้มีการสนับสนุนเฉพาะใน Linux เท่านั้น แท็กนี้จะมีความสำคัญเหนือตัวเลือกบรรทัดคำสั่ง --sandbox_fake_username

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

Bazel จะแก้ไขลักษณะการทํางานของการทดสอบหากพบคีย์เวิร์ดต่อไปนี้ในแอตทริบิวต์ tags ของกฎการทดสอบ

  • exclusive จะบังคับให้ทำการทดสอบในโหมด "พิเศษ" เพื่อให้มั่นใจว่าไม่มีการทดสอบอื่นทำงานอยู่พร้อมกัน การทดสอบดังกล่าวจะดำเนินการตามลำดับหลังจากกิจกรรมการสร้างและการทดสอบที่ไม่ใช่แบบเฉพาะตัวทั้งหมดเสร็จสมบูรณ์แล้ว ระบบจะปิดใช้การดําเนินการจากระยะไกลสําหรับการทดสอบดังกล่าวเนื่องจาก Bazel ไม่สามารถควบคุมสิ่งที่ทํางานบนเครื่องระยะไกลได้
  • exclusive-if-local จะบังคับให้เรียกใช้การทดสอบในโหมด "พิเศษ" หากเรียกใช้จากเครื่อง แต่จะใช้การทดสอบแบบขนานหากเรียกใช้จากระยะไกล
  • คีย์เวิร์ด manual จะยกเว้นเป้าหมายจากการขยายไวลด์การ์ดรูปแบบเป้าหมาย (..., :*, :all ฯลฯ) และกฎ test_suite ซึ่งไม่ได้แสดงการทดสอบอย่างชัดเจนเมื่อคํานวณชุดเป้าหมายระดับบนสุดที่จะสร้าง/เรียกใช้สําหรับคําสั่ง build, test และ coverage แต่จะไม่ได้ส่งผลต่อการขยายไวลด์การ์ดเป้าหมายหรือชุดทดสอบในบริบทอื่นๆ รวมถึงคำสั่ง query โปรดทราบว่า manual ไม่ได้หมายความว่าไม่ควรสร้าง/เรียกใช้เป้าหมายโดยอัตโนมัติจากระบบการบิลด์/ทดสอบอย่างต่อเนื่อง เช่น คุณอาจต้องการยกเว้นเป้าหมายจาก bazel test ... เนื่องจากต้องใช้ Flag ของ Bazel ที่เฉพาะเจาะจง แต่ยังคงรวมเป้าหมายนั้นไว้ในการเรียกใช้การทดสอบก่อนส่งหรือทดสอบอย่างต่อเนื่องที่กําหนดค่าอย่างถูกต้อง
  • คีย์เวิร์ด external จะบังคับให้ทดสอบโดยไม่มีเงื่อนไข (โดยไม่คำนึงถึงค่า --cache_test_results)
ดูรูปแบบเพิ่มเติมเกี่ยวกับแท็กที่แนบกับเป้าหมายการทดสอบได้ที่รูปแบบแท็กในสารานุกรมการทดสอบ
target_compatible_with

รายการป้ายกํากับ ค่าเริ่มต้นคือ []

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

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

รายการว่าง (ซึ่งเป็นค่าเริ่มต้น) หมายความว่าเป้าหมายเข้ากันได้กับทุกแพลตฟอร์ม

กฎทั้งหมดที่ไม่ใช่กฎ Workspace รองรับแอตทริบิวต์นี้ สําหรับกฎบางรายการ แอตทริบิวต์นี้จะไม่มีผล เช่น การระบุ target_compatible_with สำหรับ cc_toolchain นั้นไม่มีประโยชน์

ดูข้อมูลเพิ่มเติมเกี่ยวกับการข้ามเป้าหมายที่เข้ากันไม่ได้ได้ที่หน้าแพลตฟอร์ม

testonly

บูลีน ไม่สามารถกําหนดค่าได้ ค่าเริ่มต้นคือ False ยกเว้นเป้าหมายการทดสอบและชุดทดสอบ

หากเป็น True จะมีเพียงเป้าหมายทดสอบเท่านั้น (เช่น การทดสอบ) ที่สามารถใช้เป้าหมายนี้ได้

หรือกล่าวอีกนัยหนึ่งคือ กฎที่ไม่ใช่ testonly จะต้องไม่อิงตามกฎที่เป็น testonly

การทดสอบ (กฎ *_test) และชุดทดสอบ (กฎ test_suite) จะเป็น testonly โดยค่าเริ่มต้น

แอตทริบิวต์นี้มีไว้เพื่อระบุว่าเป้าหมายไม่ควรอยู่ในไบนารีที่เผยแพร่ไปยังเวอร์ชันที่ใช้งานจริง

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

toolchains

รายการป้ายกํากับ; ไม่สามารถกําหนดค่าได้; ค่าเริ่มต้นคือ []

ชุดเป้าหมายที่มีสร้างตัวแปรซึ่งเป้าหมายนี้ได้รับอนุญาตให้เข้าถึง เป้าหมายเหล่านี้คืออินสแตนซ์ของกฎที่ให้ TemplateVariableInfo หรือเป้าหมายพิเศษสำหรับประเภทเครื่องมือที่อยู่ใน Bazel ซึ่งรวมถึง

  • @bazel_tools//tools/cpp:toolchain_type
  • @rules_java//toolchains:current_java_runtime

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

visibility

รายการป้ายกํากับ; ไม่สามารถกําหนดค่าได้; ค่าเริ่มต้นจะแตกต่างกันไป

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

สําหรับเป้าหมายที่ประกาศในไฟล์ BUILD โดยตรงหรือในมาโครเดิมที่เรียกใช้จากไฟล์ BUILD ค่าเริ่มต้นคือ default_visibility ของแพ็กเกจ หากระบุไว้ หรือ ["//visibility:private"] สําหรับเป้าหมายที่ประกาศในมาโครสัญลักษณ์อย่างน้อย 1 รายการ ค่าเริ่มต้นจะเป็น ["//visibility:private"] เสมอ (ซึ่งทําให้ใช้ได้ภายในแพ็กเกจที่มีโค้ดของมาโครเท่านั้น)

แอตทริบิวต์ที่ใช้ร่วมกันกับกฎทดสอบทั้งหมด (*_test)

ส่วนนี้อธิบายแอตทริบิวต์ที่ใช้ร่วมกันกับกฎทดสอบทั้งหมด

แอตทริบิวต์ คำอธิบาย
args

รายการสตริง ขึ้นอยู่กับการแทนที่ $(location) และ "Make variable" รวมถึง การแยกสตริงของ Bourne Shell ค่าเริ่มต้นคือ []

อาร์กิวเมนต์บรรทัดคำสั่งที่ Bazel ส่งไปยังเป้าหมายเมื่อเรียกใช้ด้วย bazel test

ระบบจะส่งอาร์กิวเมนต์เหล่านี้ก่อนค่า --test_arg ที่ระบุไว้ในบรรทัดคำสั่ง bazel test

env

พจนานุกรมสตริง ค่าจะขึ้นอยู่กับการแทนที่ $(location) และ "Make variable" ค่าเริ่มต้นคือ {}

ระบุตัวแปรสภาพแวดล้อมเพิ่มเติมที่จะตั้งค่าเมื่อทำการทดสอบโดย bazel test

แอตทริบิวต์นี้ใช้กับกฎเนทีฟเท่านั้น เช่น cc_test, py_test และ sh_test แต่จะไม่มีผลกับกฎการทดสอบที่ Starlark กำหนด สําหรับกฎ Starlark ของคุณเอง คุณสามารถเพิ่มแอตทริบิวต์ "env" และใช้เพื่อป้อนข้อมูลผู้ให้บริการ TestEnvironment ได้

env_inherit

รายการสตริง ค่าเริ่มต้นคือ []

ระบุตัวแปรสภาพแวดล้อมเพิ่มเติมที่จะรับค่าจากสภาพแวดล้อมภายนอกเมื่อ bazel test ทำการทดสอบ

แอตทริบิวต์นี้ใช้กับกฎเนทีฟเท่านั้น เช่น cc_test, py_test และ sh_test แต่จะมีผลกับกฎการทดสอบที่ Starlark กำหนด

size

สตริง "enormous", "large", "medium" หรือ "small"ไม่สามารถกําหนดค่าได้ค่าเริ่มต้นคือ "medium"

ระบุ "ความซับซ้อน" ของเป้าหมายการทดสอบ: ระยะเวลา/ทรัพยากรที่จําเป็นในการเรียกใช้

การทดสอบหน่วยถือว่า "เล็ก" การทดสอบการผสานรวมถือว่า "กลาง" และการทดสอบจากต้นทางถึงปลายทางถือว่า "ใหญ่" หรือ "ใหญ่มาก" Bazel ใช้ขนาดเพื่อกำหนดการหมดเวลาเริ่มต้น ซึ่งสามารถลบล้างได้โดยใช้แอตทริบิวต์ timeout การหมดเวลาจะมีผลกับการทดสอบทั้งหมดในเป้าหมาย BUILD ไม่ใช่การทดสอบแต่ละรายการ เมื่อทำการทดสอบในเครื่อง size จะใช้เพื่อวัตถุประสงค์ในการกำหนดเวลาเพิ่มเติมด้วย โดย Bazel จะพยายามปฏิบัติตาม --local_{ram,cpu}_resources และไม่ให้เครื่องทำงานหนักเกินไปด้วยการเรียกใช้การทดสอบที่หนักหน่วงหลายรายการพร้อมกัน

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

ขนาด RAM (เป็น MB) CPU (ในแกน CPU) การหมดเวลาเริ่มต้น
เล็ก 20 1 สั้น (1 นาที)
ปานกลาง 100 1 ปานกลาง (5 นาที)
ใหญ่ 300 1 ยาว (15 นาที)
มหาศาล 800 1 ถาวร (60 นาที)

ระบบจะตั้งค่าตัวแปรสภาพแวดล้อม TEST_SIZE เป็นค่าของแอตทริบิวต์นี้เมื่อสร้างการทดสอบ

timeout

สตริง "short", "moderate", "long" หรือ "eternal"; ค่าเริ่มต้นที่กำหนดค่าไม่ได้จะมาจากแอตทริบิวต์ size ของการทดสอบ

ระยะเวลาที่คาดว่าการทดสอบจะทํางานก่อนที่จะแสดงผล

แม้ว่าแอตทริบิวต์ขนาดของการทดสอบจะควบคุมการประมาณทรัพยากร แต่คุณก็ตั้งค่าการหมดเวลาของการทดสอบแยกต่างหากได้ หากไม่ได้ระบุไว้อย่างชัดเจน ระบบจะกำหนดเวลาหมดอายุตามขนาดของการทดสอบ คุณลบล้างการหมดเวลาการทดสอบได้ด้วย Flag --test_timeout เช่น สำหรับการทํางานภายใต้เงื่อนไขบางอย่างที่ทราบว่าทํางานช้า ค่าระยะหมดเวลาการทดสอบ สอดคล้องกับระยะเวลาต่อไปนี้

ค่าระยะหมดเวลา ระยะเวลา
วิดีโอสั้น 1 นาที
ปานกลาง 5 นาที
ยาว 15 นาที
นิรันดร์ 60 นาที

สำหรับเวลาที่ไม่ใช่เวลาข้างต้น คุณสามารถลบล้างการหมดเวลาการทดสอบได้ด้วย--test_timeout Flag bazel เช่น สำหรับการเรียกใช้ด้วยตนเองภายใต้เงื่อนไขที่ทราบกันว่าช้า ค่า --test_timeout จะแสดงเป็นวินาที เช่น --test_timeout=120 จะตั้งค่าการหมดเวลาทดสอบเป็น 2 นาที

ระบบจะตั้งค่าตัวแปรสภาพแวดล้อม TEST_TIMEOUT เป็นระยะหมดเวลาการทดสอบ (เป็นวินาที) เมื่อสร้างการทดสอบ

flaky

บูลีน ไม่สามารถกําหนดค่าได้ ค่าเริ่มต้นคือ False

ทําเครื่องหมายการทดสอบว่าไม่น่าเชื่อถือ

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

shard_count

จํานวนเต็มที่ไม่ติดลบซึ่งน้อยกว่าหรือเท่ากับ 50 ค่าเริ่มต้นคือ -1

ระบุจํานวนชาร์ดแบบขนานที่จะใช้เพื่อเรียกใช้การทดสอบ

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

หากเปิดใช้การแยกกลุ่มการทดสอบ ระบบจะตั้งค่าตัวแปรสภาพแวดล้อม TEST_TOTAL_SHARDS เป็นค่านี้เมื่อสร้างการทดสอบ

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

ดูรายละเอียดการแยกกลุ่มได้ที่หัวข้อการแยกกลุ่มทดสอบในสารานุกรมการทดสอบ
local

บูลีน ไม่สามารถกําหนดค่าได้ ค่าเริ่มต้นคือ False

บังคับให้เรียกใช้การทดสอบในเครื่องโดยไม่ต้องใช้แซนด์บ็อกซ์

การตั้งค่านี้เป็น True เทียบเท่ากับการให้แท็ก "local" (tags=["local"])

แอตทริบิวต์ที่ใช้ร่วมกันสำหรับกฎไบนารีทั้งหมด (*_binary)

ส่วนนี้อธิบายแอตทริบิวต์ที่ใช้ร่วมกันกับกฎไบนารีทั้งหมด

แอตทริบิวต์ คำอธิบาย
args

รายการสตริง ขึ้นอยู่กับการแทนที่ $(location) และ "Make variable" และ การแยกสตริงของ Bourne Shell ไม่สามารถกำหนดค่าได้ โดยค่าเริ่มต้นคือ []

อาร์กิวเมนต์บรรทัดคำสั่งที่ Bazel จะส่งไปยังเป้าหมายเมื่อมีการเรียกใช้ ไม่ว่าจะด้วยคำสั่ง run หรือเป็นการทดสอบ ระบบจะส่งอาร์กิวเมนต์เหล่านี้ก่อนอาร์กิวเมนต์ที่ระบุไว้ในบรรทัดคำสั่ง bazel run หรือ bazel test

หมายเหตุ: ระบบจะไม่ส่งอาร์กิวเมนต์เมื่อคุณเรียกใช้เป้าหมายนอก Bazel (เช่น โดยการเรียกใช้ไบนารีใน bazel-bin/ ด้วยตนเอง)

env

พจนานุกรมสตริง ค่าจะขึ้นอยู่กับการแทนที่ $(location) และ "Make variable" ค่าเริ่มต้นคือ {}

ระบุตัวแปรสภาพแวดล้อมเพิ่มเติมที่จะตั้งค่าเมื่อ bazel run เรียกใช้เป้าหมาย

แอตทริบิวต์นี้ใช้กับกฎเนทีฟเท่านั้น เช่น cc_binary, py_binary และ sh_binary แต่จะมีผลกับกฎที่เรียกใช้ได้ซึ่ง Starlark กำหนด

หมายเหตุ: ระบบจะไม่ตั้งค่าตัวแปรสภาพแวดล้อมเมื่อคุณเรียกใช้เป้าหมายนอก Bazel (เช่น โดยการเรียกใช้ไบนารีใน bazel-bin/ ด้วยตนเอง)

output_licenses

รายการสตริง ค่าเริ่มต้นคือ []

ใบอนุญาตของไฟล์เอาต์พุตที่ไบนารีนี้สร้างขึ้น ซึ่งเป็นส่วนหนึ่งของ API การอนุญาตให้ใช้สิทธิที่เลิกใช้งานแล้วซึ่ง Bazel ไม่ได้ใช้อีกต่อไป อย่าใช้

แอตทริบิวต์ที่กำหนดค่าได้

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

ตัวอย่างต่อไปนี้จะประกาศแหล่งที่มาที่แตกต่างกันสำหรับสถาปัตยกรรมเป้าหมายที่แตกต่างกัน การใช้ bazel build :multiplatform_lib --cpu x86 จะสร้างเป้าหมายโดยใช้ x86_impl.cc ส่วนการใช้ --cpu arm แทนจะทำให้ใช้ arm_impl.cc แทน 

cc_library(
    name = "multiplatform_lib",
    srcs = select({
        ":x86_mode": ["x86_impl.cc"],
        ":arm_mode": ["arm_impl.cc"]
    })
)
config_setting(
    name = "x86_mode",
    values = { "cpu": "x86" }
)
config_setting(
    name = "arm_mode",
    values = { "cpu": "arm" }
)

ฟังก์ชัน select() จะเลือกค่าทางเลือกต่างๆ สําหรับแอตทริบิวต์ที่กำหนดค่าได้ โดยอิงตามเกณฑ์ config_setting หรือ constraint_value ที่การกําหนดค่าของเป้าหมายเป็นไปตามเกณฑ์

Bazel จะประเมินแอตทริบิวต์ที่กำหนดค่าได้หลังจากประมวลผลมาโครและก่อนประมวลผลกฎ (ในทางเทคนิคคือระหว่าง ระยะการโหลดและการวิเคราะห์) การประมวลผลก่อนการประเมิน select() จะไม่ทราบว่า select() จะเลือกสาขาใด ตัวอย่างเช่น มาโครจะเปลี่ยนลักษณะการทำงานตามสาขาที่เลือกไม่ได้ และbazel queryจะเดาอย่างถี่ถ้วนเกี่ยวกับข้อกำหนดที่พารามิเตอร์เป้าหมายกำหนดได้เท่านั้น ดูข้อมูลเพิ่มเติมเกี่ยวกับการใช้ select() กับกฎและมาโครได้ใน คำถามที่พบบ่อยนี้

แอตทริบิวต์ที่มีเครื่องหมาย nonconfigurable ในเอกสารประกอบจะใช้ฟีเจอร์นี้ไม่ได้ โดยปกติแล้ว แอตทริบิวต์จะกำหนดค่าไม่ได้เนื่องจาก Bazel ต้องทราบค่าของแอตทริบิวต์ภายในก่อนจึงจะกำหนดวิธีแก้ไข select() ได้

ดูภาพรวมโดยละเอียดได้ที่ แอตทริบิวต์การสร้างที่กำหนดค่าได้

เป้าหมายเอาต์พุตโดยนัย

เลิกใช้งานเอาต์พุตโดยนัยใน C++ แล้ว โปรดงดใช้คำนี้ในภาษาอื่นๆ หากเป็นไปได้ เรายังไม่มีเส้นทางการเลิกใช้งาน แต่สุดท้ายแล้วก็จะเลิกใช้งานเช่นกัน

เมื่อคุณกำหนดกฎการสร้างในไฟล์ BUILD แสดงว่าคุณกําลังประกาศเป้าหมายกฎที่มีชื่อใหม่ในแพ็กเกจอย่างชัดเจน ฟังก์ชันกฎการสร้างจำนวนมากยังโดยนัยกำหนดเป้าหมายไฟล์เอาต์พุตอย่างน้อย 1 รายการด้วย ซึ่งเนื้อหาและความหมายจะขึ้นอยู่กับกฎ ตัวอย่างเช่น เมื่อคุณประกาศกฎ java_binary(name='foo', ...) อย่างชัดเจน คุณจะประกาศโดยนัยว่าไฟล์เอาต์พุตเป้าหมาย foo_deploy.jar เป็นสมาชิกของแพ็กเกจเดียวกันด้วย (เป้าหมายนี้โดยเฉพาะคือไฟล์เก็บถาวร Java แบบสําเร็จรูปที่เหมาะสําหรับการนําไปใช้งาน)

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

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

ข้อแตกต่างที่สำคัญแต่ค่อนข้างละเอียดระหว่างเนมสเปซ 2 รายการที่ระบบบิลด์ใช้ ได้แก่ ป้ายกำกับจะระบุเป้าหมาย ซึ่งอาจเป็นกฎหรือไฟล์ และเป้าหมายไฟล์อาจแบ่งออกเป็นเป้าหมายไฟล์ต้นทาง (หรืออินพุต) และเป้าหมายไฟล์ที่ดึงข้อมูล (หรือเอาต์พุต) สิ่งเหล่านี้คือสิ่งที่คุณพูดถึงได้ในไฟล์ BUILD, สร้างจากบรรทัดคำสั่ง หรือตรวจสอบโดยใช้ bazel query ซึ่งก็คือเนมสเปซเป้าหมาย เป้าหมายไฟล์แต่ละรายการจะสอดคล้องกับไฟล์จริง 1 ไฟล์บนดิสก์ ("เนมสเปซของระบบไฟล์") เป้าหมายของกฎแต่ละรายการอาจสอดคล้องกับไฟล์จริง 0 ไฟล์ อย่างน้อย 1 ไฟล์ หรือมากกว่านั้นบนดิสก์ อาจมีไฟล์ในดิสก์ที่ไม่มีเป้าหมายที่เกี่ยวข้อง เช่น .o ไฟล์ออบเจ็กต์ที่สร้างขึ้นระหว่างการคอมไพล์ C++ ไม่สามารถอ้างอิงได้จากภายในไฟล์ BUILD หรือจากบรรทัดคำสั่ง วิธีนี้ทำให้เครื่องมือสร้างอาจซ่อนรายละเอียดการใช้งานบางอย่างเกี่ยวกับวิธีทํางาน โปรดดูคำอธิบายเพิ่มเติมในข้อมูลอ้างอิงแนวคิด BUILD