Save source and build materials ยท Save replacement script
# Qt replacement - Mosaic 0.25.0 direct Mac edition
This procedure creates **Mosaic Custom.app**. The official app, its signatures,
entitlements, quarantine state and library remain unchanged. A new custom app starts
with a separate empty catalogue in `~/Library/Application Support/Mosaic Custom`.
Do not select the official catalogue when testing modified libraries. To test existing
content, use a backup copy and a separate download destination. Do not run two queue
owners against the same catalogue.
## Source and notices
`Mosaic-0.25.0-Qt-6.11.1-source.zip` contains the Qt Base and PySide setup 6.11.1
archives, LGPLv3/GPLv3 and other included notices, upstream build files and this
procedure. Use About > Open-source licences > Qt > Download source to save it offline.
The source manifest identifies archives by SHA-256; it is not a legal approval.
PySide setup includes Shiboken. Qt Base includes Core, Network, their plugins and
bundled third-party source. System Apple libraries are supplied by macOS.
## Prerequisites
Use the direct edition, macOS 14 or later, and free Apple Command Line Tools
(`xcode-select --install`) for Python 3, `install_name_tool` and local build tools.
No Apple developer account, Developer ID, certificate, private key, paid licence or
network service is used by the replacement script. Building Qt itself additionally
needs CMake and Ninja; upstream `configure` and `CMakeLists.txt` describe its build.
Use a native architecture toolchain and Qt 6.11.1 with the same ABI, exported symbols
and enabled features required by your changes. The script checks architectures, not
semantic ABI compatibility; incompatible modifications can fail at load or runtime.
## Install compatible modified libraries
1. Prepare a directory containing only replacements. Paths are relative to the
shipped helper's `_internal` directory. For example:
`my-libraries/PySide6/Qt/lib/QtCore.framework/Versions/A/QtCore`.
QtNetwork, shipped Qt plugins under `PySide6/Qt/plugins`, PySide `.so`/`.dylib`
and Shiboken `.so`/`.dylib` files can be supplied the same way. Include every
ABI-dependent library changed by your modification. Supply real files, not symlinks.
2. Run (adjust your official app location):
```sh
xcrun python3 make-mosaic-custom.py \
--app "$HOME/Applications/Mosaic Media Library.app" \
--libraries "$HOME/my-libraries" \
--output "$HOME/Applications/Mosaic Custom.app"
```
3. Open `Mosaic Custom.app` normally. It is your locally generated, ad-hoc-signed
build, **not** an Apple-notarized Fancy Little Software release. The script does
not change Gatekeeper, SIP or trust settings. It uses `ditto --noqtn` while creating
the local build so the result does not inherit the input download's quarantine;
the official download remains unchanged. All custom code is signed locally.
The custom copy retains hardened runtime and adds only its local
`disable-library-validation` entitlement because ad-hoc libraries have no Team ID.
The official app never receives that entitlement.
4. A rerun refuses an existing output. Choose another parent directory to compare
builds, or move the previous custom app to the Bin yourself before retrying.
The script never deletes a catalogue, existing app or user media. Failed staging
is removed automatically. A receipt is saved in the custom app's Resources.
Custom code may need its own purchase activation and provider sign-in. This process
never bypasses paid access. Keep the official app for ordinary use and for updates;
an official update does not update the separate custom copy. Do not redistribute
owner-signed or locally modified code as an official release.
## Verification and scope
The included build script and marker patch reproduce the QtCore replacement test.
The marker is inactive unless `MOSAIC_QT_MARKER_LOG` is set. It records its identity
and actual `dladdr` loaded path when the library initializes. This is a diagnostic
modification to Qt source, not an injection or substitute library stub.
Use an empty keychain and the included restricted test environment. A successful
engine test must show the marker, acknowledge a catalogue edit, and read the result
back; launching alone is not sufficient. See the separate engineering evidence for
actual platform coverage and results. This procedure supports legal review of LGPLv3
4(d)(1) and installation information under 4(e); it is not a legal determination and
does not address unrelated component licences or App Store distribution.