This commit is contained in:
+204
@@ -0,0 +1,204 @@
|
||||
# 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
|
||||
Reference in New Issue
Block a user