4fab442939
- Remove the app fallback path when native Git is unavailable and show a startup blocker instead - Fix native level setup for staged file counting and cherry-pick parity - Improve manpage loading/search and bundle full Git documentation assets - Integrate Git cross-compilation into AndroidProjectTooling.sh and remove debug AAB support
145 lines
6.9 KiB
Markdown
145 lines
6.9 KiB
Markdown
# GitHug Android
|
|
|
|
Native Android adaptation of the Ruby [Githug](https://github.com/Gazler/githug) learning game, built with **Kotlin + Jetpack Compose**. The product goal is a shippable mobile implementation that preserves GitHug's CLI-first learning style while making repository state easier to inspect on a phone.
|
|
|
|
## Implementation Strategy
|
|
|
|
The app is organized around GitHug parity rather than simplified command quizzes:
|
|
|
|
- The level catalog follows the upstream Ruby Githug order from `Githug::Level::LEVELS`.
|
|
- Each exercise lives in its own Kotlin source file under `app/src/main/java/solutions/tretter/githugandroid/levels/`.
|
|
- Each level file documents the intended repository setup, evaluation strategy, hints, command suggestions, and embedded solution scenarios.
|
|
- Validators prefer repository state and Git objects over raw command text. Direct command-answer validation is reserved for upstream answer-style levels such as identifying a hash, filename, remote URL, author, or count.
|
|
- Shared tests execute the embedded solution scenarios for every level and assert that the Android catalog still matches the upstream level order.
|
|
- The runtime prepares an isolated sandbox per level and requires a bundled native Git binary for the device ABI. If no native Git binary is available, the app shows an unavailable-build message instead of starting a playable session.
|
|
|
|
The UI supports a terminal-centered workflow with optional inspection panes:
|
|
|
|
- **CLI ONLY**: hide visualization and play with terminal-style input.
|
|
- **HYBRID**: command line with optional repository panels.
|
|
- **VISUAL**: repository panels visible by default, still backed by the same command engine.
|
|
|
|
## Development Workflow
|
|
|
|
Development tasks should be run through the project tooling script. It provisions the local toolchain, keeps paths project-relative, and runs Gradle with the project configuration expected by this repository.
|
|
|
|
## Android project tooling
|
|
|
|
This repo includes a root-level tooling script:
|
|
|
|
```bash
|
|
bash ./AndroidProjectTooling.sh
|
|
```
|
|
|
|
It is designed to be idempotent and uses project-relative paths to:
|
|
|
|
- install a project-local JDK into `./jdk`
|
|
- install Android command-line tools into `./android-sdk`
|
|
- restore `gradle/wrapper/gradle-wrapper.jar` if missing
|
|
- install required Android SDK packages
|
|
- write `local.properties`
|
|
|
|
Available commands:
|
|
|
|
| Command | Purpose | Output |
|
|
| --- | --- | --- |
|
|
| `bash ./AndroidProjectTooling.sh` | Provision or refresh the local Android/JDK toolchain only. | Toolchain under `./jdk` and `./android-sdk` |
|
|
| `bash ./AndroidProjectTooling.sh --test` | Compile host Git, set `GITHUG_TEST_GIT_BINARY`, and run JVM unit tests. | Test reports under `app/build/reports/` |
|
|
| `bash ./AndroidProjectTooling.sh --build` | Build the debug APK. | `app/build/outputs/apk/debug/githug-android-debug.apk` |
|
|
| `bash ./AndroidProjectTooling.sh --build-release-aab` | Build the release Android App Bundle. | `app/build/outputs/bundle/release/githug-android-release.aab` |
|
|
| `bash ./AndroidProjectTooling.sh --compile-git` | Compile Git for the development host and all Android target ABIs. | Host and Android `libgit.so` binaries |
|
|
|
|
To run the JVM unit test suite after ensuring the local toolchain is ready:
|
|
|
|
```bash
|
|
bash ./AndroidProjectTooling.sh --test
|
|
```
|
|
|
|
To build installable/debuggable artifacts:
|
|
|
|
```bash
|
|
bash ./AndroidProjectTooling.sh --build
|
|
```
|
|
|
|
To build the release AAB intended for Play Store style distribution work:
|
|
|
|
```bash
|
|
bash ./AndroidProjectTooling.sh --build-release-aab
|
|
```
|
|
|
|
The script avoids depending on the system Java version by provisioning a project-local **JDK 17**, which is required by current Android SDK command-line tools.
|
|
|
|
To avoid repeated expensive SDK verification, the script writes a small state file named:
|
|
|
|
`./.android-project-tooling.state`
|
|
|
|
If all required components were verified successfully, the script will skip SDK verification/reinstallation for the next **24 hours** unless required directories are missing.
|
|
|
|
When `--build` or `--build-release-aab` is used, the script also:
|
|
|
|
- increments `versionCode` by 1
|
|
- increments the patch component of `versionName`, for example `0.1.0` to `0.1.1`
|
|
- bundles full Git manpage source files from Git's `Documentation/` directory into app assets
|
|
- renames the generated artifact to a stable `githug-android-*` filename
|
|
- attempts to create a git commit after a successful build if there are source changes
|
|
|
|
The build commands currently run these Gradle tasks:
|
|
|
|
- `--build`: `assembleDebug`
|
|
- `--build-release-aab`: `bundleRelease`
|
|
|
|
## Git Binary Compilation
|
|
|
|
Native Git compilation is integrated into the root tooling script:
|
|
|
|
```bash
|
|
bash ./AndroidProjectTooling.sh --compile-git
|
|
```
|
|
|
|
Options:
|
|
|
|
| Command | Purpose | Output |
|
|
| --- | --- | --- |
|
|
| `bash ./AndroidProjectTooling.sh --test` | Compile Git for the development machine, then run tests with it. | `build/host-git/libgit.so` and test reports |
|
|
| `bash ./AndroidProjectTooling.sh --compile-git` | Compile host Git and cross-compile Android ABIs served by Google Play. | Host and Android outputs |
|
|
|
|
Android ABI outputs:
|
|
|
|
- `app/src/main/jniLibs/arm64-v8a/libgit.so`
|
|
- `app/src/main/jniLibs/armeabi-v7a/libgit.so`
|
|
- `app/src/main/jniLibs/x86/libgit.so`
|
|
- `app/src/main/jniLibs/x86_64/libgit.so`
|
|
|
|
The `--test` tooling command automatically builds host Git first and exports `GITHUG_TEST_GIT_BINARY=build/host-git/libgit.so`. This keeps JVM tests on the same `GitRepositoryRuntime` path as the app, including the packaged-runtime helper resolution behavior.
|
|
|
|
Git manpage assets are also refreshed from the checked-out Git source whenever Git is compiled or an app artifact is built.
|
|
|
|
## Runtime Architecture
|
|
|
|
The command engine has one app-facing runtime:
|
|
|
|
- **Native Git path**: the packaged executable for the device ABI runs Git commands in a real per-level repository sandbox in app-private storage.
|
|
|
|
The runtime exposes a `RepoState` surface to validators. In addition to files, commits, branches, tags, remotes, and config, the model tracks learning-relevant effects such as stashes, fetched remote refs, pushed branches/tags, submodules, and repository maintenance actions.
|
|
|
|
Helper shell-like commands (`ls`, `pwd`, `cat`, `touch`, `mkdir`, `rm`, `echo`, `cd`) remain implemented in Kotlin so the mobile terminal behaves consistently across devices.
|
|
|
|
## Level Authoring
|
|
|
|
When adding or changing a level:
|
|
|
|
- Keep one source file per exercise.
|
|
- Keep `allGithugLevels()` in upstream Ruby Githug order.
|
|
- Document the setup and validation intent in the level file.
|
|
- Prefer validators that inspect `RepoState` over validators that match command strings.
|
|
- Add multiple `LevelTestCase` scenarios when more than one solution path should be accepted.
|
|
- Run `bash ./AndroidProjectTooling.sh --test` before building.
|
|
|
|
## Production Focus
|
|
|
|
Current work is focused on:
|
|
|
|
- improving parity with upstream Ruby Githug setup and validation semantics
|
|
- expanding native-Git-backed behavior across complex repository workflows
|
|
- improving onboarding, accessibility, UI polish, icons, and Play Store readiness
|