การลงทะเบียน BazelCon 2024 เปิดให้ลงทะเบียนแล้วในตอนนี้

หน้านี้ได้รับการแปลโดย Cloud Translation API

บทแนะนำ Bazel: สร้างโปรเจ็กต์ Java

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

บทแนะนำนี้ครอบคลุมพื้นฐานการสร้างแอปพลิเคชัน Java ด้วย Bazel คุณจะตั้งค่าพื้นที่ทำงานและสร้างโปรเจ็กต์ Java แบบง่ายๆ ที่แสดงแนวคิดหลักของ Bazel เช่น เป้าหมายและไฟล์ BUILD

เวลาโดยประมาณในการดำเนินการเสร็จสมบูรณ์: 30 นาที

สิ่งที่คุณจะได้เรียนรู้

ในบทแนะนำนี้ คุณจะได้เรียนรู้วิธีทำสิ่งต่อไปนี้

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

ก่อนเริ่มต้น

ติดตั้ง Bazel

หากต้องการเตรียมพร้อมสำหรับบทแนะนำ ก่อนอื่นให้ติดตั้ง Bazel หากยังไม่ได้ติดตั้ง

ติดตั้ง JDK

ติดตั้ง Java JDK (เวอร์ชันที่แนะนำคือ 11 แต่ระบบรองรับเวอร์ชันระหว่าง 8 ถึง 15)
ตั้งค่าตัวแปรสภาพแวดล้อม JAVA_HOME ให้ชี้ไปยัง JDK
- ใน Linux/macOS ให้ทำดังนี้
```
export JAVA_HOME="$(dirname $(dirname $(realpath $(which javac))))"
```
- บน Windows:
  1. เปิดแผงควบคุม
  2. ไปที่ "ระบบและความปลอดภัย" > "ระบบ" > "การตั้งค่าระบบขั้นสูง" > แท็บ "ขั้นสูง" > "ตัวแปรสภาพแวดล้อม..."
  3. คลิก "ใหม่..." ในรายการ "ตัวแปรของผู้ใช้" (รายการที่ด้านบน)
  4. ป้อน JAVA_HOME ในช่อง "ชื่อตัวแปร"
  5. คลิก "เรียกดูไดเรกทอรี..."
  6. ไปที่ไดเรกทอรี JDK (เช่น C:\Program Files\Java\jdk1.8.0_152)
  7. คลิก "ตกลง" ในหน้าต่างโต้ตอบทั้งหมด

รับโปรเจ็กต์ตัวอย่าง

เรียกข้อมูลโปรเจ็กต์ตัวอย่างจากที่เก็บ GitHub ของ Bazel

git clone https://github.com/bazelbuild/examples

โปรเจ็กต์ตัวอย่างสําหรับบทแนะนํานี้จะอยู่ในไดเรกทอรี examples/java-tutorial และมีลักษณะดังนี้

java-tutorial
├── BUILD
├── src
│   └── main
│       └── java
│           └── com
│               └── example
│                   ├── cmdline
│                   │   ├── BUILD
│                   │   └── Runner.java
│                   ├── Greeting.java
│                   └── ProjectRunner.java
└── WORKSPACE

สร้างด้วย Bazel

ตั้งค่าพื้นที่ทํางาน

คุณต้องตั้งค่าพื้นที่ทํางานก่อนจึงจะสร้างโปรเจ็กต์ได้ เวิร์กช็อปคือไดเรกทอรีที่มีไฟล์ต้นฉบับของโปรเจ็กต์และเอาต์พุตการสร้างของ Bazel รวมถึงไฟล์ที่ Bazel รู้จักว่าเป็นไฟล์พิเศษ

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

หากต้องการกำหนดไดเรกทอรีเป็นพื้นที่ทำงาน Bazel ให้สร้างไฟล์ว่างชื่อ WORKSPACE ในไดเรกทอรีนั้น

