Documentation for Mobile Development

REUSE.toml

@@ -283,3 +283,9 @@ path = ["ui-libraries/material/src/ui/icons/**.svg", "ui-libraries/material/exam
 precedence = "aggregate"
 SPDX-FileCopyrightText = "Material Icons <https://github.com/material-icons/material-icons/blob/master/LICENSE>"
 SPDX-License-Identifier = "Apache-2.0"
+
+[[annotations]]
+path = ["docs/astro/src/content/docs/guide/platforms/mobile/**.png"]
+precedence = "aggregate"
+SPDX-FileCopyrightText = "Copyright © SixtyFPS GmbH <[email protected]>"
+SPDX-License-Identifier = "Unlicense"

docs/astro/astro.config.mjs

@@ -160,8 +160,15 @@ export default defineConfig({
                                 items: [
                                     "guide/platforms/desktop",
                                     "guide/platforms/embedded",
-                                    "guide/platforms/android",
-                                    "guide/platforms/ios",
+                                    {
+                                        label: "Mobile",
+                                        collapsed: true,
+                                        items: [
+                                            "guide/platforms/mobile/general",
+                                            "guide/platforms/mobile/android",
+                                            "guide/platforms/mobile/ios",
+                                        ],
+                                    },
                                     "guide/platforms/web",
                                     "guide/platforms/other",
                                 ],

docs/astro/src/content/docs/guide/platforms/mobile/android.mdx

@@ -0,0 +1,189 @@
+---
+<!-- Copyright © SixtyFPS GmbH <[email protected]> ; SPDX-License-Identifier: MIT -->
+title: Android
+description: Android Platform Guide
+---
+
+import LangRefLink from '@slint/common-files/src/components/LangRefLink.astro';
+
+:::note[Note]
+When developing Slint applications for Android, you can only use Rust as the programming language.
+:::
+
+Also see the documentation of the <LangRefLink lang="rust-slint" relpath="android/">android module in our Rust API documentation</LangRefLink>.
+
+## Project Setup
+
+Slint uses the [android-activity crate](https://github.com/rust-mobile/android-activity) as the interface to
+the operating system, which is re-exported as `slint::android::android_activity`. So, you need to follow the same steps to get started.
+
+First, your project needs to be a library crate. Add the following to your `Cargo.toml`:
+
+```toml
+[lib]
+crate_type = ["cdylib"]
+```
+
+You also need to select the version of android-activity you want to use. This is done by selecting one of these
+two features on the Slint crate:
+
+* `backend-android-activity-06` (version 0.6.x)
+* `backend-android-activity-05` (version 0.5.x)
+
+For example:
+
+```toml
+[dependencies]
+slint = { version = "...", features = ["backend-android-activity-06"] }
+```
+
+Unless you depend on version 0.5 due to some other crate, we recommend to use `backend-android-activity-06`.
+
+This feature is ignored for any target\_os that is not Android. So, it can safely be enabled anywhere.
+
+Second, in your `lib.rs`, add this function:
+
+```rs
+#[cfg(target_os = "android")]
+#[unsafe(no_mangle)]
+fn android_main(app: slint::android::AndroidApp) {
+    slint::android::init(app).unwrap();
+    let main_window = ...; // window generated by the Slint macros
+    main_window.run().unwrap();
+}
+```
+
+You can also add an Android event
+([`android_activity::PollEvent`](https://docs.rs/android-activity/latest/android_activity/enum.PollEvent.html))
+listener by replacing the call to `slint::android::init` with `slint::android::init_with_event_listener`.
+
+That's it!
+
+## Android Setup
+
+The Android development workflow centers around the `adb` command line tool. With it, you can connect to
+Android devices and emulators to upload and run applications (and do other things not relevant here).
+
+The easiest way to install the Android development environment is to download and install
+[Android Studio](https://developer.android.com/studio). It contains an SDK manager in its settings pane
+that enables you to download and install all SDK versions you need. Usually it's recommended to use the
+latest version available, because they can be configured to be backwards-compatible with older versions
+of Android. This manager is available in the settings in "Languages & Frameworks" > "Android SDK".
+
+![Android SDK Manager](android_sdk_manager.png)
+
+Also note the SDK location on top, this path might have to be used for the `ANDROID_HOME` environment
+variable if the build tools can't detect it automatically.
+
+Also, the directory platform-tools in that location contains the adb tool mentioned above, and so
+should be added to your PATH (the way to do this depends on your development platform and is outside
+the scope of this guide).
+
+To get the list of Android devices, simulators and emulators currently attached to your machine, run
+
+```sh
+> adb devices
+```
+
+You can connect to a physical device on the network by using
+
+```sh
+> adb connect <host>
+```
+
+The `host` is the IP address of the device. Note that it has to have development mode enabled for
+this.
+
+### Virtual Device Setup
+
+We recommand developing using a virtual device first, because it speeds up the development cycle.
+However, eventually you have to also test on a device to make sure that the interface is usable on a
+touch screen and to check if all text is large enough, etc.
+
+To create and run a virtual device, use the Virtual Device Manager available in Android Studio. You
+can open it from its main screen under "More Actions":
+
+![Virtual Device Manager Menu Item](android_virtual_device_manager_menu.png)
+
+You can create any number of devices with different configurations here:
+
+![Virtual Device Manager](android_virtual_device_manager.png)
+
+A good approach is to have one device with the minimum API level supported by your application and
+another one with the latest release to make sure it runs on both.
+
+Running virtual devices should be connected to `adb` automatically.
+
+#### Virtual Keyboard
+
+Note that depending on the device template you pick, the virtual devices created here might use a
+hardware keyboard by default, which is not helpful for testing your application. Unfortunately, we
+were unable to locate a way to disable it in the Virtual Device Manager directly.
+
+To fix this, click on the three vertical dots next to the device in the manager to open up the menu
+and select "Show on disk". In the directory that now opens, open the file `config.ini` in your
+favorite text editor. Navigate to the line `hw.keyboard=yes` and change it to `hw.keyboard=no`, then
+save the file.
+
+The next challenge is that there is still no keyboard:
+
+![Stylus](android_virtual_keyboard_stylus.png)
+
+You have to disable the stylus input. Go to the keyboard settings:
+
+![Keyboard Settings Menu Item](android_keyboard_settings.png)
+
+Select "Write in textfields" in the list and then disable that feature. This should enable the
+regular virtual keyboard.
+
+### Running the Application
+
+There are multiple ways to build, upload and run Android apps written in Rust. This page describes using
+[xbuild](https://github.com/rust-mobile/xbuild). This does not use Android Studio at all.
+
+At the time of this writing, the current version of xbuild (0.2.0) is severly outdated and contains
+relevant bugs that have been fixed in the master branch. So, don't use `cargo install xbuild` to
+install it, clone the repository and use `cargo install --path .` while in the clone.
+
+The command line tool for xbuild is simply called `x`. For example, to get a list of devices connected,
+use
+
+```sh
+x devices
+```
+
+Note that unlike `adb` above, this tool also supports iOS devices and simulators. However, for Android
+devices it simply talks to `adb`, so if you connect a device using that tool, it will also show up here.
+
+To build your project, navigate to the directory containing your `Cargo.toml` and run
+
+```sh
+x run --device <id>
+```
+
+Where `<id>` is shown in `x devices` as the leftmost column and is something like `adb:emulator-1234`
+for virtual Android devices.
+
+This should build your project, upload it to the device and run it. The target platform is detected
+automatically.
+
+To recompile and test changes, press ctrl-c and run the same command again. The running version on the
+device is replaced automatically.
+
+#### Troubleshooting
+
+If `x run` doesn't work, run `x doctor` to check if you have all required tools installed and that
+they're found by xbuild.
+
+### Building
+
+There are many ways to distribute Android applications and xbuild supports all of them via `x build`.
+To get information about the configuration, use `x build --help`.
+
+For example, to build an .apk file, use something like
+
+```sh
+x build --platform android --arch arm64 --format apk --release
+```
+
+The apk is then located in `target/x/release/android/<name>.apk`.