Hướng dẫn về Bazel: Xây dựng dự án Java

Báo cáo vấn đề Xem nguồn Nightly · 8.3 · 8.2 · 8.1 · 8.0 · 7.6

Hướng dẫn này trình bày những thông tin cơ bản về cách tạo ứng dụng Java bằng Bazel. Bạn sẽ thiết lập không gian làm việc và tạo một dự án Java đơn giản minh hoạ các khái niệm chính của Bazel, chẳng hạn như các mục tiêu và tệp BUILD.

Thời gian hoàn thành ước tính: 30 phút.

Kiến thức bạn sẽ học được

Trong hướng dẫn này, bạn sẽ tìm hiểu cách:

  • Tạo mục tiêu
  • Trực quan hoá các phần phụ thuộc của dự án
  • Chia dự án thành nhiều mục tiêu và gói
  • Kiểm soát chế độ hiển thị mục tiêu trên các gói
  • Tham chiếu đến các mục tiêu thông qua nhãn
  • Triển khai mục tiêu

Trước khi bắt đầu

Cài đặt Bazel

Để chuẩn bị cho hướng dẫn này, trước tiên, hãy Cài đặt Bazel nếu bạn chưa cài đặt.

Cài đặt JDK

  1. Cài đặt Java JDK (phiên bản ưu tiên là 11, tuy nhiên các phiên bản từ 8 đến 15 đều được hỗ trợ).

  2. Đặt biến môi trường JAVA_HOME để trỏ đến JDK.

    • Trên Linux/macOS:

      export JAVA_HOME="$(dirname $(dirname $(realpath $(which javac))))"

    • Trên Windows:

      1. Mở Control Panel (Bảng điều khiển).
      2. Chuyển đến "System and Security" (Hệ thống và bảo mật) > "System" (Hệ thống) > "Advanced System Settings" (Cài đặt hệ thống nâng cao) > thẻ "Advanced" (Nâng cao) > "Environment Variables..." (Biến môi trường...) .
      3. Trong danh sách "User variables" (biến người dùng) (danh sách ở trên cùng), hãy nhấp vào "New..." (Mới...).
      4. Trong trường "Tên biến", hãy nhập JAVA_HOME.
      5. Nhấp vào "Duyệt tìm thư mục...".
      6. Chuyển đến thư mục JDK (ví dụ: C:\Program Files\Java\jdk1.8.0_152).
      7. Nhấp vào "OK" trên tất cả các cửa sổ hộp thoại.

Tải dự án mẫu xuống

Truy xuất dự án mẫu từ kho lưu trữ GitHub của Bazel:

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

Dự án mẫu cho hướng dẫn này nằm trong thư mục examples/java-tutorial và có cấu trúc như sau:

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

Tạo bằng Bazel

Thiết lập không gian làm việc

Trước khi có thể tạo một dự án, bạn cần thiết lập không gian làm việc cho dự án đó. Không gian làm việc là một thư mục chứa các tệp nguồn của dự án và đầu ra của bản dựng Bazel. Thư mục này cũng chứa các tệp mà Bazel nhận dạng là đặc biệt:

  • Tệp WORKSPACE xác định thư mục và nội dung của thư mục đó là một không gian làm việc Bazel và nằm ở gốc của cấu trúc thư mục dự án,

  • Một hoặc nhiều tệp BUILD, cho Bazel biết cách tạo các phần khác nhau của dự án. (Một thư mục trong không gian làm việc chứa tệp BUILD là một gói. Bạn sẽ tìm hiểu về các gói trong phần sau của hướng dẫn này.)

Để chỉ định một thư mục làm không gian làm việc Bazel, hãy tạo một tệp trống có tên là WORKSPACE trong thư mục đó.

Khi Bazel tạo dự án, tất cả các đầu vào và phần phụ thuộc phải nằm trong cùng một không gian làm việc. Các tệp nằm trong các không gian làm việc khác nhau sẽ độc lập với nhau, trừ phi được liên kết. Việc này nằm ngoài phạm vi của hướng dẫn này.