เมื่อ Bazel บิลด์โปรเจ็กต์ อินพุตและทรัพยากร Dependency ทั้งหมดต้องอยู่ในเวิร์กスペースเดียวกัน ไฟล์ที่อยู่ในพื้นที่ทำงานต่างๆ จะแยกจากกัน เว้นแต่จะมีการลิงก์ ซึ่งอยู่นอกเหนือขอบเขตของบทแนะนำนี้

ทำความเข้าใจไฟล์ BUILD

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

โปรดดูไฟล์ java-tutorial/BUILD

java_binary(
    name = "ProjectRunner",
    srcs = glob(["src/main/java/com/example/*.java"]),
)

ในตัวอย่างของเรา เป้าหมาย ProjectRunner จะสร้างอินสแตนซ์กฎ java_binary ในตัวของ Bazel กฎนี้จะบอกให้ Bazel คอมไพล์ไฟล์ .jar และสคริปต์เชลล์ที่ใช้ห่อ (ทั้ง 2 รายการตั้งชื่อตามเป้าหมาย)

แอตทริบิวต์ในเป้าหมายจะระบุการพึ่งพาและตัวเลือกอย่างชัดเจน แม้ว่าแอตทริบิวต์ name จะเป็นแอตทริบิวต์ที่บังคับ แต่ก็มีแอตทริบิวต์หลายรายการที่ไม่บังคับ ตัวอย่างเช่น ในProjectRunner target ของกฎ name คือชื่อของเป้าหมาย srcs ระบุไฟล์ต้นทางที่ Bazel ใช้สร้างเป้าหมาย และ main_class ระบุคลาสที่มีเมธอดหลัก (คุณอาจสังเกตเห็นว่าตัวอย่างของเราใช้ glob เพื่อส่งชุดไฟล์ต้นฉบับไปยัง Bazel แทนที่จะแสดงรายการทีละรายการ)

สร้างโปรเจ็กต์

หากต้องการสร้างโปรเจ็กต์ตัวอย่าง ให้ไปที่ไดเรกทอรี java-tutorial แล้วเรียกใช้

bazel build //:ProjectRunner

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

Bazel จะสร้างเอาต์พุตที่คล้ายกับตัวอย่างต่อไปนี้

   INFO: Found 1 target...
   Target //:ProjectRunner up-to-date:
      bazel-bin/ProjectRunner.jar
      bazel-bin/ProjectRunner
   INFO: Elapsed time: 1.021s, Critical Path: 0.83s

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

ตอนนี้ให้ทดสอบไบนารีที่เพิ่งสร้างขึ้นใหม่โดยทำดังนี้

bazel-bin/ProjectRunner

ตรวจสอบกราฟทรัพยากร Dependency

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

หากต้องการแสดงภาพทรัพยากร Dependency ของโปรเจ็กต์ตัวอย่าง ให้สร้างการนําเสนอแบบข้อความของกราฟทรัพยากร Dependency โดยเรียกใช้คําสั่งนี้ที่รูทของเวิร์กสเปซ

bazel query  --notool_deps --noimplicit_deps "deps(//:ProjectRunner)" --output graph

คำสั่งข้างต้นบอกให้ Bazel ค้นหาไลบรารีทั้งหมดของเป้าหมาย //:ProjectRunner (ยกเว้นไลบรารีของโฮสต์และไลบรารีโดยนัย) และจัดรูปแบบเอาต์พุตเป็นกราฟ

จากนั้นวางข้อความลงใน GraphViz

ดังที่คุณเห็น โปรเจ็กต์มีเป้าหมายเดียวที่สร้างไฟล์ต้นฉบับ 2 ไฟล์โดยไม่มีไลบรารีเพิ่มเติม

กราฟทรัพยากร Dependency ของเป้าหมาย "ProjectRunner"

หลังจากตั้งค่าเวิร์กスペース สร้างโปรเจ็กต์ และตรวจสอบข้อกําหนดของโปรเจ็กต์แล้ว คุณสามารถเพิ่มความซับซ้อนได้

