Package the desktop app for macOS (.app, DMG) and Windows (portable folder with its toolchain)

apps/portablekit/packaging/THIRD_PARTY_NOTICES.md

@@ -0,0 +1,99 @@
+# Third-party notices
+
+PortableKit is distributed under the MIT License (`PortableKit-LICENSE.txt`). Its released builds also contain the third-party software listed here, each under its own license. The license texts are in the same directory as this file: `PortableKit.app/Contents/Resources/licenses/` on macOS, `licenses\` in the Windows folder.
+
+PortableKit does not include any game, game assets or keys. You provide the disc images of games you own; what it makes from them (the prepared executable, the recompiled code and the libraries compiled from it) stays on your computer and is for your own use only.
+
+A build that also contains other components, such as HLE extension modules (see PortableKit's `docs/HLE_EXTENSIONS.md`), lists them and ships their licenses beside this file, and is distributed under the terms that combination requires.
+
+## Compiled into the program
+
+### Dear ImGui 1.92.9b
+
+The library window, the in-game menu and the setup screens. Copyright (c) 2014-2026 Omar Cornut. MIT License: `DearImGui-LICENSE.txt`. <https://github.com/ocornut/imgui>
+
+### tiny-AES-c
+
+AES for preparing the executable from the disc image and for save data. Commit `23856752fbd139da0b8ca6e471a13d5bcc99a08d`, released into the public domain under the Unlicense: `tiny-AES-c-UNLICENSE.txt`. <https://github.com/kokke/tiny-AES-c>
+
+### stb_truetype 1.26
+
+Draws the game's text. Copyright (c) 2017 Sean Barrett. Used under the public-domain dedication it offers as an alternative to the MIT License:
+
+> This is free and unencumbered software released into the public domain. Anyone is free to copy, modify, publish, use, compile, sell, or distribute this software, either in source code form or as a compiled binary, for any purpose, commercial or non-commercial, and by any means.
+
+<https://github.com/nothings/stb>
+
+### stb_image 2.30 and stb_image_write 1.16
+
+Read and write the PNG images of HD texture packs. Copyright (c) 2017 Sean Barrett. Used under the same public-domain dedication as stb_truetype above. <https://github.com/nothings/stb>
+
+### xxHash 0.8.3
+
+Hashes textures for HD texture packs. Copyright (c) 2012-2021 Yann Collet. BSD 2-Clause License: `xxHash-LICENSE.txt`. <https://github.com/Cyan4973/xxHash>
+
+## Shipped as separate libraries
+
+These are dynamically linked shared libraries: in `PortableKit.app/Contents/Frameworks/` on macOS, next to `portablekit.exe` on Windows. They are unmodified builds of the upstream releases below. You may replace them with your own builds of the same or a compatible version.
+
+### SDL3 3.4.16
+
+Window, input and audio output. Copyright (C) 1997-2026 Sam Lantinga. zlib License: `SDL3-LICENSE.txt`.
+
+- Library: `libSDL3.0.dylib` on macOS, `SDL3.dll` on Windows (the unmodified `SDL3-devel-3.4.16-mingw.zip` release build, <https://github.com/libsdl-org/SDL/releases/tag/release-3.4.16>)
+- Source: <https://github.com/libsdl-org/SDL/releases/download/release-3.4.16/SDL3-3.4.16.tar.gz> (SHA-256 `7322236cd12090c3eb40b9728be4d49c76f66ad17d04369584d4ecad5cf77c68`)
+
+### FFmpeg 7.1.5
+
+Decodes games' ATRAC3 and ATRAC3plus audio and their H.264 movies. FFmpeg is licensed under the GNU Lesser General Public License, version 2.1 or later: `FFmpeg-COPYING.LGPLv2.1.txt`, with the source and configuration also noted in `FFmpeg-SOURCE.txt`. This build contains only FFmpeg's LGPL parts and nothing non-free. <https://ffmpeg.org/>
+
+- Libraries on macOS: `libavcodec.61.dylib` and `libavutil.59.dylib`
+- Source: <https://ffmpeg.org/releases/ffmpeg-7.1.5.tar.xz> (SHA-256 `de668509caf9e35e3cd162473441fdb29538c6d96ed080292b3cf9e6fc5d558f`), not modified
+- Configured with:
+
+  ```text
+  ./configure --prefix=<prefix> --enable-shared --disable-static --disable-programs --disable-doc --disable-avdevice --disable-avformat --disable-avfilter --disable-swscale --disable-swresample --disable-network --disable-autodetect --disable-everything --enable-decoder=atrac3,atrac3p,h264 --disable-x86asm --disable-debug
+  ```
+
+- On macOS also with `--install-name-dir=@rpath`, which only sets where the libraries expect each other.
+- Built by the build itself, `cmake/FFmpeg.cmake` in PortableKit (<https://github.com/TeamGDB/PortableKit>), which pins the version, checksum and configuration above.
+
+**Source offer.** The exact FFmpeg source archive above is published on the same release page as every PortableKit build that contains it. For at least three years after we distribute a build, we will also provide that source to anyone who asks through the project's issue tracker, <https://github.com/TeamGDB/PortableKit/issues>, at no more than the cost of providing it.
+
+### Vulkan loader 1.4.357 (macOS only)
+
+Finds and loads the Vulkan driver, MoltenVK. Copyright (c) 2015-2026 The Khronos Group Inc., Valve Corporation and LunarG, Inc. Apache License 2.0: `Vulkan-Loader-LICENSE.txt`. Built for macOS 13 and Apple Silicon, with its Vulkan-Headers of the same tag.
+
+- Library: `libvulkan.1.dylib`
+- Source: <https://github.com/KhronosGroup/Vulkan-Loader/archive/refs/tags/vulkan-sdk-1.4.357.0.tar.gz> (SHA-256 `54f2537df22313768da0317dda2abdaaab7711b4081c48c869a79db343d0ae70`)
+
+### MoltenVK 1.4.2 (macOS only)
+
+Vulkan on Apple's Metal. Copyright (c) 2015-2026 The Brenwill Workshop Ltd. Apache License 2.0: `MoltenVK-LICENSE.txt`. The Khronos release build; only its Apple Silicon (arm64) part is kept.
+
+- Library: `libMoltenVK.dylib`, with its driver manifest in `PortableKit.app/Contents/Resources/vulkan/icd.d/`
+- Release: <https://github.com/KhronosGroup/MoltenVK/releases/download/v1.4.2/MoltenVK-macos.tar> (SHA-256 `f95765a6229cb7b915990a2890ce12ebe36a730b021545d3d52ae69ce4c4024e`); source: <https://github.com/KhronosGroup/MoltenVK/tree/v1.4.2>
+
+## Font
+
+### Noto Sans CJK JP (Noto CJK Sans 2.004)
+
+A fallback for text on systems without a CJK font: `PortableKit.app/Contents/Resources/fonts/NotoSansCJKjp-Regular.otf` (macOS only). Copyright 2014-2021 Adobe (<http://www.adobe.com/>), with Reserved Font Name 'Source'. SIL Open Font License, version 1.1: `NotoSansCJK-OFL.txt`. <https://github.com/notofonts/noto-cjk>
+
+## Windows only
+
+### FFmpeg 7.1.5, prebuilt (Windows)
+
+The Windows build uses the unmodified prebuilt LGPL shared build of FFmpeg 7.1.5 (commit `7d0e842004`) from BtbN/FFmpeg-Builds, built from FFmpeg's LGPL parts only and with `--enable-version3`, so it is licensed under the GNU Lesser General Public License, version 3 or later: `FFmpeg-LICENSE.txt`, with the source location in `FFmpeg-SOURCE.txt`. You may replace these libraries with your own builds of a compatible version.
+
+- Libraries: `avcodec-61.dll`, `avutil-59.dll` and `swresample-5.dll`
+- Release: <https://github.com/BtbN/FFmpeg-Builds/releases/download/autobuild-2026-06-30-13-34/ffmpeg-n7.1.5-1-g7d0e842004-win64-lgpl-shared-7.1.zip> (SHA-256 `03a8003e245c08df4277d7b0adc50b93a97ddd4a3aaafea21943c4384df59895`), pinned in `cmake/FFmpeg.cmake`
+- Source: <https://github.com/FFmpeg/FFmpeg/tree/7d0e842004>
+
+### llvm-mingw 20260922
+
+The compiler PortableKit compiles games with on the player's computer, in `toolchain\`, and the C++ runtime the program itself uses (`libc++.dll`, `libunwind.dll`). An unmodified subset of the llvm-mingw release `llvm-mingw-20260922-ucrt-x86_64.zip` (<https://github.com/mstorsjo/llvm-mingw/releases/tag/20260922>): clang, lld, the LLVM and clang libraries, the headers and the x86_64 runtime libraries.
+
+- LLVM, clang, lld, libc++, libc++abi and libunwind: Apache License 2.0 with LLVM Exceptions, `llvm-mingw-LICENSE.txt` (also `toolchain\LICENSE.TXT`). Source: <https://github.com/llvm/llvm-project>
+- mingw-w64 headers, runtime and winpthreads: their own permissive licenses and public-domain dedications, `mingw-w64-COPYING*.txt`. Source: <https://www.mingw-w64.org/>
+- The llvm-mingw build scripts: <https://github.com/mstorsjo/llvm-mingw>

apps/portablekit/packaging/macos/README.txt

@@ -0,0 +1,60 @@
+PortableKit for macOS (Apple Silicon)
+=====================================
+
+PortableKit plays PSP games you own by recompiling them on this Mac. It ships
+no game and no keys.
+
+Needs: a Mac with Apple Silicon (M1 or newer) and macOS @MINIMUM_SYSTEM_VERSION@ or newer.
+Compiling games needs Apple's free Command Line Tools; PortableKit says how
+to install them when they are missing, and plays games under its interpreter
+(slower) until then.
+
+
+Install
+-------
+
+Drag PortableKit into a folder you can write to, such as Applications or a
+folder of its own. Everything it writes goes to "PortableKit Data" next to
+PortableKit.app: move or delete both and nothing is left behind.
+
+
+First start
+-----------
+
+This build is not notarized by Apple, so the first time you open it macOS
+says that it cannot verify the developer and offers only Done or Move to
+Trash. Choose Done, then:
+
+  1. Open System Settings > Privacy & Security.
+  2. Scroll down to the message about PortableKit and click "Open Anyway".
+  3. Confirm with your password or Touch ID, then "Open Anyway" once more.
+
+Or, from Terminal:
+
+    xattr -dr com.apple.quarantine /Applications/PortableKit.app
+
+The library window then opens. "Add a game..." takes the .iso of your own
+PSP game disc; Play starts it under the interpreter at once and compiles it
+in the background. Esc in the game opens the menu.
+
+
+Keys (optional)
+---------------
+
+Without keys, a game can be added when its disc carries an unencrypted
+executable (BOOT.BIN; many do), and saves are kept unencrypted. The keys
+file's format is described in docs/DESKTOP_APP.md of the PortableKit
+repository. This program contains no keys and does not say where to get them.
+
+
+Command line
+------------
+
+    PortableKit.app/Contents/MacOS/PortableKit help
+
+lists the commands (add, list, compile, run, export, keys, version).
+
+
+Report a problem: https://github.com/TeamGDB/PortableKit/issues (never attach
+game files). Third-party software and its licenses:
+PortableKit.app/Contents/Resources/licenses/

apps/portablekit/packaging/release.env

@@ -0,0 +1,20 @@
+# The desktop app's release, for PortableKit's release scripts:
+#   scripts/release_macos.sh --game . --packaging apps/portablekit/packaging <build>
+#   scripts/package_desktop_windows.ps1 -BuildDir <build> -Toolchain <llvm-mingw>
+# (see docs/RELEASING.md, "The desktop app").
+RELEASE_NAME=PortableKit
+RELEASE_SLUG=portablekit
+RELEASE_TARGET=portablekit
+RELEASE_APP_ID=io.github.teamgdb.PortableKit
+RELEASE_SUMMARY="Play the PSP games you own by recompiling them on your computer"
+RELEASE_URL=https://github.com/TeamGDB/PortableKit
+RELEASE_OVERLAYS=0
+# The profile directory, whose game/ a developer build falls back to.
+RELEASE_PROFILE_DIR=apps/portablekit
+# The recompiler runs beside the program, and the headers the code it makes
+# includes go in Contents/Resources/include, where the program looks for them.
+RELEASE_EXTRA_EXECUTABLES=psp_recomp
+RELEASE_RESOURCES="share/portablekit/include=include"
+# The app knows no game, so no name of one is listed; the scripts' own checks
+# for disc images, executables and saves still apply.
+RELEASE_GAME_NAMES=""

apps/portablekit/packaging/windows/README.txt

@@ -0,0 +1,69 @@
+PortableKit for Windows x64
+===========================
+
+PortableKit plays PSP games you own by recompiling them on this PC. It ships
+no game and no keys. Everything it writes stays in the "data" folder next to
+portablekit.exe: move or delete this whole folder and nothing is left behind.
+Keep it in a folder you can write to (not Program Files).
+
+
+Start
+-----
+
+Double-click portablekit.exe. The library window opens.
+
+  Add a game...   choose the .iso of your own PSP game disc (or drop it on
+                  the window).
+  Play            starts the game at once under the interpreter (slow) and
+                  compiles it in the background; the running game switches to
+                  compiled code when that is done (first a quick build, then
+                  an optimised one). Esc in the game opens the menu.
+
+The compiler it uses is in the "toolchain" folder (LLVM/Clang, llvm-mingw);
+nothing needs installing.
+
+
+Keys (optional)
+---------------
+
+Without keys, a game can be added when its disc carries an unencrypted
+executable (BOOT.BIN; many do), and saves are kept unencrypted. With keys you
+provide yourself, encrypted executables can be decrypted and saves are
+written in the PSP's own format. Import a keys file with
+
+    portablekit keys import <your file>
+
+Its format is described in docs/DESKTOP_APP.md of the PortableKit
+repository. This program contains no keys and does not say where to get them.
+
+
+Command line
+------------
+
+    portablekit add <image.iso> [--executable <decrypted EBOOT>]
+    portablekit list | info <game> | status <game>
+    portablekit compile <game> [--opt 0|2|tiered]
+    portablekit run <game> [--interpreter]
+    portablekit export <game> <folder> [--source-only | --library-only]
+    portablekit keys import <file> | keys status
+    portablekit cache clear <game>
+    portablekit toolchain
+    portablekit version
+
+Add --json for machine-readable output, --data-dir <folder> for another data
+folder.
+
+
+Your data
+---------
+
+    data\games\<game>\   the game's executable prepared from your disc,
+                         settings, saves (ms0)
+    data\cache\<game>\   the recompiled and compiled game code, made on this PC
+
+The compiled code and anything "export" writes are made from your copy of the
+game and are for your own use only. Never share them.
+
+
+Report a problem: https://github.com/TeamGDB/PortableKit/issues (never attach
+game files). Third-party software and its licenses: licenses\

docs/RELEASING.md

@@ -15,6 +15,8 @@ In its own repository:
 | `packaging/icon.png` (256×256), `packaging/linux/README.txt`, `packaging/linux/<app id>.desktop`, `packaging/linux/<app id>.metainfo.xml` | The Linux icon, read-me, desktop entry and AppStream data (`@VERSION@`, `@DATE@` are filled in) |
 | `packaging/android/res/` | For Android, the name and launcher icons; see `packaging/android/README.md` |
 
+`release.env` may also set, for a program with more than one executable file: `RELEASE_EXTRA_EXECUTABLES` (programs of the build's `bin/` to put beside the executable), `RELEASE_RESOURCES` (folders of `bin/` to ship in `Contents/Resources`, as `<from>=<to>`) and `RELEASE_PROFILE_DIR` (where the profile is in the checkout, `.` by default). The desktop app uses all three.
+
 ## macOS
 
 On an Apple Silicon Mac with the macOS 13 SDK installed (the deployment target in `packaging/sources.sh`):
@@ -27,6 +29,34 @@ cmake --build out-release --target <RELEASE_TARGET>
 
 It builds SDL3 and the Vulkan loader from pinned sources for the deployment target, takes MoltenVK's pinned release, assembles `<Name>.app`, links everything inside the bundle, checks the system imports against the macOS 13 SDK, signs ad hoc (no notarization) and packs a disk image into `out/release-macos/dist`, with the FFmpeg source archive and `SHA256SUMS`.
 
+`--packaging DIR` reads `release.env`, the notices and `macos/` from another directory than `<game>/packaging`. `--license NAME=FILE`, `--notices FILE` and `--extra PATH` (each repeatable) add what a build brings beyond the game and the framework: a licence as `licenses/NAME-LICENSE.txt`, a notices file in `licenses/`, and files or folders beside the app in the disk image and the zip.
+
+## The desktop app
+
+The desktop app (`apps/portablekit`, see [DESKTOP_APP.md](DESKTOP_APP.md)) is packed by the same macOS script and by a Windows script of its own. Its release description is `apps/portablekit/packaging`: `release.env`, `THIRD_PARTY_NOTICES.md` for both systems, and a read-me for each.
+
+On macOS:
+
+```sh
+cmake -S apps/portablekit -B out-app-release -G Ninja -DCMAKE_BUILD_TYPE=Release -DPORTABLEKIT_RELEASE=ON
+cmake --build out-app-release
+scripts/release_macos.sh --game . --packaging apps/portablekit/packaging out-app-release
+```
+
+`PortableKit.app` then holds the program, the recompiler beside it in `Contents/MacOS`, and the headers the generated code includes in `Contents/Resources/include`, which is where the program looks for them inside a bundle.
+
+On Windows, with a build of the app made with llvm-mingw (see [DESKTOP_APP.md](DESKTOP_APP.md#windows-ship-an-llvm-toolchain-done)) and configured with `-DPORTABLEKIT_RELEASE=ON`:
+
+```powershell
+scripts\package_desktop_windows.ps1 -BuildDir C:\path\to\build -Toolchain C:\path\to\llvm-mingw
+```
+
+It assembles the portable folder -- the program, the recompiler, their DLLs, the headers, an empty `data\` and the part of llvm-mingw that compiling a game for x86_64 needs, in `toolchain\` -- checks it for game data and for paths of the build machine, starts the packed program to check that it runs and finds its toolchain, and packs `portablekit-<version>-windows-x64.zip` with `SHA256SUMS` and `BUILDINFO.txt` into `out\package-windows\dist`. `-License NAME=FILE`, `-Notices FILE` and `-Extra PATH` work as on macOS, and `-Packaging DIR` names another release description.
+
+### A build with other components
+
+A build that links more than PortableKit's own code, such as [HLE extension modules](HLE_EXTENSIONS.md), is packed with the same scripts: set `PORTABLEKIT_BUILD_LABEL` so it is recognisable (window title, library header, `portablekit --version`), pass each component's licence with `--license`/`-License`, and point `--packaging`/`-Packaging` at a copy of `apps/portablekit/packaging` whose notices list the components. Such a build is distributed under the terms its combination of licences requires.
+
 ## Linux
 
 `scripts/release_linux.sh --game <game>` builds inside the Steam Runtime 3 "sniper" SDK container (podman or docker, x86-64) from the game's generated code, and packs a tarball and a Flatpak bundle. It needs flatpak with Flathub, ostree and curl.