Relevant source files

The following files were used as context for generating this wiki page: - [README.md](https://github.com/matsuridayo/nekoboxforandroid/blob/main/README.md) - [app/build.gradle.kts](https://github.com/matsuridayo/nekoboxforandroid/blob/main/app/build.gradle.kts) - [build.gradle.kts](https://github.com/matsuridayo/nekoboxforandroid/blob/main/build.gradle.kts) - [settings.gradle.kts](https://github.com/matsuridayo/nekoboxforandroid/blob/main/settings.gradle.kts) - [LICENSE](https://github.com/matsuridayo/nekoboxforandroid/blob/main/LICENSE)

# Getting Started ## Introduction **NekoBox for Android** is an open‑source Android application that provides a universal proxy client built on top of **sing‑box**. It supports a wide range of proxy protocols (SOCKS, HTTP(S), Shadowsocks, V2Ray families, WireGuard, etc.) and can import nodes from popular subscription formats. The project is organized as a standard Gradle Android application with a single `:app` module and follows modern Kotlin‑based Android development practices. This guide walks you through the repository layout, build configuration, key dependencies, and licensing information required to set up a development environment and compile the app from source. For deeper architectural details, see the [Architecture](#architecture) section below. --- ## Repository Layout ### Project Structure ```mermaid graph TB rootNode[Root Project] --> appNode[App Module] rootNode --> buildFileNode[Top‑level build.gradle.kts] rootNode --> settingsNode[settings.gradle.kts] appNode --> appBuildNode[app#47;build.gradle.kts] appNode --> srcNode[src#47; #40;Kotlin & resources#41;] ``` *The diagram shows the top‑level Gradle files and the single Android module (`:app`).* Sources: [settings.gradle.kts](https://github.com/matsuridayo/nekoboxforandroid/blob/main/settings.gradle.kts), [build.gradle.kts](https://github.com/matsuridayo/nekoboxforandroid/blob/main/build.gradle.kts), [app/build.gradle.kts](https://github.com/matsuridayo/nekoboxforandroid/blob/main/app/build.gradle.kts) ### Key Gradle Files | File | Purpose | Important Snippets | |------|---------|--------------------| | `settings.gradle.kts` | Declares the `:app` module and sets the root project name. | `include(":app")`
`rootProject.name = "NB4A"` | | `build.gradle.kts` (root) | Applies common repositories to all sub‑projects and defines a `clean` task. | `apply(from = "${rootProject.projectDir}/repositories.gradle.kts")`
`tasks.register("clean") { delete(rootProject.buildDir) }` | | `app/build.gradle.kts` | Configures the Android application, Kotlin plugins, KSP, and declares all runtime dependencies. | `plugins { id("com.android.application") … }`
`android { compileOptions { isCoreLibraryDesugaringEnabled = true } … }`
`dependencies { implementation("androidx.core:core-ktx:1.9.0") … }` | Sources: [settings.gradle.kts](https://github.com/matsuridayo/nekoboxforandroid/blob/main/settings.gradle.kts), [build.gradle.kts](https://github.com/matsuridayo/nekoboxforandroid/blob/main/build.gradle.kts), [app/build.gradle.kts](https://github.com/matsuridayo/nekoboxforandroid/blob/main/app/build.gradle.kts) --- ## Architecture ### High‑Level Components ```mermaid graph TB subgraph UIGroup direction TB uiMain[MainActivity] --> uiSettings[SettingsFragment] uiMain --> uiProfile[ProfileFragment] end subgraph CoreGroup direction TB coreService[SingBoxService] --> coreRepo[Repository] coreRepo --> coreDb[Room Database] end uiMain --> coreService ``` *The UI layer (activities/fragments) interacts with the `SingBoxService`, which in turn accesses the repository and Room database.* The diagram reflects the `namespace = "io.nekohasekai.sagernet"` declared in `app/build.gradle.kts` and the inclusion of Room libraries (`androidx.room:room-runtime`, `room-ktx`). Sources: [app/build.gradle.kts](https://github.com/matsuridayo/nekoboxforandroid/blob/main/app/build.gradle.kts) ### Build Flow ```mermaid graph TB cleanTask[Clean Task] --> assembleTask[Assemble Debug#47;Release] assembleTask --> apkOutput[Generated APK] apkOutput --> installStep[Install on Device] ``` *Running `./gradlew clean assembleDebug` follows this flow.* Sources: [build.gradle.kts](https://github.com/matsuridayo/nekoboxforandroid/blob/main/build.gradle.kts) --- ## Dependency Overview ### Core AndroidX & Material ```mermaid graph TB subgraph AndroidX direction TB coreKtx[core-ktx#40;1.9.0#41;] --> appCompat[appcompat#40;1.6.1#41;] coreKtx --> recyclerView[recyclerview#40;1.3.0#41;] coreKtx --> constraint[constraintlayout#40;2.1.4#41;] coreKtx --> navigationNav[nav‑fragment‑ktx#40;2.5.3#41;] coreKtx --> navigationUI[nav‑ui‑ktx#40;2.5.3#41;] coreKtx --> workRuntime[work‑runtime‑ktx#40;2.8.1#41;] end subgraph ThirdParty direction TB material[material#40;1.8.0#41;] --> gson[gson#40;2.9.0#41;] material --> okHttp[okhttp#40;5.0.0‑alpha.3#41;] material --> yaml[snakeyaml#40;1.30#41;] material --> room[room‑runtime#40;2.6.1#41;] material --> guava[guava#40;31.0.1‑android#41;] end coreKtx --> material ``` *All versions are taken directly from the `implementation` statements in `app/build.gradle.kts`.* Sources: [app/build.gradle.kts](https://github.com/matsuridayo/nekoboxforandroid/blob/main/app/build.gradle.kts) ### Optional Plugins & Features | Feature | Library | Version | |---------|---------|---------| | QR code scanning | `com.github.jenly1314:zxing-lite` | 2.1.1 | | Code editor UI | `com.blacksquircle.ui:editorkit` | 2.6.0 | | YAML parsing | `org.yaml:snakeyaml` | 1.30 | | Fast scroll for RecyclerView | `com.simplecityapps:recyclerview-fastscroll` | 2.0.1 (excludes AndroidX RecyclerView & AppCompat) | | Room migration helper | `com.github.MatrixDev.Roomigrant:RoomigrantLib` | 0.3.4 | Sources: [app/build.gradle.kts](https://github.com/matsuridayo/nekoboxforandroid/blob/main/app/build.gradle.kts) --- ## Getting the Source & Building ### Prerequisites | Requirement | Recommended Version | |-------------|----------------------| | JDK | 11 or newer | | Android SDK | API 21+ (minimum) | | Gradle | Wrapper (included) | | Kotlin | 1.8.x (via plugin) | ### Steps 1. **Clone the repository** ```bash git clone https://github.com/matsuridayo/NekoBoxForAndroid.git cd NekoBoxForAndroid ``` 2. **Open in Android Studio** (Arctic Fox or newer) – the project uses the Gradle Kotlin DSL, so the IDE will automatically sync. 3. **Build the app** ```bash ./gradlew clean assembleDebug ``` The generated APK will be located at `app/build/outputs/apk/debug/app-debug.apk`. 4. **Run on a device or emulator** – ensure the device API level is 21 or higher. Sources: [README.md](https://github.com/matsuridayo/nekoboxforandroid/blob/main/README.md) (download badges indicate API 21+), [build.gradle.kts](https://github.com/matsuridayo/nekoboxforandroid/blob/main/build.gradle.kts) ### Common Issues | Symptom | Likely Cause | Fix | |---------|--------------|-----| | `Desugar` errors | Missing core library desugaring | Ensure `coreLibraryDesugaring("com.android.tools:desugar_jdk_libs:2.0.3")` is present (it is in `app/build.gradle.kts`). | | Dependency conflicts with RecyclerView | `recyclerview-fastscroll` excludes RecyclerView | No action needed; the exclusion is intentional. | | KSP compilation failures | Incorrect KSP arguments | Verify `ksp { arg("room.incremental", "true") … }` block is unchanged. | Sources: [app/build.gradle.kts](https://github.com/matsuridayo/nekoboxforandroid/blob/main/app/build.gradle.kts) --- ## Licensing The entire project is released under the **GNU General Public License v3.0 (GPL‑3.0)**. The license file is included in the repository and grants users the freedom to run, study, share, and modify the software, provided that derived works also carry the same license. ```text Copyright (C) 2021 by nekohasekai ... You should have received a copy of the GNU General Public License along with this program. If not, see . ``` For any redistribution, you must retain the license notice and make the source code available. Sources: [LICENSE](https://github.com/matsuridayo/nekoboxforandroid/blob/main/LICENSE) --- ## Summary Getting started with **NekoBox for Android** involves cloning the repository, understanding its single‑module Gradle layout, and building the app with the provided Gradle wrapper. The project leverages a modern Android stack (AndroidX, Kotlin, KSP, Room) and integrates a rich set of third‑party libraries to support many proxy protocols. All code is GPL‑3.0 licensed, encouraging community contributions while protecting user freedoms. ---