ปรับแต่งบิลด์ Bazel

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

ระบุเป้าหมายการสร้างหลายรายการ

คุณสามารถแยกบิลด์โปรเจ็กต์ตัวอย่างออกเป็น 2 เป้าหมายได้ แทนที่เนื้อหาของไฟล์ java-tutorial/BUILD ด้วยข้อมูลต่อไปนี้

java_binary(
    name = "ProjectRunner",
    srcs = ["src/main/java/com/example/ProjectRunner.java"],
    main_class = "com.example.ProjectRunner",
    deps = [":greeter"],
)

java_library(
    name = "greeter",
    srcs = ["src/main/java/com/example/Greeting.java"],
)

เมื่อใช้การกำหนดค่านี้ Bazel จะสร้างไลบรารี greeter ก่อน จากนั้นจึงสร้างไฟล์ไบนารี ProjectRunner แอตทริบิวต์ deps ใน java_binary บอก Bazel ว่าต้องใช้ไลบรารี greeter เพื่อสร้างไบนารี ProjectRunner

หากต้องการสร้างโปรเจ็กต์เวอร์ชันใหม่นี้ ให้เรียกใช้คำสั่งต่อไปนี้

bazel build //:ProjectRunner

Bazel จะสร้างเอาต์พุตที่คล้ายกับตัวอย่างต่อไปนี้

INFO: Found 1 target...
Target //:ProjectRunner up-to-date:
  bazel-bin/ProjectRunner.jar
  bazel-bin/ProjectRunner
INFO: Elapsed time: 2.454s, Critical Path: 1.58s

ตอนนี้ให้ทดสอบไบนารีที่เพิ่งสร้างขึ้นใหม่โดยทำดังนี้

bazel-bin/ProjectRunner

ตอนนี้หากคุณแก้ไข ProjectRunner.java และสร้างโปรเจ็กต์อีกครั้ง Bazel จะคอมไพล์ไฟล์นั้นอีกครั้งเท่านั้น

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

กราฟการขึ้นต่อกันของเป้าหมาย "ProjectRunner" หลังจากเพิ่มทรัพยากร Dependency

ตอนนี้คุณได้สร้างโปรเจ็กต์ที่มีเป้าหมาย 2 รายการแล้ว เป้าหมาย ProjectRunner จะสร้างไฟล์ต้นฉบับ 2 ไฟล์และขึ้นอยู่กับเป้าหมายอื่น 1 รายการ (:greeter) ซึ่งจะสร้างไฟล์ต้นฉบับอีก 1 ไฟล์

ใช้แพ็กเกจหลายรายการ

ตอนนี้เราจะมาแบ่งโปรเจ็กต์ออกเป็นหลายๆ แพ็กเกจ หากคุณดูไดเรกทอรี src/main/java/com/example/cmdline คุณจะเห็นว่าไดเรกทอรีมีไฟล์ BUILD และไฟล์ต้นฉบับบางไฟล์ด้วย ดังนั้นสำหรับ Bazel พื้นที่ทำงานจะมี 2 แพ็กเกจ ได้แก่ //src/main/java/com/example/cmdline และ // (เนื่องจากมีไฟล์ BUILD อยู่ที่รูทของพื้นที่ทำงาน)

โปรดดูไฟล์ src/main/java/com/example/cmdline/BUILD

java_binary(
    name = "runner",
    srcs = ["Runner.java"],
    main_class = "com.example.cmdline.Runner",
    deps = ["//:greeter"],
)

เป้าหมาย runner ขึ้นอยู่กับเป้าหมาย greeter ในแพ็กเกจ // (จึงเป็นป้ายกำกับเป้าหมาย //:greeter) - Bazel ทราบข้อมูลนี้ผ่านแอตทริบิวต์ deps ดูกราฟทรัพยากร Dependency ต่อไปนี้

กราฟการขึ้นต่อกันของ "ตัววิ่ง" เป้าหมาย

อย่างไรก็ตาม หากต้องการให้การบิลด์สําเร็จ คุณต้องให้สิทธิ์runnerเป้าหมายใน //src/main/java/com/example/cmdline/BUILD มองเห็นเป้าหมายใน //BUILD อย่างชัดเจนโดยใช้แอตทริบิวต์ visibility เนื่องจากโดยค่าเริ่มต้น เป้าหมายจะเปิดเผยต่อเป้าหมายอื่นๆ ในไฟล์ BUILD เดียวกันเท่านั้น (Bazel ใช้ระดับการเข้าถึงเป้าหมายเพื่อป้องกันปัญหา เช่น ไลบรารีที่มีรายละเอียดการใช้งานรั่วไหลไปยัง API สาธารณะ)

โดยเพิ่มแอตทริบิวต์ visibility ลงในเป้าหมาย greeter ใน java-tutorial/BUILD ดังที่แสดงด้านล่าง

java_library(
    name = "greeter",
    srcs = ["src/main/java/com/example/Greeting.java"],
    visibility = ["//src/main/java/com/example/cmdline:__pkg__"],
)

ตอนนี้คุณสร้างแพ็กเกจใหม่ได้โดยเรียกใช้คำสั่งต่อไปนี้ที่รูทของพื้นที่ทํางาน

bazel build //src/main/java/com/example/cmdline:runner

Bazel จะสร้างเอาต์พุตที่คล้ายกับตัวอย่างต่อไปนี้

INFO: Found 1 target...
Target //src/main/java/com/example/cmdline:runner up-to-date:
  bazel-bin/src/main/java/com/example/cmdline/runner.jar
  bazel-bin/src/main/java/com/example/cmdline/runner
  INFO: Elapsed time: 1.576s, Critical Path: 0.81s

ตอนนี้ให้ทดสอบไบนารีที่สร้างใหม่ โดยทำดังนี้

./bazel-bin/src/main/java/com/example/cmdline/runner

ตอนนี้คุณได้แก้ไขโปรเจ็กต์ให้สร้างเป็นแพ็กเกจ 2 รายการแล้ว โดยแต่ละรายการมีเป้าหมาย 1 รายการ และเข้าใจความสัมพันธ์ระหว่างแพ็กเกจ

ใช้ป้ายกำกับเพื่ออ้างอิงเป้าหมาย

ในไฟล์ BUILD และที่บรรทัดคำสั่ง Bazel จะใช้ป้ายกำกับเป้าหมายเพื่ออ้างอิงเป้าหมาย เช่น //:ProjectRunner หรือ //src/main/java/com/example/cmdline:runner ไวยากรณ์ของคำสั่งมีดังนี้

//path/to/package:target-name

หากเป้าหมายคือเป้าหมายกฎ path/to/package จะเป็นเส้นทางไปยังไดเรกทอรีที่มีไฟล์ BUILD และ target-name คือสิ่งที่คุณตั้งชื่อเป้าหมายในไฟล์ BUILD (แอตทริบิวต์ name) หากเป้าหมายเป็นไฟล์ path/to/package คือเส้นทางไปยังรูทของแพ็กเกจ และ target-name คือชื่อไฟล์เป้าหมาย รวมถึงเส้นทางแบบเต็ม

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

