diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..124fca7 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,100 @@ +# Contributing to Ruffle Android +🎉 Thanks for your interest in Ruffle! Contributions of all kinds are welcome. + + +* [Contributing to Ruffle Android](#contributing-to-ruffle-android) + * [Building from source](#building-from-source) + * [Requirements](#requirements) + * [Building from Command Line](#building-from-command-line) + * [Building from Android Studio](#building-from-android-studio) + * [Development tips](#development-tips) + * [Limit your targets](#limit-your-targets) + * [Use emulators!](#use-emulators) + * [Troubleshooting](#troubleshooting) + * ["error: Error detecting NDK version for path"](#error-error-detecting-ndk-version-for-path) + * [Code guidelines](#code-guidelines) + * [Rust](#rust) + * [Kotlin](#kotlin) + + +## Building from source +### Requirements +Before you can build the app from source, you'll need to grab a few things. + +- Install Android Studio with at least the Platform SDK (e.g. version 34) and the NDK Tools (e.g. version 26). +- Install jdk 17 (potentially included with Android Studio) +- Install [rust](https://rustup.rs/) +- `cargo install cargo-ndk` +- `rustup target add aarch64-linux-android armv7-linux-androideabi x86_64-linux-android i686-linux-android` +- Set the `ANDROID_NDK_ROOT` environment variable to the location of the versioned ndk folder - for example `ANDROID_NDK_ROOT=$HOME/Android/Sdk/ndk/24.0.8215888/` + +### Building from Command Line +If you're completely using the command line and bypassing Android Studio, make sure that the `local.properties` +file exists at the repository root folder. It can be empty. + +To build the apks run `./gradlew assembleDebug`. You will find the resulting APKs in `app/build/outputs/apk/debug/`. + +### Building from Android Studio +Just open the repository root directory in Android Studio, it should automatically set up all the right things. + +### Development tips +#### Limit your targets +To speed up iteration, you can tell gradle to only build the rust project for one specific target - the emulator/device you're using. +To do this, add `ndkTargets=arm64` (for example) to your `local.properties`. To specify more than one target, separate them with a space. +The default value is all 4 targets, so that's cutting the build time by 75%! + +#### Use emulators! +An Android device is **not** required to build or test Ruffle. Android Studio defaults to deploying and testing on an emulator. + +Feel free to install other emulators to help test different form factors or older versions of Android OS. + +### Troubleshooting + +#### "error: Error detecting NDK version for path" +This means your `ANDROID_NDK_ROOT` environment variable is missing or incorrect. + +## Code guidelines +We have strict guidelines about trivial code quality matters (formatting and easily checkable lints). +These are enforced by Github Actions, but you are encouraged to run these locally to avoid having to iterate *after* a PR has been opened. + +### Rust +Ruffle is built using the latest stable version of the Rust compiler. Nightly and unstable features should be avoided. +The Rust code in Ruffle strives to be idiomatic. The Rust compiler should emit no warnings when building the project. Additionally, all code should be formatted using [`rustfmt`](https://github.com/rust-lang/rustfmt) and linted using [`clippy`](https://github.com/rust-lang/rust-clippy). You can install these tools using `rustup`: + +```sh +rustup component add rustfmt +rustup component add clippy +``` + +You can auto-format your changes with `rustfmt` + +```sh +cargo fmt --all +``` + +And you can run the clippy lints: + +```sh +cargo ndk clippy --all --tests +``` + +Specific warnings and clippy lints can be allowed when appropriate using attributes, such as: + +```rs +#[allow(clippy::float_cmp)] +``` + +### Kotlin +We try to use Kotlin where possible, no Java. Additionally, we try to use best practices and maintain readable, idiomatic code. + +To automatically format all Kotlin code, run: + +```sh +./gradlew ktlintFormat +``` + +And to automatically lint the code, use: + +```sh +./gradlew lint +``` \ No newline at end of file diff --git a/README.md b/README.md index 64d4d19..d396b7b 100644 --- a/README.md +++ b/README.md @@ -18,34 +18,9 @@ You can try this app by downloading and installing one of those. - The `universal` version should work on all 4 of the above architectures, but it's _huge_. -# Build Prerequisites +# Building from source -- Install Android Sudio with at least the Platform SDK (e.g. version 29) and the NDK Tools (e.g. version 25). -- Ensure `java` is Java 17. -- `cargo install cargo-ndk` -- `rustup target add aarch64-linux-android armv7-linux-androideabi x86_64-linux-android i686-linux-android` - -# Build Steps - -```bash -# substitute the appropriate location and version: -export ANDROID_NDK_ROOT=$HOME/Android/Sdk/ndk/24.0.8215888/ -cd app -./gradlew assembleDebug # the "release" version requires a keyfile -``` - -The final APK should be at: `app/ruffle/build/outputs/apk/debug/ruffle-universal-debug.apk` -There are also single-arch split APKs next to it. - -Opening the `app` project in Android Studio for development and debugging also works. - -# Development Tips - -Set the target of `rust-analyzer` to `x86_64-linux-android` (or even `aarch64-linux-android`), to stop one of the NDK crates from erroring out due to compilation to an unsupported platform. - -Also set the `ANDROID_HOME` and `ANDROID_NDK_ROOT` extra environment variables for it to suitable values, so the C parts of the dependencies can also be built by it. - -You may also need to set the `TARGET_CC`, `TARGET_CXX`, and `TARGET_AR` environment variables to the full paths of the (sometimes API level-specific) `clang`, `clang++`, and `llvm-ar` binaries, respectively. +Please see [CONTRIBUTING.md](CONTRIBUTING.md#building-from-source) for details about how to build this repository yourself. ---