Tìm hiểu về tệp BUILD

Tệp BUILD chứa nhiều loại chỉ dẫn khác nhau cho Bazel. Loại quan trọng nhất là quy tắc xây dựng, cho Bazel biết cách xây dựng các đầu ra mong muốn, chẳng hạn như các tệp nhị phân hoặc thư viện có thể thực thi. Mỗi phiên bản của một quy tắc xây dựng trong tệp BUILD được gọi là một mục tiêu và trỏ đến một tập hợp cụ thể gồm các tệp nguồn và phần phụ thuộc. Một mục tiêu cũng có thể trỏ đến các mục tiêu khác.

Hãy xem tệp java-tutorial/BUILD:

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

Trong ví dụ của chúng tôi, mục tiêu ProjectRunner sẽ khởi tạo quy tắc java_binary tích hợp của Bazel. Quy tắc này yêu cầu Bazel tạo một tệp .jar và một tập lệnh trình bao bọc (cả hai đều được đặt tên theo mục tiêu).

Các thuộc tính trong mục tiêu nêu rõ các phần phụ thuộc và lựa chọn của mục tiêu đó. Mặc dù thuộc tính name là bắt buộc, nhưng nhiều thuộc tính khác là không bắt buộc. Ví dụ: trong mục tiêu quy tắc ProjectRunner, name là tên của mục tiêu, srcs chỉ định các tệp nguồn mà Bazel dùng để tạo mục tiêu và main_class chỉ định lớp chứa phương thức chính. (Có thể bạn đã nhận thấy ví dụ của chúng tôi sử dụng glob để truyền một nhóm tệp nguồn đến Bazel thay vì liệt kê từng tệp một.)

Tạo dự án

Để tạo dự án mẫu, hãy chuyển đến thư mục java-tutorial rồi chạy:

bazel build //:ProjectRunner

Trong nhãn đích, phần // là vị trí của tệp BUILD so với gốc của không gian làm việc (trong trường hợp này là chính gốc), còn ProjectRunner là tên đích trong tệp BUILD. (Bạn sẽ tìm hiểu chi tiết hơn về nhãn mục tiêu ở cuối hướng dẫn này.)

Bazel tạo ra kết quả tương tự như sau:

   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

Xin chúc mừng! Bạn vừa tạo mục tiêu Bazel đầu tiên! Bazel đặt các đầu ra bản dựng trong thư mục bazel-bin ở gốc của không gian làm việc. Duyệt qua nội dung của tệp này để nắm được cấu trúc đầu ra của Bazel.

Giờ thì hãy kiểm thử tệp nhị phân mới tạo:

bazel-bin/ProjectRunner

Xem xét biểu đồ phần phụ thuộc

Bazel yêu cầu bạn khai báo rõ ràng các phần phụ thuộc của bản dựng trong tệp BUILD. Bazel sử dụng những câu lệnh đó để tạo biểu đồ phần phụ thuộc của dự án, giúp tạo các bản dựng gia tăng chính xác.

Để hình dung các phần phụ thuộc của dự án mẫu, bạn có thể tạo một bản trình bày văn bản của biểu đồ phần phụ thuộc bằng cách chạy lệnh này ở thư mục gốc của không gian làm việc:

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

Lệnh trên yêu cầu Bazel tìm tất cả các phần phụ thuộc cho mục tiêu //:ProjectRunner (không bao gồm các phần phụ thuộc ngầm và máy chủ lưu trữ) và định dạng đầu ra dưới dạng biểu đồ.

Sau đó, hãy dán văn bản vào GraphViz.

Như bạn thấy, dự án này có một mục tiêu duy nhất là tạo 2 tệp nguồn mà không có phần phụ thuộc bổ sung:

Biểu đồ phần phụ thuộc của mục tiêu "ProjectRunner"

Sau khi thiết lập không gian làm việc, tạo dự án và kiểm tra các phần phụ thuộc của dự án, bạn có thể thêm một số độ phức tạp.

Tinh chỉnh bản dựng Bazel

Mặc dù một mục tiêu là đủ cho các dự án nhỏ, nhưng bạn có thể muốn chia các dự án lớn hơn thành nhiều mục tiêu và gói để cho phép các bản dựng gia tăng nhanh (tức là chỉ xây dựng lại những gì đã thay đổi) và tăng tốc các bản dựng bằng cách xây dựng nhiều phần của một dự án cùng một lúc.

Chỉ định nhiều mục tiêu bản dựng

Bạn có thể chia bản dựng dự án mẫu thành 2 mục tiêu. Thay thế nội dung của tệp java-tutorial/BUILD bằng nội dung sau:

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"],
)

Với cấu hình này, trước tiên Bazel sẽ tạo thư viện greeter, sau đó tạo tệp nhị phân ProjectRunner. Thuộc tính deps trong java_binary cho Bazel biết rằng cần có thư viện greeter để tạo tệp nhị phân ProjectRunner.

Để tạo phiên bản mới này của dự án, hãy chạy lệnh sau:

bazel build //:ProjectRunner

Bazel tạo ra kết quả tương tự như sau:

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

Giờ thì hãy kiểm thử tệp nhị phân mới tạo:

bazel-bin/ProjectRunner

Nếu bạn sửa đổi ProjectRunner.java và tạo lại dự án, Bazel sẽ chỉ biên dịch lại tệp đó.

Khi xem biểu đồ phần phụ thuộc, bạn có thể thấy rằng ProjectRunner phụ thuộc vào cùng một đầu vào như trước đây, nhưng cấu trúc của bản dựng lại khác:

Biểu đồ phần phụ thuộc của mục tiêu "ProjectRunner" sau khi thêm một phần phụ thuộc

Giờ đây, bạn đã tạo dự án có 2 mục tiêu. Mục tiêu ProjectRunner tạo 2 tệp nguồn và phụ thuộc vào một mục tiêu khác (:greeter), mục tiêu này tạo thêm một tệp nguồn.

Sử dụng nhiều gói

Bây giờ, hãy chia dự án thành nhiều gói. Nếu xem thư mục src/main/java/com/example/cmdline, bạn có thể thấy thư mục này cũng chứa một tệp BUILD, cùng với một số tệp nguồn. Do đó, đối với Bazel, không gian làm việc hiện chứa hai gói, //src/main/java/com/example/cmdline và // (vì có một tệp BUILD ở gốc của không gian làm việc).

Hãy xem tệp src/main/java/com/example/cmdline/BUILD:

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

Mục tiêu runner phụ thuộc vào mục tiêu greeter trong gói // (do đó, nhãn mục tiêu //:greeter) – Bazel biết điều này thông qua thuộc tính deps. Hãy xem biểu đồ phần phụ thuộc:

Biểu đồ phần phụ thuộc của "trình chạy" mục tiêu

Tuy nhiên, để bản dựng thành công, bạn phải cung cấp rõ ràng mục tiêu runner trong khả năng hiển thị //src/main/java/com/example/cmdline/BUILD cho các mục tiêu trong //BUILD bằng cách sử dụng thuộc tính visibility. Điều này là do theo mặc định, các mục tiêu chỉ hiển thị cho các mục tiêu khác trong cùng một tệp BUILD. (Bazel sử dụng khả năng hiển thị mục tiêu để ngăn chặn các vấn đề như thư viện chứa thông tin triển khai rò rỉ vào các API công khai.)

Để làm việc này, hãy thêm thuộc tính visibility vào mục tiêu greeter trong java-tutorial/BUILD như minh hoạ dưới đây:

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

Giờ đây, bạn có thể tạo gói mới bằng cách chạy lệnh sau ở thư mục gốc của không gian làm việc:

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

Bazel tạo ra kết quả tương tự như sau:

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

Giờ thì hãy kiểm thử tệp nhị phân mới tạo:

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

Giờ đây, bạn đã sửa đổi dự án để tạo thành 2 gói, mỗi gói chứa một mục tiêu và hiểu rõ các phần phụ thuộc giữa chúng.

Sử dụng nhãn để tham chiếu mục tiêu

Trong các tệp BUILD và tại dòng lệnh, Bazel sử dụng nhãn mục tiêu để tham chiếu đến các mục tiêu – ví dụ: //:ProjectRunner hoặc //src/main/java/com/example/cmdline:runner. Cú pháp của các hàm này như sau:

//path/to/package:target-name

Nếu đích đến là đích đến quy tắc, thì path/to/package là đường dẫn đến thư mục chứa tệp BUILD và target-name là tên bạn đặt cho đích đến trong tệp BUILD (thuộc tính name). Nếu đích đến là đích đến tệp, thì path/to/package là đường dẫn đến gốc của gói và target-name là tên của tệp đích, bao gồm cả đường dẫn đầy đủ của tệp đó.

Khi tham chiếu đến các mục tiêu ở thư mục gốc của kho lưu trữ, đường dẫn gói sẽ trống, chỉ cần sử dụng //:target-name. Khi tham chiếu các mục tiêu trong cùng một tệp BUILD, bạn thậm chí có thể bỏ qua giá trị nhận dạng gốc của không gian làm việc // và chỉ sử dụng :target-name.

Ví dụ: đối với các mục tiêu trong tệp java-tutorial/BUILD, bạn không phải chỉ định đường dẫn gói, vì thư mục gốc của không gian làm việc chính là một gói (//) và hai nhãn mục tiêu của bạn chỉ là //:ProjectRunner và //:greeter.

Tuy nhiên, đối với các mục tiêu trong tệp //src/main/java/com/example/cmdline/BUILD, bạn phải chỉ định đường dẫn đầy đủ của gói //src/main/java/com/example/cmdline và nhãn mục tiêu của bạn là //src/main/java/com/example/cmdline:runner.

Đóng gói mục tiêu Java để triển khai

Bây giờ, hãy đóng gói một mục tiêu Java để triển khai bằng cách tạo tệp nhị phân với tất cả các phần phụ thuộc thời gian chạy của tệp đó. Nhờ đó, bạn có thể chạy tệp nhị phân bên ngoài môi trường phát triển.

Như bạn nhớ, quy tắc tạo java_binary tạo ra một .jar và một tập lệnh trình bao bao bọc. Hãy xem nội dung của runner.jar bằng lệnh sau:

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

Nội dung đó là:

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

Như bạn có thể thấy, runner.jar chứa Runner.class nhưng không chứa phần phụ thuộc của Runner.class là Greeting.class. Tập lệnh runner mà Bazel tạo sẽ thêm greeter.jar vào đường dẫn lớp. Vì vậy, nếu bạn giữ nguyên như thế này, tập lệnh sẽ chạy cục bộ nhưng không chạy độc lập trên một máy khác. Rất may là quy tắc java_binary cho phép bạn tạo một tệp nhị phân khép kín, có thể triển khai. Để tạo, hãy thêm _deploy.jar vào tên mục tiêu:

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

Bazel tạo ra kết quả tương tự như sau:

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

Bạn vừa tạo runner_deploy.jar. Bạn có thể chạy độc lập runner_deploy.jar mà không cần đến môi trường phát triển vì runner_deploy.jar chứa các phần phụ thuộc thời gian chạy bắt buộc. Hãy xem nội dung của JAR độc lập này bằng cách dùng cùng một lệnh như trước:

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

Nội dung bao gồm tất cả các lớp cần thiết để chạy:

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

Tài liệu đọc thêm

Để biết thêm thông tin, hãy xem:

Chúc bạn xây dựng vui vẻ!