|
| 1 | +--- |
| 2 | +<!-- Copyright © SixtyFPS GmbH <[email protected]> ; SPDX-License-Identifier: MIT --> |
| 3 | +title: Android |
| 4 | +description: Android Platform Guide |
| 5 | +--- |
| 6 | + |
| 7 | +// cSpell: ignore xbuild textfields |
| 8 | + |
| 9 | +import LangRefLink from '@slint/common-files/src/components/LangRefLink.astro'; |
| 10 | +import { Image } from 'astro:assets'; |
| 11 | + |
| 12 | +:::note[Note] |
| 13 | +When developing Slint applications for Android, you can only use Rust as the programming language. |
| 14 | +::: |
| 15 | + |
| 16 | +Also see the documentation of the <LangRefLink lang="rust-slint" relpath="android/">android module in our Rust API documentation</LangRefLink>. |
| 17 | + |
| 18 | +## Project Setup |
| 19 | + |
| 20 | +Slint uses the [android-activity crate](https://github.com/rust-mobile/android-activity) as the interface to |
| 21 | +the operating system, which is re-exported as `slint::android::android_activity`. To get started, follow these steps: |
| 22 | + |
| 23 | +First, your project needs to be a library crate. Add the following to your `Cargo.toml`: |
| 24 | + |
| 25 | +```toml |
| 26 | +[lib] |
| 27 | +crate_type = ["cdylib"] |
| 28 | +``` |
| 29 | + |
| 30 | +You also need to select the version of android-activity you want to use: |
| 31 | + |
| 32 | +```toml |
| 33 | +[dependencies] |
| 34 | +slint = { version = "1.15.0", features = ["backend-android-activity-06"] } |
| 35 | +``` |
| 36 | + |
| 37 | +This feature compiles with any target\_os and can safely be enabled anywhere. |
| 38 | + |
| 39 | +Second, in your `lib.rs`, add this function: |
| 40 | + |
| 41 | +```rs |
| 42 | +#[cfg(target_os = "android")] |
| 43 | +#[unsafe(no_mangle)] |
| 44 | +fn android_main(app: slint::android::AndroidApp) { |
| 45 | + slint::android::init(app).unwrap(); |
| 46 | + let main_window = ...; // window generated by the Slint macros |
| 47 | + main_window.run().unwrap(); |
| 48 | +} |
| 49 | +``` |
| 50 | + |
| 51 | +You can also add an Android event |
| 52 | +([`android_activity::PollEvent`](https://docs.rs/android-activity/latest/android_activity/enum.PollEvent.html)) |
| 53 | +listener by replacing the call to `slint::android::init` with `slint::android::init_with_event_listener`. |
| 54 | + |
| 55 | +That's all of the necessary code changes. In the next section, we're going to set up the environment to |
| 56 | +build the project. |
| 57 | + |
| 58 | +## Android Setup |
| 59 | + |
| 60 | +The Android development workflow centers around the `adb` command line tool. Use it to connect to |
| 61 | +Android devices and emulators to upload and run applications (and do other things not relevant here). |
| 62 | + |
| 63 | +The easiest way to install the Android development environment is to download and install |
| 64 | +[Android Studio](https://developer.android.com/studio). In the settings pane, navigate to the Android |
| 65 | +SDK page and install all SDK versions you need. We recommend to use the latest version available, |
| 66 | +because it can be configured to be backwards-compatible with older versions of Android. This manager |
| 67 | +is available in the settings in "Languages & Frameworks" > "Android SDK". |
| 68 | + |
| 69 | +import androidSdkManager from '/src/assets/android/android_sdk_manager.png'; |
| 70 | + |
| 71 | +<Image src={androidSdkManager} style={{width: "500px"}} alt="Screenshot Android SDK Manager" /> |
| 72 | + |
| 73 | +Also note the SDK location on top, this path might have to be used for the `ANDROID_HOME` environment |
| 74 | +variable if the build tools can't detect it automatically. |
| 75 | + |
| 76 | +Add the `platform-tools` directory to your `PATH` so that the `adb` tool is available on the command |
| 77 | +line. |
| 78 | + |
| 79 | +To get the list of Android devices, simulators and emulators currently attached to your machine, run |
| 80 | + |
| 81 | +```sh |
| 82 | +adb devices |
| 83 | +``` |
| 84 | + |
| 85 | +You can connect to a physical device on the network by using |
| 86 | + |
| 87 | +```sh |
| 88 | +adb connect <host> |
| 89 | +``` |
| 90 | + |
| 91 | +The `host` is the IP address of the device. Note that it has to have development mode enabled for |
| 92 | +this. |
| 93 | + |
| 94 | +### Virtual Device Setup |
| 95 | + |
| 96 | +We recommend developing using a virtual device first, because it speeds up the development cycle. |
| 97 | +However, eventually you have to also test on a device to make sure that the interface is usable on a |
| 98 | +touch screen and to check if all text is large enough, etc. |
| 99 | + |
| 100 | +To create and run a virtual device, use the Virtual Device Manager available in Android Studio. You |
| 101 | +can open it from its main screen under "More Actions": |
| 102 | + |
| 103 | +import virtualDeviceManagerMenuItem from '/src/assets/android/android_virtual_device_manager_menu.png'; |
| 104 | + |
| 105 | +<Image src={virtualDeviceManagerMenuItem} style={{width: "500px"}} alt="Screenshot Virtual Device Manager Menu Item" /> |
| 106 | + |
| 107 | +You can create any number of devices with different configurations here: |
| 108 | + |
| 109 | +import virtualDeviceManager from '/src/assets/android/android_virtual_device_manager.png'; |
| 110 | + |
| 111 | +<Image src={virtualDeviceManager} style={{width: "500px"}} alt="Screenshot Virtual Device Manager" /> |
| 112 | + |
| 113 | +A good approach is to have one device with the minimum API level supported by your application and |
| 114 | +another one with the latest release to make sure it runs on both. |
| 115 | + |
| 116 | +Running virtual devices connect to `adb` automatically. |
| 117 | + |
| 118 | +#### Virtual Keyboard |
| 119 | + |
| 120 | +Note that depending on the device template you pick, the virtual devices created here might use a |
| 121 | +hardware keyboard by default, which is not helpful for testing your application. Unfortunately, we |
| 122 | +were unable to locate a way to disable it in the Virtual Device Manager directly. |
| 123 | + |
| 124 | +To fix this, click on the three vertical dots next to the device in the manager to open up the menu |
| 125 | +and select "Show on disk". In the directory that now opens, open the file `config.ini` in your |
| 126 | +favorite text editor. Navigate to the line `hw.keyboard=yes` and change it to `hw.keyboard=no`, then |
| 127 | +save the file. |
| 128 | + |
| 129 | +The next challenge is that there is still no keyboard: |
| 130 | + |
| 131 | +import virtualKeyboardStylus from '/src/assets/android/android_virtual_keyboard_stylus.png'; |
| 132 | + |
| 133 | +<Image src={virtualKeyboardStylus} style={{width: "300px"}} alt="Screenshot Stylus Support" /> |
| 134 | + |
| 135 | +Disable the stylus input in the keyboard settings: |
| 136 | + |
| 137 | +import keyboardSettings from '/src/assets/android/android_keyboard_settings.png'; |
| 138 | + |
| 139 | +<Image src={keyboardSettings} style={{width: "300px"}} alt="Screenshot Keyboard Settings" /> |
| 140 | + |
| 141 | +Select "Write in textfields" in the list and then disable that feature. This enables the |
| 142 | +regular virtual keyboard. |
| 143 | + |
| 144 | +### Running the Application |
| 145 | + |
| 146 | +There are multiple ways to build, upload and run Android apps written in Rust. This page describes a |
| 147 | +way using [xbuild](https://github.com/rust-mobile/xbuild). This doesn't use Android Studio at all. |
| 148 | + |
| 149 | +At the time of this writing, the current version of xbuild (0.2.0) is severely outdated and contains |
| 150 | +relevant bugs that have been fixed in the master branch. So, don't use `cargo install xbuild` to |
| 151 | +install it, use the git version instead: |
| 152 | + |
| 153 | +```sh |
| 154 | +cargo install --git https://github.com/rust-mobile/xbuild.git |
| 155 | +``` |
| 156 | + |
| 157 | +The command line tool for xbuild is simply called `x`. For example, to get a list of devices connected, |
| 158 | +use |
| 159 | + |
| 160 | +```sh |
| 161 | +x devices |
| 162 | +``` |
| 163 | + |
| 164 | +Note that unlike `adb` above, this tool also supports iOS devices and simulators. However, for Android |
| 165 | +devices it simply talks to `adb`, so if you connect a device using that tool, it will also show up here. |
| 166 | + |
| 167 | +To build your project, navigate to the directory containing your `Cargo.toml` and run |
| 168 | + |
| 169 | +```sh |
| 170 | +x run --device <id> |
| 171 | +``` |
| 172 | + |
| 173 | +Where `<id>` is shown in `x devices` as the leftmost column and is something like `adb:emulator-1234` |
| 174 | +for virtual Android devices. |
| 175 | + |
| 176 | +This should build your project, upload it to the device and run it. The target platform is detected |
| 177 | +automatically. |
| 178 | + |
| 179 | +To recompile and test changes, press ctrl-c and run the same command again. The running version on the |
| 180 | +device is replaced automatically. |
| 181 | + |
| 182 | +#### Troubleshooting |
| 183 | + |
| 184 | +If `x run` doesn't work, run `x doctor` to check if you have all required tools installed and that |
| 185 | +they're found by xbuild. |
| 186 | + |
| 187 | +### Building |
| 188 | + |
| 189 | +There are many ways to distribute Android applications and xbuild supports all of them via `x build`. |
| 190 | +To get information about the configuration, use `x build --help`. |
| 191 | + |
| 192 | +For example, to build an .apk file, use something like |
| 193 | + |
| 194 | +```sh |
| 195 | +x build --platform android --arch arm64 --format apk --release |
| 196 | +``` |
| 197 | + |
| 198 | +The apk is then located in `target/x/release/android/<name>.apk`. |
0 commit comments