ตัวอย่างเช่น สำหรับเป้าหมายในไฟล์ java-tutorial/BUILD คุณไม่จำเป็นต้องระบุเส้นทางของแพ็กเกจ เนื่องจากรูทของพื้นที่ทำงานเป็นแพ็กเกจอยู่แล้ว (//) และป้ายกำกับเป้าหมาย 2 รายการของคุณก็คือ //:ProjectRunner และ //:greeter

แต่สำหรับเป้าหมายในไฟล์ //src/main/java/com/example/cmdline/BUILD คุณต้องระบุเส้นทางแบบเต็มของแพ็กเกจ //src/main/java/com/example/cmdline และป้ายกำกับเป้าหมายคือ //src/main/java/com/example/cmdline:runner

แพ็กเกจเป้าหมาย Java สำหรับการทำให้ใช้งานได้

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

ดังที่คุณจำได้ กฎการสร้าง java_binary จะสร้าง .jar และสคริปต์เชลล์ของ Wrapper ดูเนื้อหาของ runner.jar โดยใช้คำสั่งนี้

jar tf bazel-bin/src/main/java/com/example/cmdline/runner.jar

เนื้อหามีดังนี้

META-INF/
META-INF/MANIFEST.MF
com/
com/example/
com/example/cmdline/
com/example/cmdline/Runner.class

ดังที่คุณเห็น runner.jar มี Runner.class แต่ไม่มี Greeting.class ซึ่งเป็นข้อกำหนด สคริปต์ runner ที่ Bazel สร้างขึ้นจะเพิ่ม greeter.jar ลงใน classpath ดังนั้นหากปล่อยไว้เช่นนี้ สคริปต์จะทำงานในเครื่อง แต่จะไม่ทำงานแบบสแตนด์อโลนในเครื่องอื่น แต่กฎ java_binary ช่วยให้คุณสร้างไบนารีแบบสําเร็จรูปที่ใช้งานได้ หากต้องการสร้าง ให้เพิ่ม _deploy.jar ต่อท้ายชื่อเป้าหมาย:

bazel build //src/main/java/com/example/cmdline:runner_deploy.jar

Bazel จะสร้างเอาต์พุตที่คล้ายกับตัวอย่างต่อไปนี้

INFO: Found 1 target...
Target //src/main/java/com/example/cmdline:runner_deploy.jar up-to-date:
  bazel-bin/src/main/java/com/example/cmdline/runner_deploy.jar
INFO: Elapsed time: 1.700s, Critical Path: 0.23s

คุณเพิ่งสร้าง runner_deploy.jar ซึ่งสามารถเรียกใช้ได้แบบสแตนด์อโลนจากสภาพแวดล้อมการพัฒนา เนื่องจากมีไลบรารีรันไทม์ที่จำเป็น ดูเนื้อหาของ JAR แบบสแตนด์อโลนนี้โดยใช้คำสั่งเดียวกันกับก่อนหน้านี้

jar tf bazel-bin/src/main/java/com/example/cmdline/runner_deploy.jar

เนื้อหาประกอบด้วยคลาสที่จำเป็นทั้งหมดในการเรียกใช้

META-INF/
META-INF/MANIFEST.MF
build-data.properties
com/
com/example/
com/example/cmdline/
com/example/cmdline/Runner.class
com/example/Greeting.class

อ่านเพิ่มเติม

โปรดดูรายละเอียดเพิ่มเติมที่หัวข้อต่อไปนี้

rules_jvm_external สำหรับกฎในการจัดการทรัพยากร Dependency ของ Maven แบบทรานซิทีฟ
Dependency ภายนอกเพื่อดูข้อมูลเพิ่มเติมเกี่ยวกับการทำงานกับที่เก็บข้อมูลในเครื่องและที่เก็บข้อมูลระยะไกล
กฎอื่นๆ เพื่อดูข้อมูลเพิ่มเติมเกี่ยวกับ Bazel
บทแนะนำบิลด์ C++ เพื่อเริ่มต้นการสร้าง โปรเจ็กต์ C++ ด้วย Bazel
บทแนะนำแอปพลิเคชัน Android และบทแนะนำแอปพลิเคชัน iOS เพื่อเริ่มต้นสร้างแอปพลิเคชันบนอุปกรณ์เคลื่อนที่สำหรับ Android และ iOS ด้วย Bazel

ขอให้สนุกกับการสร้าง