Hướng dẫn của Bazel: Tạo ứng dụng Android

Hướng dẫn này trình bày cách xây dựng một ứng dụng Android đơn giản bằng Bazel.

Bazel hỗ trợ xây dựng ứng dụng Android bằng các quy tắc Android.

Hướng dẫn này dành cho người dùng Windows, macOS và Linux, đồng thời không yêu cầu kinh nghiệm về Bazel hoặc phát triển ứng dụng Android. Bạn không cần viết bất kỳ mã Android nào trong hướng dẫn này.

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

Trong hướng dẫn này, bạn sẽ học cách:

• Thiết lập môi trường bằng cách cài đặt Bazel và Android Studio, đồng thời tải dự án mẫu xuống.
• Thiết lập một không gian làm việc Bazel chứa mã nguồn cho ứng dụng và tệp MODULE.bazel xác định cấp cao nhất của thư mục không gian làm việc.
• Cập nhật tệp MODULE.bazel để chứa các tham chiếu đến các phần phụ thuộc bên ngoài bắt buộc, chẳng hạn như SDK Android.
• Tạo tệp BUILD.
• Xây dựng ứng dụng bằng Bazel.
• Triển khai và chạy ứng dụng trên trình mô phỏng Android hoặc thiết bị thực.

Trước khi bắt đầu

Cài đặt Bazel

Trước khi bắt đầu hướng dẫn, hãy cài đặt phần mềm sau:

• Bazel. Để cài đặt, hãy làm theo hướng dẫn cài đặt.
• Android Studio. Để cài đặt, hãy làm theo các bước để tải Android Studio xuống. Thực thi trình hướng dẫn thiết lập để tải SDK xuống và định cấu hình môi trường của bạn.
• (Không bắt buộc) Git. Sử dụng git để tải dự án ứng dụng Android xuống.

Tải dự án mẫu

Đối với dự án mẫu, hãy sử dụng dự án ứng dụng Android hướng dẫn trong kho lưu trữ ví dụ của Bazel.

Ứng dụng này có một nút duy nhất in lời chào khi được nhấp vào:

Hình 1. Lời chào của nút ứng dụng Android.

Sao chép kho lưu trữ bằng git (hoặc tải trực tiếp tệp ZIP xuống):

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

Dự án mẫu cho hướng dẫn này nằm trong examples/android/tutorial. Trong phần còn lại của hướng dẫn, bạn sẽ thực thi các lệnh trong thư mục này.

Xem lại các tệp nguồn

Hãy xem các tệp nguồn cho ứng dụng.

.
├── README.md
└── src
    └── main
        ├── AndroidManifest.xml
        └── java
            └── com
                └── example
                    └── bazel
                        ├── AndroidManifest.xml
                        ├── Greeter.java
                        ├── MainActivity.java
                        └── res
                            ├── layout
                            │   └── activity_main.xml
                            └── values
                                ├── colors.xml
                                └── strings.xml

Các tệp và thư mục chính là:

Xây dựng bằng Bazel

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

Không gian làm việc là một thư mục chứa các tệp nguồn cho một hoặc nhiều dự án phần mềm và có tệp MODULE.bazel ở thư mục gốc.

Tệp MODULE.bazel có thể trống hoặc có thể chứa các tham chiếu đến các phần phụ thuộc bên ngoài cần thiết để xây dựng dự án.

Trước tiên, hãy chạy lệnh sau để tạo tệp MODULE.bazel trống:

Chạy Bazel

Giờ đây, bạn có thể kiểm tra xem Bazel có đang chạy đúng cách hay không bằng lệnh:

bazel info workspace

Nếu Bazel in đường dẫn của thư mục hiện tại, thì bạn đã sẵn sàng! Nếu tệp MODULE.bazel không tồn tại, bạn có thể thấy thông báo lỗi như:

ERROR: The 'info' command is only supported from within a workspace.

Tích hợp với SDK Android

