Skip to content

android: Fix resource extraction on Android 10 and shallow CI builds - #1867

Open
arsdragonfly wants to merge 1 commit into
c3d:devfrom
arsdragonfly:android-files-fix
Open

arsdragonfly wants to merge 1 commit into
c3d:devfrom
arsdragonfly:android-files-fix

Conversation

@arsdragonfly

Copy link
Copy Markdown

Summary

Fixes #1864 and #1863 by correcting the Android data directory selection across API levels and ensuring bundled resources (help/, config/, library/) are always extracted on first run even in shallow CI builds.

Root Causes

  1. Android $\le$ 10 (#1864): Commit ab0bfa67 (#1816) switched AppDataLocation to QStandardPaths::writableLocation(QStandardPaths::GenericDataLocation). In Qt's qstandardpaths_android.cpp, GenericDataLocation only returns Context.getExternalFilesDir(null) (.../Android/data/<package>/files) when sdkVersion() >= 30 (Android 11+). On Android 10 and older (sdkVersion() < 30), GenericDataLocation returns Environment.getExternalStorageDirectory() (/storage/emulated/0), which fails with EACCES without runtime permission requests and leaves Android/data/<package>/files empty.
  2. Shallow CI builds (#1863 / #1864):
    • actions/checkout@v6 defaults to fetch-depth: 1 (no tags), so git describe fails and DB48X_VERSION is "".
    • On a fresh installation where .assets-version (in sim-main.cpp) and QSettings "AssetVersion" (in sim-window.cpp) do not exist yet, found and savedAssetVersion both default to "". Comparing found != wanted ("" != "") evaluated to false, completely skipping resource extraction on first launch.
    • sim/help/img.qrc did not depend on help/$(NAME).md (which populates help/img/*.bmp from doc/img/*.bmp).
    • sim-main.cpp and sim-window.cpp used separate stamp mechanisms (.assets-version vs QSettings), causing the 4.6 MB resource tree to be extracted twice on every version update.

Changes

  • sim/sim-install.h & sim/sim-install.cpp:
    • Add sim_install_data_dir() which selects Context.getExternalFilesDir(null) via QStandardPaths::standardLocations(QStandardPaths::AppDataLocation) (available at index 1 on all Android API levels without runtime permissions) and falls back to writableLocation(QStandardPaths::AppDataLocation) if external storage is unavailable.
    • Add sim_install_needed() and sim_install_write_stamp() which verify that HELPFILE_NAME, config/library.csv, and a non-empty .assets-version stamp exist on disk before skipping extraction.
  • sim/sim-main.cpp & sim/sim-window.cpp:
    • Use sim_install_data_dir(), sim_install_needed(), and sim_install_write_stamp() consistently so resources are extracted once and never skipped on fresh installs.
  • Makefile & .github/workflows/build.yml:
    • Fall back to git rev-parse --short HEAD when git describe fails, pass fetch-depth: 0 in Android CI jobs, and make sim/help/img.qrc depend on help/$(NAME).md.

- Use QStandardPaths::standardLocations(QStandardPaths::AppDataLocation)
  (selecting Context.getExternalFilesDir(null), with fallback to
  internal AppDataLocation) instead of GenericDataLocation. In Qt 6,
  GenericDataLocation returns /storage/emulated/0 on Android <= 10 (API
  < 30), where extraction fails without runtime storage permissions.
- Require both help and config/library.csv plus a non-empty
  .assets-version stamp before skipping extraction, and unify the stamp
  check between sim-main.cpp and sim-window.cpp so resources are not
  extracted twice and empty DB48X_VERSION strings on shallow checkouts
  do not skip first-run extraction.
- Fall back to git rev-parse --short HEAD for VERSION in Makefile and
  fetch full history in Android CI jobs, and make sim/help/img.qrc
  depend on help/$(NAME).md so help/img/*.bmp is populated first.

Fixes: c3d#1863
Fixes: c3d#1864

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
@evgaster

evgaster commented Nov 2, 2026

Copy link
Copy Markdown

This looks very promising (impression after a first read of the above and the code).

I knew #1816 could perhaps cause problems for older Android versions. But what exactly and how to fix wasn't clear to me (yet). Considering declining usage of older versions getting USB/PC access in, had priority.

About sim_install_needed, I don't think the helpfile of library.csv are the right / only criteria. There are a lot of other relevant files. Perhaps wantedVersion is the, only to be used, criterium.

I don't know why Jean chose a file .../.assets-version for it. Wouldn't a QSetting be better?

If there is a ..._write_stamp, why not a ..._read_stamp. I like symmetry.

Supersedes a few changes I sneaked into #1865 in addition to the fix for the subject. Will look into that. I would appreciate your feedback on that PR, in particular on the documentation.

I intend to take your contribution for some tests.

@Wiljea chime in please.

@Wiljea

Wiljea commented Nov 2, 2026

Copy link
Copy Markdown

Thanks @arsdragonfly, and thanks Ed for asking.

Why a file. .assets-version was added because the old !QDir(files).exists() test never fired on Android, since the Qt bootstrap creates the directory first. The AssetVersion QSetting already existed then, and only copied the help files. I would keep the file: it lives inside the tree it describes, so if that tree is deleted, for instance over USB since #1816, the stamp goes with it and extraction runs again. A QSetting would still say that everything is up to date.

The criterion. I agree with Ed: the stamp alone should decide. Extract when it is missing or differs from the wanted version. Since it is written after the copy, an interrupted extraction runs again. Checking two particular files adds little, and the non-empty stamp already covers the case of an empty version. A ..._read_stamp would also make this simpler.

One remaining weakness. copy() ignores the result of sim_install_copy_file, so the stamp is written even if extraction failed, for instance on a full disk. It would be better to write it only after a complete copy.

Directories. I read qstandardpaths_android.cpp in Qt 6.8: it matches the description. GenericDataLocation returns the external files directory only from API 30, and index 1 of standardLocations(AppDataLocation) is that same directory. So nothing moves on Android 11 and later. Our builds use Qt 6.10.3, which I have not checked.

I have not run this PR yet. I can test an update in place on Android 13. The Android 10 test has to come from the reporter of c3d/db48x#1864.

Author & design: Jean Wilson
🤖 Generated with Claude Code

@evgaster

evgaster commented Nov 2, 2026

Copy link
Copy Markdown

I took the Makefile and build.yml changes from this PR to build Android only. Results are here.

Installed the db50x artifact on my Pixel 10, Android version = 17.
Hurrah! Resources seem to be there (checked the help file and some library items).
So for Android = 17, this fixes #1863.

@evgaster

evgaster commented Nov 3, 2026

Copy link
Copy Markdown

Installed the db50x artifact on my Pixel 10, Android version = 17.

Tried also on my Samsung Galaxy S10e, Android version = 12. I had to allow Google drive as a source for where the App comes from. During install a dialog about the Play Store scan flashes by. Did not get a chance to tap Skip. Then it kept Installing for ages. Couldn't Cancel. Eventually swiped it away. Tried again ... same effect.

@evgaster

evgaster commented Nov 3, 2026

Copy link
Copy Markdown

Tried also on my Samsung Galaxy S10e, Android version = 12.

This time I used the Chrome browser to surf to the Artifacts. After logging in to GitHub I could download db50x.apk. I had to allow Chrome as a source for apps. This time the scan dialog did allow me to skip. The App installs and works (limited testing) like on my Pixel 10.

@evgaster

evgaster commented Nov 9, 2026

Copy link
Copy Markdown

See #1864 (comment) and later, for info on testing on Android 10.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants