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 <[email protected]>
dodorare · Sep 11, 2022 · d216087 · d216087
1 parent f741583
commit d216087
Show file tree

Hide file tree

Showing 16 changed files with 290 additions and 254 deletions.
diff --git 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
@@ -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
@@ -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)
diff --git 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
@@ -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
@@ -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
-```
+```
diff --git 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/<versio
 
 The [sdkmanager](https://developer.android.com/studio/command-line/sdkmanager) is a command-line tool that allows you to view, install, update, and uninstall packages for the Android SDK.
 
-To install packages use the command below. We prefer to use --preferred-tools flag to install minimal required tools needed for crossbundle correct working. This command will setup build-tools, android-ndk and android platforms: 
-
-```sh
-crossbundle install sdkmanager --preferred-tools
-```
-
 Also you can install packages manually. To see all available tools use the -h flag. List installed and available packages:
 
 ```sh
@@ -47,11 +52,7 @@ crossbundle install sdkmanager --install "build-tools;31.0.0" "ndk;23.1.7779620"
 
 The command will install packages into `$HOME\AppData\Local\Android\Sdk\` for Windows, `$HOME/Library/Android/sdk/` for macOS, and `$HOME/Android/sdk/` for Linux.
 
-## Install tools to AAB correct building
-
-For correct AAB building install [bundletool](https://developer.android.com/studio/command-line/bundletool) and tools above.
-
-### Install bundletool
+## Install bundletool to AAB building
 
 To install [bundletool](https://developer.android.com/studio/command-line/bundletool) use command below. To see all available options use the -h flag.
 

diff --git a/docs/src/crossbundle/command-new.md b/docs/src/crossbundle/command-new.md
@@ -0,0 +1,17 @@
+# Crossbundle new command
+
+`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).
diff --git a/docs/src/crossbundle/command-run.md b/docs/src/crossbundle/command-run.md
@@ -1,4 +1,6 @@
-# Run Command
+# Crossbundle run command
+
+## Crossbundle run gradle
 
 Crossbow default run process requires installed Gradle on your PC.
 
@@ -13,6 +15,8 @@ crossbundle run android --export-path=./gen/
 
 By default run directory is `target/android/<project_name>/gradle`. But you can specify your own build directory via `--export-path=<OUT_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
@@ -2,39 +2,41 @@
 
 ## 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)
    - Android SDK Command-line Tools
    - 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=<path_to_sdk>\sdk\emulator:$PATH
-export PATH=<path_to_sdk>\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 | <path_to_sdk>\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 | <path_to_sdk>\Sdk\ndk\<version> | 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 | <path_to_gradle> | Crossbow default build process requires installed Gradle on your PC. You can download it [here](https://services.gradle.org/distributions/) |
+| Native AAB | BUNDLETOOL_PATH | <path_to_bundletool> | 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=<path_to_gradle>
+export BUNDLETOOL_PATH=<path_to_bundletool>
 ```
 
 Also, we need to make sure we have a java runtime environment (JRE) installed. We need a key tool utility from there. <br/>
@@ -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=<path_to_bundletool>
-```
-
 ## 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