Bazel cần chạy các công cụ xây dựng SDK Android để xây dựng ứng dụng. Điều này có nghĩa là bạn cần thêm một số thông tin vào tệp MODULE.bazel để Bazel biết nơi tìm thấy các công cụ đó.

Thêm dòng sau vào tệp MODULE.bazel của bạn:

bazel_dep(name = "rules_android", version = "0.6.6")

remote_android_extensions = use_extension(
    "@rules_android//bzlmod_extensions:android_extensions.bzl",
    "remote_android_tools_extensions")
use_repo(remote_android_extensions, "android_tools")

android_sdk_repository_extension = use_extension("@rules_android//rules/android_sdk_repository:rule.bzl", "android_sdk_repository_extension")
use_repo(android_sdk_repository_extension, "androidsdk")

Thao tác này sẽ sử dụng SDK Android tại đường dẫn được biến môi trường ANDROID_HOME tham chiếu và tự động phát hiện cấp độ API cao nhất cũng như phiên bản mới nhất của các công cụ xây dựng được cài đặt trong vị trí đó.

Bạn có thể đặt biến ANDROID_HOME thành vị trí của SDK Android. Tìm đường dẫn đến SDK đã cài đặt bằng Trình quản lý SDK của Android Studio. Giả sử SDK được cài đặt vào các vị trí mặc định, bạn có thể sử dụng các lệnh sau để đặt biến ANDROID_HOME:

Các lệnh trên chỉ đặt biến cho phiên shell hiện tại. Để biến các lệnh này thành vĩnh viễn, hãy chạy các lệnh sau:

Không bắt buộc: Nếu muốn biên dịch mã gốc vào ứng dụng Android, bạn cũng cần tải NDK Android xuống và sử dụng rules_android_ndk bằng cách thêm dòng sau vào tệp MODULE.bazel của bạn:

bazel_dep(name = "rules_android_ndk", version = "0.1.3")

Để biết thêm thông tin, hãy đọc bài viết Sử dụng Bộ phát triển mã gốc Android với Bazel.

Bạn không cần đặt cấp độ API thành cùng một giá trị cho SDK và NDK. Trang này chứa một bản đồ từ các bản phát hành Android đến các cấp độ API được NDK hỗ trợ.

Tạo tệp BUILD

Tệp BUILD mô tả mối quan hệ giữa một tập hợp các kết quả đầu ra của bản dựng, chẳng hạn như các tài nguyên Android đã biên dịch từ aapt hoặc các tệp lớp từ javac, và các phần phụ thuộc của chúng. Các phần phụ thuộc này có thể là tệp nguồn (Java, C++) trong không gian làm việc của bạn hoặc các kết quả đầu ra khác của bản dựng. Tệp BUILD files được viết bằng một ngôn ngữ có tên là Starlark.

Tệp BUILD là một phần của khái niệm trong Bazel được gọi là hệ phân cấp gói. Hệ phân cấp gói là một cấu trúc logic phủ lên cấu trúc thư mục trong không gian làm việc của bạn. Mỗi gói là một thư mục (và các thư mục con của nó) chứa một tập hợp các tệp nguồn có liên quan và một tệp BUILD. Gói này cũng bao gồm mọi thư mục con, ngoại trừ những thư mục chứa tệp BUILD riêng. Tên gói là đường dẫn đến tệp BUILD tương ứng với tệp MODULE.bazel.

Xin lưu ý rằng hệ phân cấp gói của Bazel về mặt khái niệm khác với hệ phân cấp gói Java của thư mục Ứng dụng Android nơi tệp BUILD được đặt, mặc dù các thư mục có thể được sắp xếp giống hệt nhau.

Đối với ứng dụng Android đơn giản trong hướng dẫn này, các tệp nguồn trong src/main/ bao gồm một gói Bazel duy nhất. Một dự án phức tạp hơn có thể có nhiều gói lồng nhau.

Thêm quy tắc android_library

