205 lines
9.1 KiB
Markdown
205 lines
9.1 KiB
Markdown
# Building and running — Fileworkbench 0.2.3
|
|
|
|
## Pinned baseline
|
|
|
|
| Component | Selected version |
|
|
|---|---|
|
|
| Gradle build JVM / daemon | Installed JDK **17**, any vendor |
|
|
| Java/Kotlin compilation toolchains and JVM bytecode target | **17** |
|
|
| Gradle wrapper distribution | **8.14.5** |
|
|
| Android Gradle Plugin | 8.11.1 (unchanged) |
|
|
| Kotlin / Compose compiler plugin | 2.2.21 (unchanged) |
|
|
| Compose BOM | 2025.08.00 (unchanged) |
|
|
| Android compile / target SDK | 36 / 36 |
|
|
| Android minimum SDK | 26 |
|
|
| Android Build Tools | 35.0.0 (AGP default) |
|
|
|
|
These are deliberate project pins, not a recommendation to use the newest releases.
|
|
This source package is **not a verified Android APK**. The current execution results
|
|
and limitations are recorded in `VALIDATION.md`.
|
|
|
|
## Start with a fresh extraction
|
|
|
|
This is the whole project, not a patch. Extract it to a new directory and open the
|
|
contained `fileworkbench` directory (the one containing `settings.gradle.kts`).
|
|
Keep your existing checkout and any local changes separately. Do not copy the old
|
|
`build.gradle.kts`, `settings.gradle.kts`, version catalog, wrapper files,
|
|
`gradle/gradle-daemon-jvm.properties`, `.idea`, `.gradle` or `.kotlin` over this release.
|
|
Otherwise old Gradle 9.x / Java 25 / duplicate-plugin settings can be reintroduced.
|
|
|
|
There are no machine-specific IDE files or absolute SDK/JDK paths in this archive.
|
|
For your Gitea repository, review the new files against your checkout after the
|
|
fresh project imports successfully; do not overwrite uncommitted work blindly.
|
|
|
|
## Install/select JDK 17 and the SDK
|
|
|
|
Install a **JDK 17**, not only a JRE. In Android Studio/IntelliJ, open
|
|
**Settings → Build, Execution, Deployment → Build Tools → Gradle**, use the wrapper
|
|
from this project, and select that JDK 17 as the **Gradle JDK/JVM**. On IDE versions
|
|
that expose daemon JVM criteria, leave this project's version-17 criteria intact.
|
|
You do not need to change the IDE's own boot runtime or uninstall other JDKs.
|
|
|
|
In SDK Manager install Android SDK Platform 36, Build Tools 35.0.0 and Platform
|
|
Tools. Accept any SDK licences yourself. Let the IDE generate a new
|
|
`local.properties` with `sdk.dir`, or use your existing `ANDROID_HOME` environment
|
|
setting. Do not commit local.properties, signing keys or private documents.
|
|
|
|
Set terminal `JAVA_HOME` to your installed JDK 17 directory (not its `bin` folder).
|
|
The project also recognises an optional `JDK17_HOME` for toolchain discovery.
|
|
The checked-in `gradle/gradle-daemon-jvm.properties` contains `toolchainVersion=17`;
|
|
module toolchains also select 17. No vendor or absolute installation path is pinned.
|
|
Automatic JDK downloads are disabled: install a JDK 17 before building.
|
|
|
|
### Linux/macOS terminal
|
|
|
|
```bash
|
|
cd /path/to/new/fileworkbench
|
|
# Replace this example with the path of your actual JDK 17 installation.
|
|
export JAVA_HOME="/path/to/jdk-17"
|
|
export PATH="$JAVA_HOME/bin:$PATH"
|
|
chmod +x gradlew scripts/*.sh
|
|
java -version
|
|
./gradlew --version
|
|
./gradlew help
|
|
./gradlew :core:jvmTest :platform-jvm:test \
|
|
:androidApp:assembleDebug :androidApp:assembleDebugAndroidTest :androidApp:lintDebug
|
|
```
|
|
|
|
### Windows PowerShell
|
|
|
|
```powershell
|
|
cd C:\path\to\new\fileworkbench
|
|
# Replace this example with the path of your actual JDK 17 installation.
|
|
$env:JAVA_HOME = "C:\path\to\jdk-17"
|
|
$env:Path = "$env:JAVA_HOME\bin;$env:Path"
|
|
java -version
|
|
.\gradlew.bat --version
|
|
.\gradlew.bat help
|
|
.\gradlew.bat :core:jvmTest :platform-jvm:test :androidApp:assembleDebug :androidApp:assembleDebugAndroidTest :androidApp:lintDebug
|
|
```
|
|
|
|
The environment changes above apply only to the current terminal. Verify that
|
|
`--version` reports **Gradle 8.14.5**, with the intended Java 17 launcher and daemon
|
|
criteria. A version command alone does not prove that the application compiles.
|
|
|
|
## First-run wrapper bootstrap
|
|
|
|
The external `gradle-wrapper.jar` could not be downloaded in the authoring runtime,
|
|
so it is **not bundled**. All project source, Gradle configuration, launchers and
|
|
bootstrap scripts are present. The first `./gradlew --version` invocation (Windows:
|
|
`.\gradlew.bat --version`) downloads the wrapper binary and verifies its SHA-256.
|
|
Do this once **before importing into the IDE**, so its Gradle integration can see
|
|
the wrapper JAR. An internet connection is required for this and dependency setup.
|
|
|
|
Both shell and PowerShell bootstrap scripts now request the 8.14.5 source tag and
|
|
release distribution. A downloaded JAR with the wrong checksum is not executed;
|
|
the script falls back to the separately verified distribution and checks its
|
|
embedded wrapper. The fallback needs `unzip` on Unix-like systems or .NET ZIP
|
|
support in PowerShell. A failed initial network request still aborts; resolve that
|
|
network problem or bootstrap from an official local Gradle installation.
|
|
|
|
Official **8.14.5 wrapper JAR SHA-256**:
|
|
|
|
```text
|
|
7d3a4ac4de1c32b59bc6a4eb8ecb8e612ccd0cf1ae1e99f66902da64df296172
|
|
```
|
|
|
|
Official **8.14.5 binary distribution SHA-256**:
|
|
|
|
```text
|
|
6f74b601422d6d6fc4e1f9a1ab6522f642c2fdcbc15ae33ebd30ba3d7198e854
|
|
```
|
|
|
|
Hashes were verified against Gradle's release-checksum reference on 2026-09-24;
|
|
this is not a claim that the binary downloads succeeded here.
|
|
|
|
Once the official wrapper runs, the standard upstream launchers can be generated:
|
|
|
|
```sh
|
|
./gradlew wrapper --gradle-version 8.14.5 --distribution-type bin \
|
|
--gradle-distribution-sha256-sum 6f74b601422d6d6fc4e1f9a1ab6522f642c2fdcbc15ae33ebd30ba3d7198e854
|
|
./gradlew wrapper
|
|
```
|
|
|
|
Commit the verified wrapper JAR and generated scripts in your own repository.
|
|
A network-free build is possible only after the required tooling and dependencies
|
|
are locally available. The installed application's main manifest has no network
|
|
permission; an external storage provider may use its own network connection.
|
|
|
|
## Install and identify this diagnostic build
|
|
|
|
After successful APK assembly, with a connected and authorised device:
|
|
|
|
```sh
|
|
adb install -r androidApp/build/outputs/apk/debug/androidApp-debug.apk
|
|
```
|
|
|
|
Use your existing debug signing identity when installing over the current app.
|
|
Changing source directories on the same machine normally keeps the same user
|
|
keystore; this archive does not contain a signing key. Do not uninstall or clear
|
|
app data just to test the folder issue. A signing mismatch needs to be resolved
|
|
with the existing signing key rather than silently discarding application data.
|
|
|
|
The package remains `dev.fileworkbench.android`, version **0.2.3**, code **5**.
|
|
In **Browse → Locations**, verify the footer:
|
|
|
|
```text
|
|
Fileworkbench 0.2.3 · Browser diagnostics SAF-D1 · read-only
|
|
```
|
|
|
|
Then open the previously failing folder. A genuinely null cursor now produces
|
|
`[SAF-D1/NULL_CURSOR]`, the storage-provider authority, Android API level, and
|
|
retained-grant status. Send the full new message for diagnosis. A false retained
|
|
grant does not establish a permission failure: temporary access may still exist.
|
|
The query, successful listing behaviour and storage permissions are unchanged.
|
|
|
|
## Verification and troubleshooting
|
|
|
|
With a device/emulator, execute the Android instrumentation sources:
|
|
|
|
```sh
|
|
./gradlew :androidApp:connectedDebugAndroidTest
|
|
```
|
|
|
|
`./scripts/verify-android.sh` runs source checks plus Gradle tests, APK assembly and
|
|
lint. The existing optional GitHub workflow uses Java 17 and these same commands;
|
|
it has not been run here. These commands can also run on your local machine or a
|
|
suitably configured Gitea runner; no Gitea workflow is introduced in this release.
|
|
|
|
For offline **host-only** checks with Python 3, Kotlin compiler and an installed JVM:
|
|
|
|
```sh
|
|
python3 scripts/check-project.py
|
|
python3 scripts/test-build-config.py
|
|
bash scripts/test-core.sh
|
|
python3 scripts/test-folder-listing.py
|
|
bash scripts/check-kotlin-syntax.sh
|
|
```
|
|
|
|
Host test bytecode targets 17, but the scripts run on the local JVM; see the
|
|
validation report for the actual host version. They do not compile Android APIs.
|
|
|
|
**A duplicate `org.jetbrains.kotlin.jvm` plugin request:** this archive's root
|
|
script contains five distinct plugin aliases, with no extra `id("...")` or
|
|
`kotlin("jvm")` declarations. Do not append a second request for the JVM plugin.
|
|
Its use in `platform-jvm/build.gradle.kts` is intentional. The offline
|
|
`scripts/check-build-config.py` verifies the root aliases and catalog IDs.
|
|
|
|
**Gradle still selects 9.x or Java 25:** confirm that you opened this new directory,
|
|
are using its wrapper and selected JDK 17 in the IDE. Inspect user-level Gradle
|
|
properties/init scripts and environment variables for local overrides. The new
|
|
settings guards reject a different Gradle version or daemon JVM rather than
|
|
silently building with an unintended toolchain.
|
|
|
|
**Could not find a matching JDK / no download URL:** install JDK 17 and make it
|
|
discoverable using JAVA_HOME/JDK17_HOME. The package deliberately has no per-machine
|
|
path or automatically provisioned JDK download.
|
|
|
|
## Primary references
|
|
|
|
- Gradle release hashes: https://gradle.org/release-checksums/
|
|
- Gradle 8.14.5 release notes: https://docs.gradle.org/8.14.5/release-notes.html
|
|
- Daemon JVM criteria: https://docs.gradle.org/current/userguide/gradle_daemon.html
|
|
- Android build JVM selection: https://developer.android.com/build/jdks
|
|
- Android command-line builds: https://developer.android.com/build/building-cmdline
|