diff --git a/.gitmodules b/.gitmodules index 9b6db4b..4bef52b 100644 --- a/.gitmodules +++ b/.gitmodules @@ -6,3 +6,7 @@ path = repositories/revanced-manager url = git@github.com:revanced/revanced-manager.git branch = docs +[submodule "repositories/revanced-cli"] + path = repositories/revanced-cli + url = git@github.com:revanced/revanced-cli.git + branch = feat/docs diff --git a/README.md b/README.md index c613214..99b0448 100644 --- a/README.md +++ b/README.md @@ -4,6 +4,7 @@ Documentation for ReVanced, also contains guides, walkthroughs and tutorials. ## 📖 Table of contents +- [💻 ReVanced CLI](./docs/revanced-cli) - [🧩 ReVanced Patches](./docs/revanced-patches) - [💊 ReVanced Manager](./docs/revanced-manager) -- [💻 ReVanced Development](./docs/revanced-development) +- [🛠️ ReVanced Development](./docs/revanced-development) diff --git a/docs/revanced-cli b/docs/revanced-cli new file mode 120000 index 0000000..9112dc9 --- /dev/null +++ b/docs/revanced-cli @@ -0,0 +1 @@ +repositories/revanced-cli diff --git a/docs/revanced-development/0_prerequisites.md b/docs/revanced-development/0_prerequisites.md index 8732209..85c4bb0 100644 --- a/docs/revanced-development/0_prerequisites.md +++ b/docs/revanced-development/0_prerequisites.md @@ -1,20 +1,15 @@ -# Requirements +# 💼 Prerequisites -- ADB -- x86/x86_64 host architecture -- Zulu JDK 17 -- Latest Android SDK if you plan to build the integrations from the source -- The APK file you want to patch (e.g. YouTube v17.49.37 or YouTube Music v5.36.51). If you want to mount patched applications as root, make sure the same version is installed on your device. +To develop with ReVanced, you will need to fulfill certain requirements. -You can continue by either [building everything from source](2_building_from_source.md) or [downloading the prebuilt packages](1_downloading.md). +## 🤝 Requirements -## Overview +- A Java IDE such as [IntelliJ IDEA](https://www.jetbrains.com/idea/) +- An Android IDE such as [Android Studio](https://developer.android.com/studio) +- Understanding on how to use the ReVanced CLI -- [Prerequisites](0_prerequisites.md) - - [Downloading prebuilt Packages](1_downloading.md) - - [Building from source](2_building_from_source.md) - - [1. Building the ReVanced Patcher](3_building_revanced_patcher.md) - - [2. Building the ReVanced Patches](4_building_revanced_patches.md) - - [3. Building the ReVanced Integrations](5_building_revanced_integrations.md) - - [4. Building the ReVanced CLI](6_building_revanced_cli.md) -- [Using the ReVanced CLI](7_usage.md) +## ⏭️ Whats next + +The next section will explain, how to setup a convenient development environment for ReVanced with [IntelliJ IDEA](https://www.jetbrains.com/idea/) and [Android Studio](https://developer.android.com/studio) + +Continue: [👨‍💻 Setup a development environment for ReVanced](1_setup_development_environment.md) diff --git a/docs/revanced-development/1_downloading.md b/docs/revanced-development/1_downloading.md deleted file mode 100644 index 8c3ea2f..0000000 --- a/docs/revanced-development/1_downloading.md +++ /dev/null @@ -1,9 +0,0 @@ -# Downloading the packages - -- [ReVanced CLI](https://github.com/revanced/revanced-cli/releases/latest) -- [ReVanced Patches](https://github.com/revanced/revanced-patches/releases/latest) -- [ReVanced Integrations](https://github.com/revanced/revanced-integrations/releases/latest) - -## Next step - -[Using the ReVanced CLI](7_usage.md) diff --git a/docs/revanced-development/1_setup_development_environment.md b/docs/revanced-development/1_setup_development_environment.md new file mode 100644 index 0000000..4ea92f9 --- /dev/null +++ b/docs/revanced-development/1_setup_development_environment.md @@ -0,0 +1,109 @@ +# 👨‍💻 Setup a development environment for ReVanced + +A certain development environment is suggested to allow for streamlined development on ReVanced. + +## 1. ⬇️ Clone necessary repositories + +```bash +repositories=( + "revanced-cli" + "revanced-patches" + "revanced-patcher" # optional + "revanced-integrations" +) + +for repository in "${repositories[@]}" ; do + git clone -b dev --single-branch --depth 1 https://github.com/revanced/$repository +done +``` + +## 2. 🛠️ Build from source + +### Before building you need to be authenticated to GitHub Packages. This will assume you have a GitHub account + +Create a PAT with the scope `read:packages` [here](https://github.com/settings/tokens/new?scopes=read:packages&description=Revanced) and add your token to `~/.gradle/gradle.properties`. + +Example `gradle.properties` file: + +```properties +gpr.user = ReVanced +gpr.key = ghp_key +``` + +### To build all projects, run the following command from the directory which contains the repositories + +```bash +repositories=( + "revanced-cli" + "revanced-patches" + "revanced-patcher" # optional + "revanced-integrations" +) + +for repository in "${repositories[@]}" ; do + cd $repository + ./gradlew build + cd .. +done +``` + +## 3. ⚙️ Setup IntelliJ IDEA + +1. Open the `revanced-cli` project in IntelliJ IDEA and ensure you are using the right JDK from [💼 Prerequisites](0_prerequisites.md) +2. Import the `revanced-patches` and optionally the `revanced-patcher` project as modules into the `revanced-cli` project +3. Add a new Run/Debug configuration for the `revanced-cli` project + + Example configuration: + + ```xml + + + + + ``` + + > **Note**: The builds of the `revanced-patches` and `revanced-integrations` change. **Do not forget to update them as well in the run configuration program arguments.** + +## 5. ⚙️ Setup Android Studio + +1. Open the `revanced-integrations` project in Android Studio and ensure you are using the latest Android SDK. +2. Add a new default build configuration and confirm if it succeeds. + +## 6. ⚠️ Troubleshoot your development environment + +To confirm your development environment works as intended, set a breakpoint in any patch in IntelliJ IDEA. Run the configuration and confirm, that your IDE reaches and breaks at the breakpoint. Continue and let the ReVanced CLI exit. + +- If the ReVanced CLI output is unexpected, confirm if you supplied the correct program arguments by following [💻 ReVanced CLI](./docs/revanced-development). + +- If the breakpoint was not hit, confirm, that you correctly added the necessary projects as modules to the `revanced-cli` project + +## ❗ Afterword + +Couple things should be considered with the development environment for ReVanced: + +- Follow [conventional commits](https://www.conventionalcommits.org/en/v1.0.0/) + +- Pull new commits from remote to keep your branch up to date + +- Keep your Run/Debug configuration up to date. Make sure, you use the correct paths in your program argument after you pull new commits. If you forget to do this, you might end up debugging for hours until realizing, you supply the wrong paths to the ReVanced CLI + +- Use development branches and always branch off and PR to the `dev` branch + +- To use the local `revanced-patches` project in the `revanced-cli` and `revanced-patches` projects, make sure you publish it to the local Maven repository with `./gradlew publish` and use the correct version in the `build.gradle.kts` file in the `revanced-cli` and `revanced-patches` projects, otherwise, it will use the package from GitHub Packages diff --git a/docs/revanced-development/2_building_from_source.md b/docs/revanced-development/2_building_from_source.md deleted file mode 100644 index 8a5c02f..0000000 --- a/docs/revanced-development/2_building_from_source.md +++ /dev/null @@ -1,21 +0,0 @@ -# Building from source - -If you have already downloaded the prebuilt packages you can skip to [Using the ReVanced CLI](7_usage.md). - -Before continuing you need to be authenticated to GitHub Packages. -\ -This will assume you have a GitHub account. Create a PAT with the scope `read:packages` [here](https://github.com/settings/tokens/new?scopes=read:packages&description=Revanced) and add your token to ~/.gradle/gradle.properties. -\ -Example `gradle.properties` file: - -```properties -gpr.user = YourUsername -gpr.key = ghp_longrandomkey -``` - -## Overview - -1. [Building the ReVanced Patcher](3_building_revanced_patcher.md) -2. [Building the ReVanced Patches](4_building_revanced_patches.md) -3. [Building the ReVanced Integrations](5_building_revanced_integrations.md) -4. [Building the ReVanced CLI](6_building_revanced_cli.md) diff --git a/docs/revanced-development/3_building_revanced_patcher.md b/docs/revanced-development/3_building_revanced_patcher.md deleted file mode 100644 index dccfb44..0000000 --- a/docs/revanced-development/3_building_revanced_patcher.md +++ /dev/null @@ -1,17 +0,0 @@ -# Building the ReVanced Patcher - -1. Clone the repository - - ```bash - git clone https://github.com/revanced/revanced-patcher && cd revanced-patcher - ``` - -2. Publish the patcher to your local maven repository - - ```bash - ./gradlew publish - ``` - -## Next step - -[Building the ReVanced Patches](4_building_revanced_patches.md) diff --git a/docs/revanced-development/4_building_revanced_patches.md b/docs/revanced-development/4_building_revanced_patches.md deleted file mode 100644 index cca833f..0000000 --- a/docs/revanced-development/4_building_revanced_patches.md +++ /dev/null @@ -1,19 +0,0 @@ -# Building the ReVanced Patches - -1. Clone the repository - - ```bash - git clone https://github.com/revanced/revanced-patches && cd revanced-patches - ``` - -2. Build the patches - - ```bash - ./gradlew build - ``` - -The file will be located in `build/libs/revanced-patches-VERSION.jar` - -## Next step - -[Building the ReVanced integrations](5_building_revanced_integrations.md) diff --git a/docs/revanced-development/5_building_revanced_integrations.md b/docs/revanced-development/5_building_revanced_integrations.md deleted file mode 100644 index ea967f6..0000000 --- a/docs/revanced-development/5_building_revanced_integrations.md +++ /dev/null @@ -1,21 +0,0 @@ -# Building the ReVanced Integrations - -1. Make sure `$ANDROID_SDK_ROOT` or `$ANDROID_HOME` is set correctly - -2. Clone the repository - - ```bash - git clone https://github.com/revanced/revanced-integrations && cd revanced-integrations - ``` - -3. Build the integrations - - ```bash - ./gradlew build - ``` - -The file will be located in `app/build/outputs/apk/release/app-release-unsigned.apk` - -## Next step - -[Building the ReVanced CLI](6_building_revanced_cli.md) diff --git a/docs/revanced-development/6_building_revanced_cli.md b/docs/revanced-development/6_building_revanced_cli.md deleted file mode 100644 index 22af854..0000000 --- a/docs/revanced-development/6_building_revanced_cli.md +++ /dev/null @@ -1,19 +0,0 @@ -# Building the ReVanced CLI - -1. Clone the repository - -```bash -git clone https://github.com/revanced/revanced-cli && cd revanced-cli -``` - -Build the CLI - -```bash -./gradlew build -``` - -The file will be located in `build/libs/revanced-cli-VERSION-all.jar` - -## Next step - -[Using the ReVanced CLI](7_usage.md) diff --git a/docs/revanced-development/7_usage.md b/docs/revanced-development/7_usage.md deleted file mode 100644 index 599d732..0000000 --- a/docs/revanced-development/7_usage.md +++ /dev/null @@ -1,47 +0,0 @@ -# Using the ReVanced CLI - -1. Make sure your device is connected - - ```bash - adb shell exit - ``` - - If you plan to use the root variant, check if you have root access - - ```bash - adb shell su -c exit - ``` - -2. Copy the ADB device name - - ```bash - adb devices - ``` - -3. Run the CLI - - ```bash - # Non-Root - java -jar revanced-cli-all.jar \ - -a input.apk \ - -c \ - -d device-name \ - -o output.apk \ - -b revanced-patches.jar - - # Root - # In the case of YouTube you want to exlude the patch 'microg-support' with the option '-e'. The option '-e' allows you to exclude patches (e.g. -e microg-support -e amoled ...) - java -jar revanced-cli-all.jar \ - -a input.apk \ - -c \ - -d device-name \ - -o output.apk \ - -b revanced-patches.jar \ - -e microg-support \ - --mount - ``` - -> **Note**: Patches might require additional integrations to be merged. Merge integrations with the option `-m`. -> **Note**: You can list all patches available by using the option `-l`. - -If you specified an ADB device the patched application will be automatically installed. diff --git a/docs/revanced-development/README.md b/docs/revanced-development/README.md index d9acb06..19a9136 100644 --- a/docs/revanced-development/README.md +++ b/docs/revanced-development/README.md @@ -1,14 +1,8 @@ -# 💻 ReVanced Development +# 🛠️ ReVanced Development -Instructions to build and install ReVanced. +Documentation to develop with ReVanced. ## 📖 Table of contents -- [Prerequisites](0_prerequisites.md) - - [Downloading prebuilt Packages](1_downloading.md) - - [Building from source](2_building_from_source.md) - - [1. Building the ReVanced Patcher](3_building_revanced_patcher.md) - - [2. Building the ReVanced Patches](4_building_revanced_patches.md) - - [3. Building the ReVanced Integrations](5_building_revanced_integrations.md) - - [4. Building the ReVanced CLI](6_building_revanced_cli.md) -- [Using the ReVanced CLI](7_usage.md) +- [💼 Prerequisites](0_prerequisites.md) +- [👨‍💻 Setup a development environment for ReVanced](1_setup_development_environment.md) diff --git a/repositories/revanced-cli b/repositories/revanced-cli new file mode 160000 index 0000000..6bd7d42 --- /dev/null +++ b/repositories/revanced-cli @@ -0,0 +1 @@ +Subproject commit 6bd7d42e32450974a52e1bb9df4a31512d399842