Tệp BUILD chứa nhiều loại khai báo cho Bazel. Loại quan trọng nhất là quy tắc bản dựng, cho Bazel biết cách xây dựng kết quả đầu ra của phần mềm trung gian hoặc cuối cùng từ một tập hợp các tệp nguồn hoặc các phần phụ thuộc khác. Bazel cung cấp 2 quy tắc bản dựng, android_library và android_binary, mà bạn có thể sử dụng để xây dựng ứng dụng Android.

Đối với hướng dẫn này, trước tiên, bạn sẽ sử dụng quy tắc android_library để cho Bazel biết cách xây dựng một mô-đun thư viện Android từ mã nguồn ứng dụng và các tệp tài nguyên. Sau đó, bạn sẽ sử dụng quy tắc android_binary để cho Bazel biết cách xây dựng gói ứng dụng Android.

Tạo tệp BUILD mới trong thư mục src/main/java/com/example/bazel, và khai báo mục tiêu android_library mới:

src/main/java/com/example/bazel/BUILD:

load("@rules_android//rules:rules.bzl", "android_library")

package(
    default_visibility = ["//src:__subpackages__"],
)

android_library(
    name = "greeter_activity",
    srcs = [
        "Greeter.java",
        "MainActivity.java",
    ],
    manifest = "AndroidManifest.xml",
    resource_files = glob(["res/**"]),
)

Quy tắc bản dựng android_library chứa một tập hợp các thuộc tính chỉ định thông tin mà Bazel cần để xây dựng một mô-đun thư viện từ các tệp nguồn. Xin lưu ý rằng tên của quy tắc là greeter_activity. Bạn sẽ tham chiếu quy tắc bằng tên này dưới dạng phần phụ thuộc trong quy tắc android_binary.

Thêm quy tắc android_binary

Quy tắc android_binary xây dựng gói ứng dụng Android (.apk tệp) cho ứng dụng của bạn.

Tạo tệp BUILD mới trong thư mục src/main/, và khai báo mục tiêu android_binary mới:

src/main/BUILD:

load("@rules_android//rules:rules.bzl", "android_binary")

android_binary(
    name = "app",
    manifest = "//src/main/java/com/example/bazel:AndroidManifest.xml",
    deps = ["//src/main/java/com/example/bazel:greeter_activity"],
)

Ở đây, thuộc tính deps tham chiếu đến kết quả đầu ra của quy tắc greeter_activity mà bạn đã thêm vào tệp BUILD ở trên. Điều này có nghĩa là khi Bazel xây dựng kết quả đầu ra của quy tắc này, trước tiên, Bazel sẽ kiểm tra để xem kết quả đầu ra của quy tắc thư viện greeter_activity đã được xây dựng và có phải là phiên bản mới nhất hay không. Nếu không, Bazel sẽ xây dựng kết quả đầu ra đó rồi sử dụng kết quả đầu ra đó để xây dựng tệp gói ứng dụng.

Bây giờ, hãy lưu và đóng tệp.

Tạo ứng dụng

Hãy thử xây dựng ứng dụng! Chạy lệnh sau để xây dựng mục tiêu android_binary:

bazel build //src/main:app

Lệnh con build hướng dẫn Bazel xây dựng mục tiêu tiếp theo. Mục tiêu được chỉ định là tên của một quy tắc bản dựng bên trong một tệp BUILD, cùng với đường dẫn gói tương ứng với thư mục không gian làm việc của bạn. Đối với ví dụ này, mục tiêu là app và đường dẫn gói là //src/main/.

Xin lưu ý rằng đôi khi bạn có thể bỏ qua đường dẫn gói hoặc tên mục tiêu, tuỳ thuộc vào thư mục làm việc hiện tại của bạn trong dòng lệnh và tên của mục tiêu. Để biết thêm thông tin chi tiết về nhãn và đường dẫn mục tiêu, hãy xem phần Nhãn.

Bazel sẽ bắt đầu xây dựng ứng dụng mẫu. Trong quá trình xây dựng, kết quả đầu ra của ứng dụng sẽ có dạng như sau:

INFO: Analysed target //src/main:app (0 packages loaded, 0 targets configured).
INFO: Found 1 target...
Target //src/main:app up-to-date:
  bazel-bin/src/main/app_deploy.jar
  bazel-bin/src/main/app_unsigned.apk
  bazel-bin/src/main/app.apk

Xác định vị trí kết quả đầu ra của bản dựng

Bazel đặt kết quả đầu ra của cả các thao tác xây dựng trung gian và cuối cùng vào một tập hợp các thư mục đầu ra cho mỗi người dùng, mỗi không gian làm việc. Các thư mục này được liên kết tượng trưng từ các vị trí sau ở cấp cao nhất của thư mục dự án, nơi có tệp MODULE.bazel:

• bazel-bin lưu trữ các tệp thực thi nhị phân và các kết quả đầu ra khác của bản dựng có thể chạy
• bazel-genfiles lưu trữ các tệp nguồn trung gian do các quy tắc Bazel tạo
• bazel-out lưu trữ các loại kết quả đầu ra khác của bản dựng

Bazel lưu trữ tệp .apk Android được tạo bằng quy tắc android_binary trong thư mục bazel-bin/src/main, trong đó tên thư mục con src/main được lấy từ tên của gói Bazel.

Tại dấu nhắc lệnh, hãy liệt kê nội dung của thư mục này và tìm app.apk tệp:

Chạy ứng dụng

Giờ đây, bạn có thể triển khai ứng dụng vào một thiết bị Android hoặc trình mô phỏng đã kết nối từ dòng lệnh bằng bazel mobile-install. Lệnh này sử dụng Cầu gỡ lỗi Android (adb) để giao tiếp với thiết bị. Bạn phải thiết lập thiết bị để sử dụng adb theo hướng dẫn trong Cầu gỡ lỗi Android trước khi triển khai. Bạn cũng có thể chọn cài đặt ứng dụng trên trình mô phỏng Android có trong Android Studio. Hãy đảm bảo trình mô phỏng đang chạy trước khi thực thi lệnh bên dưới.

Nhập thông tin sau:

bazel mobile-install //src/main:app \
  --mode=skylark \
  --mobile_install_aspect=@rules_android//mobile_install:mi.bzl \
  --mobile_install_supported_rules=android_binary \
  --java_runtime_version=17 \
  --java_language_version=17 \
  --tool_java_runtime_version=17 \
  --tool_java_language_version=17

Xin lưu ý rằng bạn có thể thêm các cờ bổ sung cần thiết cho mobile-install vào tệp bazelrc của dự án. Bạn sẽ không cần các cờ dành riêng cho mobile-install (--mode, --mobile_install*) kể từ Bazel 8.4.0 trở đi. Bạn có thể cần nhiều cờ Java cho ngôn ngữ và phiên bản thời gian chạy , tuỳ thuộc vào cấu hình Java của không gian làm việc. Các công cụ phụ mobile-install yêu cầu ngôn ngữ và cấp độ thời gian chạy là 17 trở lên.

Giờ đây, "Ứng dụng hướng dẫn Bazel" sẽ tự động cài đặt và khởi chạy:

Hình 2. Ứng dụng hướng dẫn Bazel.

Xin chúc mừng! Bạn vừa cài đặt ứng dụng Android đầu tiên được xây dựng bằng Bazel.

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

Để biết thêm thông tin chi tiết, hãy xem các trang sau:

• Các vấn đề mở trên rules_android GitHub
• Thông tin khác về mobile-install
• Tích hợp các phần phụ thuộc bên ngoài như AppCompat, Guava và JUnit từ kho lưu trữ Maven bằng rules_jvm_external
• Chạy các bài kiểm thử Robolectric bằng tính năng tích hợp robolectric-bazel.
• Tích hợp mã C và C++ vào ứng dụng Android bằng NDK
• Xem thêm các dự án mẫu Bazel của:
  • một ứng dụng Kotlin
  • Kiểm thử Robolectric
  • Kiểm thử Espresso

Chúc bạn xây dựng thành công!