From d21608768b67673406b4d7a546e46b974270cdc5 Mon Sep 17 00:00:00 2001 From: Daniil Anikin <81761954+Heezay@users.noreply.github.com> Date: Sun, 11 Sep 2022 17:10:03 +0300 Subject: [PATCH] Rework docs (#152) * Rework docs * Fix relative paths to files * Alter hello-world.md * Rewrite android-windows install * Rewrite install commands * Update subxt docs * Small code format fix * Rename android-emulator * Fix docs issue * Update subxt tutorial Co-authored-by: David --- README.md | 8 +- .../cli/src/commands/install/sdkmanager.rs | 5 +- docs/src/crossbow/README.md | 4 + docs/src/crossbow/configuration.md | 57 +++++++++ docs/src/crossbundle/README.md | 6 + docs/src/crossbundle/command-build.md | 8 +- docs/src/crossbundle/command-install.md | 29 ++--- docs/src/crossbundle/command-new.md | 17 +++ docs/src/crossbundle/command-run.md | 6 +- docs/src/install/android-linux.md | 83 +++++-------- docs/src/install/android-macos.md | 83 +++++-------- docs/src/install/android-windows.md | 110 +++++------------- docs/src/install/docker.md | 9 +- docs/src/install/set-up-android-device.md | 50 ++++++++ docs/src/tutorials/hello-world.md | 39 +++---- docs/src/tutorials/subxt-with-bevy.md | 30 +++-- 16 files changed, 290 insertions(+), 254 deletions(-) create mode 100644 docs/src/crossbundle/command-new.md create mode 100644 docs/src/install/set-up-android-device.md diff --git a/README.md b/README.md index 31885f76..181c7aad 100644 --- a/README.md +++ b/README.md @@ -52,10 +52,10 @@ Crossbow Plugins: | Name | Description | Status | | ---- | ----------- | ------ | -| [admob-android](./crossbow/admob-android) | [Google AdMob](https://developers.google.com/admob/android/quick-start) Plugin for Android. | πŸ†— | -| [play-games-services](./crossbow/play-games-services) | [Google Play Games Services](https://developers.google.com/games/services/) Plugin for Android. | πŸ†— | -| [play-billing](./crossbow/play-billing) | [Google Play Billing](https://developer.android.com/google/play/billing) Plugin for Android. | πŸ†— | -| [play-core](./crossbow/play-core) | [Google Play Core](https://developer.android.com/guide/playcore) Plugin for Android. | πŸ“ | +| [admob-android](./plugins/admob-android) | [Google AdMob](https://developers.google.com/admob/android/quick-start) Plugin for Android. | πŸ†— | +| [play-games-services](./plugins/play-games-services) | [Google Play Games Services](https://developers.google.com/games/services/) Plugin for Android. | πŸ†— | +| [play-billing](./plugins/play-billing) | [Google Play Billing](https://developer.android.com/google/play/billing) Plugin for Android. | πŸ†— | +| [play-core](./plugins/play-core) | [Google Play Core](https://developer.android.com/guide/playcore) Plugin for Android. | πŸ“ | Helper crates: diff --git a/crossbundle/cli/src/commands/install/sdkmanager.rs b/crossbundle/cli/src/commands/install/sdkmanager.rs index 9e5cc1d8..63478200 100644 --- a/crossbundle/cli/src/commands/install/sdkmanager.rs +++ b/crossbundle/cli/src/commands/install/sdkmanager.rs @@ -9,7 +9,7 @@ use std::path::Path; #[derive(Parser, Clone, Debug, Default)] pub struct SdkManagerInstallCommand { /// Install all preferred tools for correct crossbundle work. It will install - /// build-tools;31.0.0, ndk;23.1.7779620 and platforms;android-31 + /// build-tools;31.0.0, ndk;23.1.7779620, platforms;android-31 and platform-tools #[clap(long, short)] pub preferred_tools: bool, /// List installed and available packages. Use the channel option to include a package @@ -210,7 +210,8 @@ impl SdkManagerInstallCommand { sdkmanager .arg("build-tools;31.0.0") .arg("ndk;23.1.7779620") - .arg("platforms;android-31"); + .arg("platforms;android-31") + .arg("platform-tools"); } if let Some(channel) = &self.channel { sdkmanager.arg(format!("--channel={}", channel)); diff --git a/docs/src/crossbow/README.md b/docs/src/crossbow/README.md index 4ceb7b3f..e6506566 100644 --- a/docs/src/crossbow/README.md +++ b/docs/src/crossbow/README.md @@ -1,3 +1,7 @@ # Overview In this category, you will learn how to use the `crossbow` crate. + +- [Project configuration](./configuration.md) +- [Android plugins](./android-plugins.md) +- [Permissions](./permissions.md) \ No newline at end of file diff --git a/docs/src/crossbow/configuration.md b/docs/src/crossbow/configuration.md index c70d2307..006beafc 100644 --- a/docs/src/crossbow/configuration.md +++ b/docs/src/crossbow/configuration.md @@ -15,16 +15,73 @@ edition = "2021" crossbow = "0.2.3" [package.metadata] +# The user-friendly application name for your app. Displayed in the applications menu app_name = "Game" +# Android assets directory path relatively to project path assets = ["assets"] +# Path to icon with `.png` format that will be provided to generate mipmap resources icon = "path/to/icon.png" [package.metadata.android] +# Android application wrapper: supports ndk-glue and sokol. Now ndk-glue used by bevy engine and sokol used by macroquad +app_wrapper = "quad" +# Android targets to build on debug or release. +debug_build_targets = ["aarch64-linux-android"] release_build_targets = ["aarch64-linux-android"] +# Android resources directory path relatively to project path resources = ["res/android"] +# Complete support of all AndroidManifest.xml attributes +[package.metadata.android.manifest] +package = "com.example.ExampleProject" + +# Adds a uses-permission element to the AndroidManifest.xml. +# Note that android_version 23 and higher, Android requires the application to request permissions at runtime +[[package.metadata.android.manifest.uses_permission]] +name = "android.permission.INTERNET" +# Specifies that an app wants a particular permission, but only if the app is installed on a device running +# Android 6.0 (API level 23) or higher. If the device is running API level 22 or lower, the app does not have the specified permission. + +# See https://developer.android.com/guide/topics/manifest/uses-permission-sdk-23-element +[[package.metadata.android.manifest.uses_permission_sdk_23]] +name = "android.permission.WRITE_EXTERNAL_STORAGE" +max_sdk_version = 30 + +# See https://developer.android.com/guide/topics/manifest/service-element +[[package.metadata.android.manifest.service]] +name = "UpdateService" +intent_filter = [] +meta_data = [] + +# See https://developer.android.com/guide/topics/manifest/queries-element#provider +[[package.metadata.android.manifest.queries.provider]] +authorities = "org.khronos.openxr.runtime_broker;org.khronos.openxr.system_runtime_broker" +# Note: The `name` attribute is normally not required for a queries provider, but is non-optional +# as a workaround for aapt throwing errors about missing `android:name` attribute. +# This will be made optional if/when cargo-apk migrates to aapt2. +name = "org.khronos.openxr" + +# See https://developer.android.com/guide/topics/manifest/uses-feature-element +# +# Note: there can be multiple .uses_feature entries. +[[package.metadata.android.manifest.features]] +name = "android.hardware.vulkan.level" +required = true +version = 1 + +# See https://developer.android.com/guide/topics/manifest/meta-data-element +[[package.metadata.android.manifest.application.meta_data]] +name = "com.oculus.vr.focusaware" +value = "true" + [package.metadata.apple] release_build_targets = ["aarch64-apple-ios", "x86_64-apple-ios"] +# The user-friendly application name for your app. Displayed in the applications menu +app_name = "Example" +# Apple targets to build on debug or release. +debug_build_targets = ["aarch64-apple-ios"] +release_build_targets = ["aarch64-apple-ios", "x86_64-apple-ios"]. +# Apple resources directory path relatively to project path. resources = ["res/apple"] ``` diff --git a/docs/src/crossbundle/README.md b/docs/src/crossbundle/README.md index 9cebb909..c5c38cb9 100644 --- a/docs/src/crossbundle/README.md +++ b/docs/src/crossbundle/README.md @@ -1,3 +1,9 @@ # Overview In this category, you will learn how to use the `crossbundle` tool. + +- [Crossbundle build command](command-build.md) +- [Crossbundle run command](command-run.md) +- [Crossbundle install command](command-install.md) +- [Crossbundle new command](command-new.md) + diff --git a/docs/src/crossbundle/command-build.md b/docs/src/crossbundle/command-build.md index 6d90da90..45893978 100644 --- a/docs/src/crossbundle/command-build.md +++ b/docs/src/crossbundle/command-build.md @@ -1,4 +1,6 @@ -# Crossbow gradle +# Crossbundle build command + +## Crossbundle build gradle Crossbow default build process requires installed Gradle on your PC. @@ -19,6 +21,8 @@ gradle installDebug Also you can replace `build` with `run` subcommand to build and run APK on your device (it uses `installDebug` command under the hood). To see how to set android emulator check install recommendations for [linux-android](./install-linux-android.md), [macos-android](./install-macos-android.md), [windows-android](./install-windows-android.md). +## Crossbundle build native AAB/APK + If you don't want to use gradle you can specify it in strategy native-apk: ```sh @@ -31,4 +35,4 @@ To find out available commands specify the -h flag. ```sh crossbundle build android -h -``` \ No newline at end of file +``` diff --git a/docs/src/crossbundle/command-install.md b/docs/src/crossbundle/command-install.md index f75cde3d..71641f88 100644 --- a/docs/src/crossbundle/command-install.md +++ b/docs/src/crossbundle/command-install.md @@ -1,12 +1,23 @@ -# Setup packages with crossbundle install +# Crossbundle install command -Use `crossbundle` install command to install necessary packages. To find out available commands specify the -h flag. +## Setup packages + +Use `crossbundle` install command to install necessary packages. To find out available commands specify the `-h` flag. The `-h` flag can be used in all subcommands crossbundle install offers. ```sh crossbundle install -h +crossbundle install command-line-tools -h +``` + +## Install tools to APK building + +We offer to use our command to fast installation all required packages. + +```sh +crossbundle install --preferred ``` -## Install tools to APK correct building +This command will setup command line tools, Android platforms, build-tools, Android NDK and bundletool for AAB correct working. To provide custom installation read the article below. ### Install command-line tools @@ -27,12 +38,6 @@ Note: Android studio install cmdline tools into `$SDK_ROOT/cmdline-tools//gradle`. But you can specify your own build directory via `--export-path=` flag. +## Crossbundle run native AAB/APK + If you don't want to use gradle you can specify it in strategy native-apk: ```sh diff --git a/docs/src/install/android-linux.md b/docs/src/install/android-linux.md index e1b46f29..0e9b6879 100644 --- a/docs/src/install/android-linux.md +++ b/docs/src/install/android-linux.md @@ -2,7 +2,7 @@ ## Install necessary packages -1. Use [crossbundle install command](/~https://github.com/dodorare/crossbow/blob/main/docs/crossbundle-install-command.md) or download and install [Android Studio](https://developer.android.com/studio). +1. Use [crossbundle install command](../crossbundle/command-install.md) or download and install [Android Studio](https://developer.android.com/studio). 2. Start Android Studio, and go through the `Android Studio Setup Wizard` with the `Custom` option and install the following (or install them in `SDK Manager`): - Android SDK - NDK (Side by side) @@ -10,31 +10,33 @@ - Android SDK Build-Tools - Android SDK Platform-tools -## Add environment variables - -Take these steps to add Android-related environment variables: - -- From the Start search bar, enter β€˜env’ and select **Edit environment variables for your account**. -- Add `ANDROID_SDK_ROOT`||`ANDROID_SDK_PATH`||`ANDROID_HOME` and `ANDROID_NDK_ROOT`||`ANDROID_NDK_PATH`||`NDK_HOME`to environment variables. +## Install necessary rustup targets -For that edit **~/.bash_profile** or **~/.bashrc** files so they contain those lines: +Run the following command: ```sh -export ANDROID_SDK_ROOT=$HOME/Android/Sdk -export ANDROID_NDK_ROOT=$HOME/Android/Sdk/ndk/23.1.7779620 +rustup target add armv7-linux-androideabi aarch64-linux-android i686-linux-android x86_64-linux-android ``` -If u will build application with emulator u should add this environment variables: +## Add environment variables -```sh -export PATH=\sdk\emulator:$PATH -export PATH=\sdk\tools\bin:$PATH -``` +From the Start search bar, enter `env` and select **Edit environment variables for your account**. -Crossbow default build process requires installed Gradle on your PC. You can download it [here](https://services.gradle.org/distributions/). Set to environment variable. +| Building strategy | Key | Value | Description | +| ----------------- | ---- | ----------- | ------------| +| Gradle project, native APK/AAB| ANDROID_SDK_ROOT | \Sdk | Can be replaced with ANDROID_SDK_PATH and ANDROID_HOME. You might not install this env var if you used [crossbundle install](../crossbundle/command-install.md) to set up required packages | +| | | | or just want to build native APK or native AAB | +| Native APK/AAB | ANDROID_NDK_ROOT | \Sdk\ndk\ | Can be replaced with ANDROID_NDK_PATH and NDK_HOME. You might not install this env var if you used [crossbundle install](../crossbundle/command-install.md) to set up required packages | +| Gradle project | GRADLE_HOME | | Crossbow default build process requires installed Gradle on your PC. You can download it [here](https://services.gradle.org/distributions/) | +| Native AAB | BUNDLETOOL_PATH | | Download bundletool from the [`GitHub repository`](/~https://github.com/google/bundletool/releases) or use [crossbundle install](../crossbundle/command-install.md) | + +For that edit **~/.bash_profile** or **~/.bashrc** files so they contain those lines: ```sh +export ANDROID_SDK_ROOT=$HOME/Android/Sdk +export ANDROID_NDK_ROOT=$HOME/Android/Sdk/ndk/23.1.7779620 export GRADLE_HOME= +export BUNDLETOOL_PATH= ``` Also, we need to make sure we have a java runtime environment (JRE) installed. We need a key tool utility from there.
@@ -48,52 +50,19 @@ Examples: - Ubuntu: `sudo apt install default-jdk` - Manjaro (Arch): `sudo pacman -S jre11-openjdk-headless jre11-openjdk jdk11-openjdk openjdk11-doc openjdk11-src` -### If you want to generate AAB (Android App Bundle) u will need to install Bundletool - -If you haven't already done so, download bundletool from the [`GitHub repository`](/~https://github.com/google/bundletool/releases). - -```sh -export BUNDLETOOL_PATH= -``` - ## Set up your Android device -To prepare to run your `Crossbow` app on an Android device, you need an Android device running Android 4.1 (API level 16) or higher. - -1. Enable **Developer options** and **USB debugging** on your device. Detailed instructions are available in the [Android documentation](https://developer.android.com/studio/debug/dev-options). -2. Using a USB cable, plug your phone into your computer. If prompted on your device, authorize your computer to access your device. - -## Set up the Android emulator - -To prepare to run and test your Crossbow app on the Android emulator, follow these steps if you want to install it from the console: - -```sh -# Run following command to install System Image for Android SDK 31 -crossbundle install sdkmanager --install "system-images;android-31;google_apis;x86_64" -# Run this command to create a new emulator -avdmanager create avd -n Phone -k "system-images;android-31;google_apis;x86_64" -# And finally run this command to start the emulator -emulator -avd=Phone -``` - -If you want to install it from the GUI, follow these instructions: +Follow the link to find out how to set up your device or [android emulator](./set-up-android-device.md) -1. Enable [`VM acceleration`](https://developer.android.com/studio/run/emulator-acceleration) on your machine. -2. Launch **Android Studio**, click the **AVD Manager** icon, and select **Create Virtual Device**. -3. Choose a device definition and select **Next**. -4. Select one or more system images for the Android versions you want to emulate, and select **Next**. An x86 or x86_64 image is recommended. -5. Under Emulated Performance, select **Hardware - GLES 2.0** to enable [`hardware acceleration`](https://developer.android.com/studio/run/emulator-acceleration). -6. Verify the AVD configuration is correct, and select **Finish**. (For details on the above steps, see [`Managing AVDs`](https://developer.android.com/studio/run/managing-avds)) -7. In Android Virtual Device Manager, click Run in the toolbar. The emulator starts up and displays the default canvas for your selected OS version and device. +## Next step -## Install necessary rustup targets +See [hello-world](../tutorials/hello-world.md) to configure your project -Run the following command: +After previous steps you can use crossbundle to build gradle project or native APK/AAB. Go to the links: -```sh -rustup target add armv7-linux-androideabi aarch64-linux-android i686-linux-android x86_64-linux-android -``` +- [Crossbundle build command](../crossbundle/command-build.md) +- [Crossbundle run command](../crossbundle/command-run.md) +- [Crossbundle install command](../crossbundle/command-install.md) +- [Crossbundle new command](../crossbundle/command-new.md) -## Next step -[`Hello World! application`](/~https://github.com/dodorare/crossbow/wiki/Hello-World!) with Crossbow diff --git a/docs/src/install/android-macos.md b/docs/src/install/android-macos.md index 25ff9cd8..456d75dd 100644 --- a/docs/src/install/android-macos.md +++ b/docs/src/install/android-macos.md @@ -2,7 +2,7 @@ ## Install necessary packages -1. Use [crossbundle install command](/~https://github.com/dodorare/crossbow/blob/main/docs/crossbundle-install-command.md) or download and install [Android Studio](https://developer.android.com/studio). +1. Use [crossbundle install command](../crossbundle/command-install.md) or download and install [Android Studio](https://developer.android.com/studio). 2. Start Android Studio, and go through the `Android Studio Setup Wizard` with the `Custom` option and install the following (or install them in `SDK Manager`): - Android SDK - NDK (Side by side) @@ -16,82 +16,51 @@ brew tap adoptopenjdk/openjdk brew install --cask adoptopenjdk8 ``` -## Add environment variables - -Take these steps to add Android-related environment variables: - -- From the Start search bar, enter β€˜env’ and select **Edit environment variables for your account**. -- Add `ANDROID_SDK_ROOT`||`ANDROID_SDK_PATH`||`ANDROID_HOME` and `ANDROID_NDK_ROOT`||`ANDROID_NDK_PATH`||`NDK_HOME`to environment variables. +## Install necessary rustup targets -For that edit **~/.bash_profile**/**~/.bashrc** or **~/.zshrc** files so they contain those lines: +Run the following command: ```sh -export ANDROID_SDK_ROOT=$HOME/android/sdk -export ANDROID_NDK_ROOT=$ANDROID_SDK_ROOT/ndk/23.1.7779620 +rustup target add armv7-linux-androideabi aarch64-linux-android i686-linux-android x86_64-linux-android ``` -If u will build application with emulator u should add this environment variables: +## Add environment variables -```sh -export PATH=\sdk\emulator:$PATH -export PATH=\sdk\tools\bin:$PATH -``` +From the Start search bar, enter β€˜env’ and select **Edit environment variables for your account**. -Crossbow default build process requires installed Gradle on your PC. You can download it [here](https://services.gradle.org/distributions/). Set to environment variable. +| Building strategy | Key | Value | Description | +| ----------------- | ---- | ----------- | ------------| +| Gradle project, native APK/AAB| ANDROID_SDK_ROOT | \Sdk | Can be replaced with ANDROID_SDK_PATH and ANDROID_HOME. You might not install this env var if you used [crossbundle install](../crossbundle/command-install.md) to set up required packages | +| | | | or just want to build native APK or native AAB | +| Native APK/AAB | ANDROID_NDK_ROOT | \Sdk\ndk\ | Can be replaced with ANDROID_NDK_PATH and NDK_HOME. You might not install this env var if you used [crossbundle install](../crossbundle/command-install.md) to set up required packages | +| Gradle project | GRADLE_HOME | | Crossbow default build process requires installed Gradle on your PC. You can download it [here](https://services.gradle.org/distributions/) | +| Native AAB | BUNDLETOOL_PATH | | Download bundletool from the [`GitHub repository`](/~https://github.com/google/bundletool/releases) or use [crossbundle install](../crossbundle/command-install.md) | + +For that edit **~/.bash_profile**/**~/.bashrc** or **~/.zshrc** files so they contain those lines: ```sh +export ANDROID_SDK_ROOT=$HOME/android/sdk +export ANDROID_NDK_ROOT=$ANDROID_SDK_ROOT/ndk/23.1.7779620 export GRADLE_HOME= +export BUNDLETOOL_PATH= ``` Also, we need to make sure we have a java runtime environment (JRE) installed. We will need a key tool utility from there.
To make sure it's present type this command: `ls /usr/lib/jvm/default/bin/ | grep keytool` or add to your `PATH` env var. -### If you want to generate AAB (Android App Bundle) u will need to install Bundletool - -If you haven't already done so, download bundletool from the [`GitHub repository`](/~https://github.com/google/bundletool/releases). - -```sh -export BUNDLETOOL_PATH= -``` - ## Set up your Android device -To prepare to run your `crossbow` app on an Android device, you need an Android device running Android 4.1 (API level 16) or higher. - -1. Enable **Developer options** and **USB debugging** on your device. Detailed instructions are available in the [Android documentation](https://developer.android.com/studio/debug/dev-options). -2. Using a USB cable, plug your phone into your computer. If prompted on your device, authorize your computer to access your device. - -## Set up the Android emulator - -To prepare to run and test your Crossbow app on the Android emulator, follow these steps if you want to install it from the console: - -```sh -# Run following command to install System Image for Android SDK 31 -crossbundle install sdkmanager --install "system-images;android-31;google_apis;x86_64" -# Run this command to create a new emulator -avdmanager create avd -n Phone -k "system-images;android-31;google_apis;x86_64" -# And finally run this command to start the emulator -emulator -avd=Phone -``` - -If you want to install it from the GUI, follow these instructions: +Follow the link to find out how to set up your device or [android emulator](./set-up-android-device.md) -1. Enable [`VM acceleration`](https://developer.android.com/studio/run/emulator-acceleration) on your machine. -2. Launch **Android Studio**, click the **AVD Manager** icon, and select **Create Virtual Device**. -3. Choose a device definition and select **Next**. -4. Select one or more system images for the Android versions you want to emulate, and select **Next**. An x86 or x86_64 image is recommended. -5. Under Emulated Performance, select **Hardware - GLES 2.0** to enable [`hardware acceleration`](https://developer.android.com/studio/run/emulator-acceleration). -6. Verify the AVD configuration is correct, and select **Finish**. (For details on the above steps, see [`Managing AVDs`](https://developer.android.com/studio/run/managing-avds)) -7. In Android Virtual Device Manager, click Run in the toolbar. The emulator starts up and displays the default canvas for your selected OS version and device. +## Next step -## Install necessary rustup targets +See [hello-world](../tutorials/hello-world.md) to configure your project -Run the following command: +After previous steps you can use crossbundle to build gradle project or native APK/AAB. Go to the links: -```sh -rustup target add armv7-linux-androideabi aarch64-linux-android i686-linux-android x86_64-linux-android -``` +- [Crossbundle build command](../crossbundle/command-build.md) +- [Crossbundle run command](../crossbundle/command-run.md) +- [Crossbundle install command](../crossbundle/command-install.md) +- [Crossbundle new command](../crossbundle/command-new.md) -## Next step -[`Hello World! application`](/~https://github.com/dodorare/crossbow/wiki/Hello-World!) with Crossbow diff --git a/docs/src/install/android-windows.md b/docs/src/install/android-windows.md index c21b1c5d..850e3749 100644 --- a/docs/src/install/android-windows.md +++ b/docs/src/install/android-windows.md @@ -2,7 +2,7 @@ ## Install necessary packages -1. Use [crossbundle install command](/~https://github.com/dodorare/crossbow/blob/main/docs/crossbundle-install-command.md) or download and install [Android Studio](https://developer.android.com/studio). +1. Use [crossbundle install command](../crossbundle/command-install.md) or download and install [Android Studio](https://developer.android.com/studio). 2. Start Android Studio, and go through the `Android Studio Setup Wizard` with the `Custom` option and install the following (or install them in `SDK Manager`): - Android SDK - NDK (Side by side) @@ -10,101 +10,51 @@ - Android SDK Build-Tools - Android SDK Platform-tools -## Add environment variables - -Take these steps to add Android-related environment variables: - -- From the Start search bar, enter β€˜env’ and select **Edit environment variables for your account**. -- Add `ANDROID_SDK_ROOT`||`ANDROID_SDK_PATH`||`ANDROID_HOME` and `ANDROID_NDK_ROOT`||`ANDROID_NDK_PATH`||`NDK_HOME`to environment variables. -- Add `ANDROID_SDK_ROOT` variable with value `\sdk`.
(ex. `C:\Users\username\AppData\Local\android\sdk`) -- Add `ANDROID_NDK_ROOT` variable with value `\sdk\ndk\`.
(ex. `C:\Users\username\AppData\Local\Android\Sdk\ndk\23.1.7779620`) - -Or you can install via command line - -```sh -SETX ANDROID_SDK_ROOT "path_to_sdk\sdk" /M -SETX ANDROID_NDK_ROOT "path_to_sdk\sdk\ndk\version" /M -``` - -Crossbow default build process requires installed Gradle on your PC. You can download it [here](https://services.gradle.org/distributions/). Set to environment variable. +## Install necessary rustup targets -- Add `GRADLE_HOME` variable with value ``. +Run the following command: ```sh -SETX GRADLE_HOME "path_to_gradle" /M +rustup target add armv7-linux-androideabi aarch64-linux-android i686-linux-android x86_64-linux-android ``` -If you will build application with emulator you should add this to environment variables: +## Add environment variables -- Add `\sdk\tools\bin` to `PATH` variable. -- Add `\sdk\emulator` to `PATH` variable. +From the Start search bar, enter `env` and select **Edit environment variables for your account**. -```sh -SETX "\sdk\tools\bin" ~PATH~ -SETX "\sdk\emulator" ~PATH~ -``` +| Building strategy | Key | Value | Description | +| ----------------- | ---- | ----------- | ------------| +| Gradle project, native APK/AAB| ANDROID_SDK_ROOT | \Sdk | Can be replaced with ANDROID_SDK_PATH and ANDROID_HOME. You might not install this env var if you used [crossbundle install](../crossbundle/command-install.md) to set up required packages | +| | | | or just want to build native APK or native AAB | +| Native APK/AAB | ANDROID_NDK_ROOT | \Sdk\ndk\ | Can be replaced with ANDROID_NDK_PATH and NDK_HOME. You might not install this env var if you used [crossbundle install](../crossbundle/command-install.md) to set up required packages | +| Gradle project, native APK/AAB| JAVA_HOME | \bin | Also, we need to make sure we have a [java runtime environment](https://www.oracle.com/java/technologies/downloads/) (JRE) | +| | | | or [Java developer kit](https://www.oracle.com/java/technologies/downloads/) (JDK) installed. We need jarsigner utility from there | +| Gradle project | GRADLE_HOME | | Crossbow default build process requires installed Gradle on your PC. You can download it [here](https://services.gradle.org/distributions/) | +| Native AAB | BUNDLETOOL_PATH | | Download bundletool from the [`GitHub repository`](/~https://github.com/google/bundletool/releases) or use [crossbundle install](../crossbundle/command-install.md) | -Also, we need to make sure we have a [java runtime environment](https://www.oracle.com/java/technologies/downloads/) (JRE) or [Java developer kit](https://www.oracle.com/java/technologies/downloads/) (JDK) installed. We need a key tool utility from there.
-To make sure it's present type this command: `keytool -h` - -- If command above fails, add `\bin` to `PATH` environment variable.
(ex. `C:\Program Files\Android\Android Studio\jre\bin`)
(ex. `C:\Program Files\java\jdk\bin`) +Or you can install required env via command line accordingly table above. Arguments were provided for example ```sh -SETX JAVA_HOME "path_to_jdk" /M +SETX ANDROID_SDK_ROOT "C:\Users\Username\AppData\Local\Android\Sdk" /M +SETX ANDROID_NDK_ROOT "C:\Users\Username\AppData\Local\Android\Sdk\ndk\23.1.7779620" /M +SETX JAVA_HOME "C:\Program Files\Java\jdk-11.0.15+10" /M +SETX GRADLE_HOME "C:\Gradle\gradle-7.4.2" /M +SETX BUNDLETOOL_PATH "C:\Users\Username\bundletool-all-1.8.2.jar" /M ``` - -You have to close and reopen any existing console windows for these changes to take effect. - -### If you want to generate AAB (Android App Bundle) u will need to install Bundletool - -If you haven't already done so, download bundletool from the [`GitHub repository`](/~https://github.com/google/bundletool/releases). - -- Add `BUNDLETOOL_PATH` variable with value ``. - -```sh -SETX BUNDLETOOL_PATH "path_to_bundletool" /M -``` +> You have to close and reopen any existing console windows for these changes to take effect. ## Set up your Android device -To prepare to run your `Crossbow` app on an Android device, you need an Android device running Android 4.1 (API level 16) or higher. - -1. Enable **Developer options** and **USB debugging** on your device. Detailed instructions are available in the [Android documentation](https://developer.android.com/studio/debug/dev-options). -2. Windows-only: Install the [Google USB Driver](https://developer.android.com/studio/run/win-usb). -3. Using a USB cable, plug your phone into your computer. If prompted on your device, authorize your computer to access your device. - -## Set up the Android emulator - -To prepare to run and test your Crossbow app on the Android emulator, follow these steps if you want to install it from the console: - -```sh -# Run following command to install System Image for Android SDK 31 -crossbundle install sdkmanager --install "system-images;android-31;google_apis;x86_64" -# Run this command to create a new emulator -avdmanager create avd -n Phone -k "system-images;android-31;google_apis;x86_64" -# And finally run this command to start the emulator -emulator -avd=Phone -``` - -If you want to install it from the GUI, follow these instructions: +Follow the link to find out how to set up your device or [android emulator](./set-up-android-device.md) -1. Enable [`VM acceleration`](https://developer.android.com/studio/run/emulator-acceleration) on your machine. -2. Launch **Android Studio**, click the **AVD Manager** icon, and select **Create Virtual Device**. -3. Choose a device definition and select **Next**. -4. Select one or more system images for the Android versions you want to emulate, and select **Next**. An x86 or x86_64 image is recommended. -5. Under Emulated Performance, select **Hardware - GLES 2.0** to enable [`hardware acceleration`](https://developer.android.com/studio/run/emulator-acceleration). -6. Verify the AVD configuration is correct, and select **Finish**. (For details on the above steps, see [`Managing AVDs`](https://developer.android.com/studio/run/managing-avds)) -7. In Android Virtual Device Manager, click Run in the toolbar. The emulator starts up and displays the default canvas for your selected OS version and device. +## Next step -## Install necessary rustup targets +See [hello-world](../tutorials/hello-world.md) to configure your project -Run the following command: - -```sh -rustup target add armv7-linux-androideabi aarch64-linux-android i686-linux-android x86_64-linux-android -``` - -## Next step +After previous steps you can use crossbundle to build gradle project or native APK/AAB. Go to the links: -[`Hello World! application`](/~https://github.com/dodorare/crossbow/wiki/Hello-World!) with Crossbow +- [Crossbundle build command](../crossbundle/command-build.md) +- [Crossbundle run command](../crossbundle/command-run.md) +- [Crossbundle install command](../crossbundle/command-install.md) +- [Crossbundle new command](../crossbundle/command-new.md) diff --git a/docs/src/install/docker.md b/docs/src/install/docker.md index 55e4d868..300c7f0a 100644 --- a/docs/src/install/docker.md +++ b/docs/src/install/docker.md @@ -23,15 +23,20 @@ docker pull ghcr.io/dodorare/crossbundle:latest Run the following command at the root of `crossbow` project: +> For unix systems (Bash): ```sh -# For unix systems: docker run --rm -it -v "$(pwd)/:/src" -w /src/examples/macroquad-permissions ghcr.io/dodorare/crossbundle build android --release -# For Windows: +``` + +> For Windows (PowerShell): +```sh docker run --rm -it -v "${pwd}/:/src" -w /src/examples/macroquad-permissions ghcr.io/dodorare/crossbundle build android --release ``` Install APK on connected Android phone via USB: +Follow the link to find out how to set up your device or [android emulator](./set-up-android-device.md) + ```sh adb install ./target/android/macroquad-permissions/gradle/build/outputs/apk/release/gradle-release-unsigned.apk ``` diff --git a/docs/src/install/set-up-android-device.md b/docs/src/install/set-up-android-device.md new file mode 100644 index 00000000..b607ab0b --- /dev/null +++ b/docs/src/install/set-up-android-device.md @@ -0,0 +1,50 @@ +# Set up your Android device + +To prepare to run your `Crossbow` app on an Android device, you need an Android device running Android 4.1 (API level 16) or higher. + +1. Enable **Developer options** and **USB debugging** on your device. Detailed instructions are available in the [Android documentation](https://developer.android.com/studio/debug/dev-options). +2. Using a USB cable, plug your phone into your computer. If prompted on your device, authorize your computer to access your device. + +## Set up the Android emulator + +To prepare to run and test your Crossbow app on the Android emulator, follow these steps if you want to install it from the console: + +```sh +# Run following command to install System Image for Android SDK 31 +crossbundle install sdkmanager --install "system-images;android-31;google_apis;x86_64" +# Run this command to create a new Pnone emulator +avdmanager create avd -n Phone -k "system-images;android-31;google_apis;x86_64" +# And finally run this command to start the emulator +emulator -avd=Phone +``` + +If you want to install it from the GUI, follow these instructions: + +1. Enable [`VM acceleration`](https://developer.android.com/studio/run/emulator-acceleration) on your machine. +2. Launch **Android Studio**, click the **AVD Manager** icon, and select **Create Virtual Device**. +3. Choose a device definition and select **Next**. +4. Select one or more system images for the Android versions you want to emulate, and select **Next**. An x86 or x86_64 image is recommended. +5. Under Emulated Performance, select **Hardware - GLES 2.0** to enable [`hardware acceleration`](https://developer.android.com/studio/run/emulator-acceleration). +6. Verify the AVD configuration is correct, and select **Finish**. (For details on the above steps, see [`Managing AVDs`](https://developer.android.com/studio/run/managing-avds)) +7. In Android Virtual Device Manager, click Run in the toolbar. The emulator starts up and displays the default canvas for your selected OS version and device. + +## Add environment variables + +If you will build application with emulator you should add this to environment variables: + +> Install via command line for for macos and linux: + +```sh +export PATH=\sdk\emulator:$PATH +export PATH=\sdk\tools\bin:$PATH +``` + +> Install via command line for windows: + +- Add `\sdk\tools\bin` to `PATH` variable. +- Add `\sdk\emulator` to `PATH` variable. + +```sh +SETX "\sdk\tools\bin" ~PATH~ +SETX "\sdk\emulator" ~PATH~ +``` \ No newline at end of file diff --git a/docs/src/tutorials/hello-world.md b/docs/src/tutorials/hello-world.md index 07ba39e9..bffbc670 100644 --- a/docs/src/tutorials/hello-world.md +++ b/docs/src/tutorials/hello-world.md @@ -2,26 +2,15 @@ ## Generate a project -`crossbundle` uses [`cargo-generate`](/~https://github.com/cargo-generate/cargo-generate) to generate a new project. This means that you need to install it before we proceed. - -```sh -cargo install cargo-generate -``` - -Then you can create a new project: - -```sh -crossbundle new project-name -# crossbundle new project-name --template bevy -# crossbundle new project-name --template quad -``` - -All supported templates you can watch [`here`](/~https://github.com/dodorare/crossbundle-templates) (each branch = template). +Generate new project with [crossbundle new command](../crossbundle/command-new.md)! ## Project overview The project has been created. Now let's see what the project consists of. +The code below is belong to the native crossbow project with pure rust without [android plugins](../crossbow/android-plugins.md). +To see all possibilities of `cargo.toml` see [crossbow configutarion tutorial](../crossbow/configuration.md) + ```toml # Cargo.toml @@ -39,6 +28,7 @@ app_name = "My Project" icon = "path/to/icon.png" ``` +> We decided to refuse from lib.rs file for a more convenient project configuration. We need only `main.rs` to deploy our code ```rust // main.rs @@ -49,21 +39,18 @@ fn main() { ## Build an application -Let's build and run our first `crossbundle` application. Android commands below will generate gradle project and install apk on your device. +Let's build and run our first `crossbundle` application. Android commands below will generate gradle project and install apk on your device. See [crossbundle run command](/docs/src/crossbundle/command-run.md) for additional information. +> cd project-name. To attach a logger when application deploys on your device use `--log` flag. ```sh -# cd project-name -crossbundle run android -# or -crossbundle run ios +crossbundle run android --log ``` -If you want to build the application for android as native AAB - add `-s=native-aab` flag or add `-s=native-apk` to build native APK. - -When the application deploys on your device, you can attach a logger. - +> or ```sh -crossbundle log android +crossbundle run ios --log ``` -and you will see the message: `"Hello, project-name!"` +If you want to build the application for android as native AAB - add `-s=native-aab` flag or add `-s=native-apk` to build native APK. + +You will see the message: `"Hello, project-name!"` diff --git a/docs/src/tutorials/subxt-with-bevy.md b/docs/src/tutorials/subxt-with-bevy.md index 5c2a8e34..f70d7087 100644 --- a/docs/src/tutorials/subxt-with-bevy.md +++ b/docs/src/tutorials/subxt-with-bevy.md @@ -1,18 +1,20 @@ # Using subxt with bevy engine -1. You need to install crossbundle if you haven't already. See [documention](/~https://github.com/dodorare/crossbow/tree/main/docs) to install it and configure your project. +1. You need to install crossbundle if you haven't already. See [documention](../install/README.md) to install it and configure your project. -2. Specify substrate-subxt and bevy in your Cargo.toml. We prefer to use versions below: +2. Specify `subxt` crate and `bevy` in your Cargo.toml. We prefer to use versions below: -```sh +```toml [dependencies] -substrate-subxt = "0.21" +subxt = "0.23" bevy = "0.8.1" ``` +> You might need additional dependencies to write your code. See [examples/bevy-explorer/cargo.toml](/examples/bevy-explorer/Cargo.toml) + ## Bevy explorer example -To learn how to use subxt with bevy engine, you can go to the [examples/bevy-explorer](/~https://github.com/dodorare/crossbow/tree/main/examples/bevy-explorer) or install bevy explorer template. Follow next steps: +To learn how to use subxt with bevy engine, you can go to the [examples/bevy-explorer](/examples/bevy-explorer/) or install bevy explorer template. Follow next steps: 1. Install cargo-generate: @@ -30,22 +32,32 @@ crossbundle new example --template=bevy-explorer ## Installing application on the device -You can deploy the application on your device with commands below. At first, you should go to example directory. Use it: +You can deploy the application on your device or [android emulator](../install/set-up-android-device.md) with commands below. At first, you should go to example directory. Use it: Bash: +> If the template was installed + ```sh -# If the template was installed cd example -# If bevy-explorer example will be used +``` + +> If bevy-explorer example will be used + +```sh cd example/bevy-explorer ``` + By default `crossbundle build android` command will generate gradle project and install apk on your device. To build native `.apk` and `.aab` see commands below. To build native APK and run it on the device using the command. If you want to build an application replaces `run` with `build`. ```sh crossbundle run android -s=native-apk -# or +``` + +> or + +```sh crossbundle run ios ```