From 20d79a881dc96f91bc6f3294f82ed31e6b7110f8 Mon Sep 17 00:00:00 2001 From: RetroGameDeveloper <40120498+RetroGameDeveloper@users.noreply.github.com> Date: Sun, 8 Nov 2026 16:12:17 +0000 Subject: [PATCH 1/2] feat: add a portable Windows ZIP with relocatable EXE launcher --- .github/workflows/release.yml | 8 ++-- .github/workflows/windows-portable.yml | 27 +++++++++++ README.md | 10 +++- ROADMAP.md | 4 ++ packaging/windows/build.ps1 | 28 +++++++++++- packaging/windows/portable-README.txt | 15 ++++++ packaging/windows/portable-launcher.cs | 58 ++++++++++++++++++++++++ packaging/windows/smoke_portable.py | 50 ++++++++++++++++++++ site/public/index.html | 2 +- src/decompnet/app/launcher.py | 2 + tests/test_windows_portable.py | 63 ++++++++++++++++++++++++++ 11 files changed, 260 insertions(+), 7 deletions(-) create mode 100644 .github/workflows/windows-portable.yml create mode 100644 packaging/windows/portable-README.txt create mode 100644 packaging/windows/portable-launcher.cs create mode 100644 packaging/windows/smoke_portable.py create mode 100644 tests/test_windows_portable.py diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml index bbb6e4437..36d9a984f 100644 --- a/.github/workflows/release.yml +++ b/.github/workflows/release.yml @@ -57,7 +57,7 @@ jobs: run: | $version = (Select-String '^__version__ = "(.*)"' src/decompnet/__init__.py).Matches.Groups[1].Value if ("v$version" -ne $env:TAG) { throw "Tag $env:TAG does not match project version $version" } - - name: Build the Windows setup bundle + - name: Build Windows setup and portable downloads shell: pwsh run: packaging/windows/build.ps1 - name: Attach it to the release @@ -67,11 +67,13 @@ jobs: run: | $installer = (Get-ChildItem dist -Filter '*-windows-x64-setup.exe' | Select-Object -First 1).FullName if (-not $installer) { throw 'Windows setup bundle was not created.' } + $portable = (Get-ChildItem dist -Filter '*-windows-x64-portable.zip' | Select-Object -First 1).FullName + if (-not $portable) { throw 'Windows portable ZIP was not created.' } gh release view $env:TAG 2>$null | Out-Null if ($LASTEXITCODE -eq 0) { - gh release upload $env:TAG $installer --clobber + gh release upload $env:TAG $installer $portable --clobber } else { - gh release create $env:TAG $installer --generate-notes --latest + gh release create $env:TAG $installer $portable --generate-notes --latest } macos: diff --git a/.github/workflows/windows-portable.yml b/.github/workflows/windows-portable.yml new file mode 100644 index 000000000..dd9a2febb --- /dev/null +++ b/.github/workflows/windows-portable.yml @@ -0,0 +1,27 @@ +name: Windows portable +on: + workflow_dispatch: + pull_request: + paths: + - 'packaging/windows/**' + - '.github/workflows/windows-portable.yml' + - 'pyproject.toml' + - 'uv.lock' +permissions: + contents: read +jobs: + portable: + runs-on: windows-latest + steps: + - uses: actions/checkout@v7 + - uses: astral-sh/setup-uv@v10.3.0 + - name: Check native launcher argument forwarding + run: uv run pytest tests/test_windows_portable.py -q + - name: Build and smoke test relocated portable EXE + shell: pwsh + run: packaging/windows/build.ps1 -PortableOnly + - uses: actions/upload-artifact@v4 + with: + name: decompdecomp-windows-x64-portable + path: dist/*-windows-x64-portable.zip + if-no-files-found: error diff --git a/README.md b/README.md index 962853b70..ef1120a4a 100644 --- a/README.md +++ b/README.md @@ -654,7 +654,15 @@ decomp ``` The app opens in a native Windows window. Its shortcuts appear on the desktop and in Start, and its tray icon -brings back a window closed while helpers work. Free tools use Windows builds where available. Projects stay in your Windows `Decomp-RetroReversing` folder. +brings back a window closed while helpers work. + +For a portable Windows download, extract `decompdecomp--windows-x64-portable.zip` +and open `decompdecomp.exe`. Keep its bundled `python` and `packages` folders beside it; +no app installation or administrator access is needed. The native window requires .NET +Framework 4.8 and Microsoft Edge WebView2 Runtime. Projects use +`%USERPROFILE%\Decomp-RetroReversing` (or your explicit `DECOMP_HOME`), so move that +folder too when moving your work. The setup download can install missing Microsoft prerequisites. +Free tools use Windows builds where available. Projects stay in your Windows `Decomp-RetroReversing` folder. > [!IMPORTANT] > **PS1, PS2 and most N64 games need WSL 2 on Windows.** Their period compilers (GCC for PlayStation, EE-GCC and diff --git a/ROADMAP.md b/ROADMAP.md index 6169e3d82..27466fddc 100644 --- a/ROADMAP.md +++ b/ROADMAP.md @@ -868,6 +868,10 @@ similar C through objdiff. Other processors need an instruction reader for this ## Recently done +- **Portable Windows app.** A ZIP bundles a relocatable `decompdecomp.exe`, Python and app + dependencies. No app installation is needed; Microsoft window prerequisites must already be + available. CI extracts the archive to a different path and checks the EXE and server imports. + - **Separate fork data.** Installed copies default to `Decomp-RetroReversing` in the user home; checkouts and separate source handoffs use `Decomp-RetroReversing-dev`. Explicit `DECOMP_HOME` overrides still work. Upstream data is never selected or migrated automatically. diff --git a/packaging/windows/build.ps1 b/packaging/windows/build.ps1 index 36c17f52e..cfde9dc78 100644 --- a/packaging/windows/build.ps1 +++ b/packaging/windows/build.ps1 @@ -1,7 +1,7 @@ -# Build the Windows setup bundle used by the release workflow. It installs missing Microsoft runtimes before running +# Build the Windows portable ZIP and setup bundle used by the release workflow. It installs missing Microsoft runtimes before running # the app's MSI. WiX 3 is used because it does not require accepting the WiX 7 Open Source Maintenance Fee agreement. [CmdletBinding()] -param([switch]$SkipInstallSmoke) +param([switch]$SkipInstallSmoke, [switch]$PortableOnly) $ErrorActionPreference = 'Stop' $repoRoot = (Resolve-Path (Join-Path $PSScriptRoot '../..')).Path @@ -75,6 +75,30 @@ raise SystemExit(main()) } Get-ChildItem -Path $app -Filter '__pycache__' -Directory -Recurse | Remove-Item -Recurse -Force + # Build from the same runtime as the installer, then test after ZIP extraction and relocation. + $compiler = Join-Path $env:WINDIR 'Microsoft.NET/Framework64/v4.0.30319/csc.exe' + if (-not (Test-Path -LiteralPath $compiler)) { throw 'The portable launcher needs the .NET Framework C# compiler.' } + & $compiler /nologo /target:winexe /platform:x64 /reference:System.Windows.Forms.dll ` + "/win32icon=$(Join-Path $app 'decompdecomp.ico')" "/out:$(Join-Path $app 'decompdecomp.exe')" ` + (Join-Path $PSScriptRoot 'portable-launcher.cs') + if ($LASTEXITCODE -ne 0) { throw 'Could not compile the portable Windows launcher.' } + Copy-Item -LiteralPath (Join-Path $PSScriptRoot 'portable-README.txt') -Destination (Join-Path $app 'README.txt') + foreach ($license in @('LICENSE', 'LICENSE-decomp.wtf')) { + Copy-Item -LiteralPath (Join-Path $repoRoot $license) -Destination $app + } + $portable = Join-Path $dist "decompdecomp-$version-windows-x64-portable.zip" + Compress-Archive -Path (Join-Path $app '*') -DestinationPath $portable -Force + $relocated = Join-Path $work 'relocated portable app' + Expand-Archive -LiteralPath $portable -DestinationPath $relocated + $portableRun = Start-Process -FilePath (Join-Path $relocated 'decompdecomp.exe') ` + -ArgumentList '--help' -Wait -PassThru + if ($portableRun.ExitCode -ne 0) { throw 'The extracted portable EXE failed its relocated launch check.' } + & (Join-Path $relocated 'python/python.exe') -c "import site,sys; site.addsitedir(sys.argv[1]); import decompnet.app.server" (Join-Path $relocated 'packages') + if ($LASTEXITCODE -ne 0) { throw 'The extracted portable app failed its server import check.' } + & (Join-Path $relocated 'python/python.exe') (Join-Path $PSScriptRoot 'smoke_portable.py') $relocated + if ($LASTEXITCODE -ne 0) { throw 'The extracted portable EXE failed its isolated server startup/Stop check.' } + if ($PortableOnly) { return } + $wixBin = $env:WIX_BIN if (-not $wixBin) { $wixZip = Join-Path $work 'wix314-binaries.zip' diff --git a/packaging/windows/portable-README.txt b/packaging/windows/portable-README.txt new file mode 100644 index 000000000..37cd4cfa0 --- /dev/null +++ b/packaging/windows/portable-README.txt @@ -0,0 +1,15 @@ +decompdecomp portable for Windows x64 + +Extract the entire ZIP, then double-click decompdecomp.exe. Keep the python and +packages folders beside the EXE. No app installation or administrator access is +needed, and no shortcuts or uninstall entry are created automatically. + +Projects and settings use %USERPROFILE%\Decomp-RetroReversing, separate from +upstream decompdecomp. An explicit DECOMP_HOME environment variable still works. +To move your work to another computer, copy that data folder as well as the app. + +The native window needs .NET Framework 4.8 and Microsoft Edge WebView2 Runtime. +Windows Update normally provides .NET. If WebView2 is missing, install Microsoft's +runtime from https://developer.microsoft.com/microsoft-edge/webview2/ . +The setup download can install these prerequisites for you; the portable app +does not install them silently. Compilers are selected separately in Setup. diff --git a/packaging/windows/portable-launcher.cs b/packaging/windows/portable-launcher.cs new file mode 100644 index 000000000..2b39e69ce --- /dev/null +++ b/packaging/windows/portable-launcher.cs @@ -0,0 +1,58 @@ +// A relocatable entry point for the bundled runtime, without an installer or console window. +using System; +using System.Diagnostics; +using System.IO; +using System.Reflection; +using System.Text; +using System.Windows.Forms; + +internal static class PortableLauncher +{ + // Windows passes a single command line. Preserve quotes, empty arguments and trailing backslashes. + private static string Quote(string value) + { + var result = new StringBuilder("\""); + int slashes = 0; + foreach (char c in value) + { + if (c == '\\') { slashes++; continue; } + result.Append('\\', c == '"' ? slashes * 2 + 1 : slashes); + result.Append(c); + slashes = 0; + } + result.Append('\\', slashes * 2); + return result.Append('"').ToString(); + } + + [STAThread] + private static int Main(string[] args) + { + try + { + string root = Path.GetDirectoryName(Assembly.GetExecutingAssembly().Location); + string python = Path.Combine(root, "python", "pythonw.exe"); + string script = Path.Combine(root, "decomp-launch.pyw"); + if (!File.Exists(python) || !File.Exists(script)) + throw new FileNotFoundException("Extract the entire portable ZIP before opening decompdecomp.exe. Keep it beside the python and packages folders."); + var command = new StringBuilder(Quote(script)); + foreach (string arg in args) command.Append(" ").Append(Quote(arg)); + var start = new ProcessStartInfo(python, command.ToString()); + start.UseShellExecute = false; + start.CreateNoWindow = true; + // An unrelated Python installation must not change the bundled runtime's imports. + start.EnvironmentVariables.Remove("PYTHONHOME"); + start.EnvironmentVariables.Remove("PYTHONPATH"); + start.EnvironmentVariables["DECOMP_PORTABLE"] = "1"; + using (Process child = Process.Start(start)) + { + child.WaitForExit(); + return child.ExitCode; + } + } + catch (Exception error) + { + MessageBox.Show(error.Message, "decompdecomp", MessageBoxButtons.OK, MessageBoxIcon.Error); + return 1; + } + } +} diff --git a/packaging/windows/smoke_portable.py b/packaging/windows/smoke_portable.py new file mode 100644 index 000000000..34235b92e --- /dev/null +++ b/packaging/windows/smoke_portable.py @@ -0,0 +1,50 @@ +"""Start and stop only the extracted portable app, in an isolated home on the Windows build runner.""" +import os +import socket +import subprocess +import sys +import tempfile +import time +import urllib.error +import urllib.request +from pathlib import Path + + +def main(folder): + executable = Path(folder).resolve() / 'decompdecomp.exe' + with tempfile.TemporaryDirectory(prefix='decomp-portable-smoke-') as temporary: + home = Path(temporary) + env = dict(os.environ, HOME=str(home), USERPROFILE=str(home), DECOMP_HOME=str(home / 'data'), + DECOMP_WINDOW='0', DECOMP_TRAY='0') + with socket.socket() as listener: + listener.bind(('127.0.0.1', 0)) + port = listener.getsockname()[1] + process = subprocess.Popen([str(executable), 'serve', '--port', str(port)], cwd=home, env=env) + try: + deadline = time.monotonic() + 90 + while time.monotonic() < deadline: + if process.poll() is not None: + raise RuntimeError(f'The portable app exited before becoming ready: {process.returncode}') + try: + with urllib.request.urlopen(f'http://127.0.0.1:{port}/health', timeout=2) as response: + if response.status == 200: + break + except (OSError, urllib.error.URLError): + time.sleep(.25) + else: + raise RuntimeError('The portable app did not answer its health check within 90 seconds.') + if not (home / 'data/.decomp/server.json').is_file(): + raise RuntimeError('The portable app did not use its explicitly isolated data home.') + subprocess.run([str(executable), 'stop'], cwd=home, env=env, check=True, timeout=40) + if process.wait(timeout=20) != 0: + raise RuntimeError('The portable app did not exit cleanly after Stop.') + print('Extracted portable EXE: isolated server startup, health and graceful Stop passed.') + finally: + if process.poll() is None: + subprocess.run(['taskkill', '/PID', str(process.pid), '/T', '/F'], + capture_output=True, timeout=15, check=False) + process.wait(timeout=15) + + +if __name__ == '__main__': + main(sys.argv[1]) diff --git a/site/public/index.html b/site/public/index.html index 6f96de078..5a7b96da0 100644 --- a/site/public/index.html +++ b/site/public/index.html @@ -261,7 +261,7 @@

Start.

Linux: run it in your terminal. It installs the app and compilers, then opens the app in its own window. There's also a .deb, an .rpm and an AppImage on the releases page.

Projects and settings use ~/Decomp-RetroReversing (%USERPROFILE%\Decomp-RetroReversing on Windows), separate from upstream. Existing DECOMP_HOME overrides are respected; upstream databases are not migrated automatically.

Fork releases use vX.Y.Z-rr.N and include Windows installers and macOS apps for Apple Silicon and Intel.

-

Windows 10 and 11: download and open decompdecomp-<version>-windows-x64-setup.exe from the latest release. The app opens in a native Windows window, with desktop and Start shortcuts and a tray icon. PS1, PS2 and most N64 games also need WSL 2 for their period compilers: run wsl --install in an administrator PowerShell, restart if asked, then open Ubuntu once. GameCube, Wii, DS and Windows PC games, and N64 games built with IDO, don't.

+

Windows 10 and 11: for a portable app, extract the windows-x64-portable.zip download and open decompdecomp.exe. Keep its bundled folders alongside it. The portable download uses the same separate fork data folder and needs .NET Framework 4.8 and Microsoft Edge WebView2 Runtime already available. For setup with prerequisite installation, download and open decompdecomp-<version>-windows-x64-setup.exe from the latest release. The app opens in a native Windows window, with desktop and Start shortcuts and a tray icon. PS1, PS2 and most N64 games also need WSL 2 for their period compilers: run wsl --install in an administrator PowerShell, restart if asked, then open Ubuntu once. GameCube, Wii, DS and Windows PC games, and N64 games built with IDO, don't.

Frequent source updates: Settings → Run from Git can prepare main updates in a separate runtime while agents keep working. Enable automatic updates there; a restart check holds new sessions for at most 15 seconds, then releases them and retries later if active work needs longer. Agents resume with saved usage limits. No app rebuild is needed.

curl -fsSL https://raw.githubusercontent.com/RetroReversing/decompdecomp/main/site/public/install.sh | bash -s -- --source branch:main

macOS 12+ on Intel and Apple Silicon: installs the current source and a Finder app in ~/Applications. Apple Silicon needs Rosetta for the Intel N64 KMC compiler and binutils. PS2 Sony EE-GCC needs the optional local Linux runner: install brew install colima docker, then choose Prepare Linux runner in Compilers & tools. SN Systems EE-GCC 2.95.2/2.95.3 and CodeWarrior PS2 2.3.3/3.0.1 use wibo. Install wibo under Compilers & tools → Tools; existing compiler packs show Install missing tools when a runtime needs repair. Pinned SN packs handle install paths containing spaces automatically; CodeWarrior requires license acceptance in Setup. macOS has no menu bar tray icon yet.

diff --git a/src/decompnet/app/launcher.py b/src/decompnet/app/launcher.py index f06191954..5ce50d840 100644 --- a/src/decompnet/app/launcher.py +++ b/src/decompnet/app/launcher.py @@ -57,6 +57,8 @@ def _shortcut_app_id(shortcut: Path) -> None: def install_launcher() -> str: """Put decompdecomp in the apps menu (a .desktop entry and its icon). A development copy gets none: it's started from its checkout.""" + if os.environ.get("DECOMP_PORTABLE") == "1": + return "the portable app is available through decompdecomp.exe; no shortcuts were installed" if edition.DEV: return "a development copy gets no launcher: run it with `uv run decomp` in the checkout" if sys.platform == "darwin" and os.environ.get("DECOMP_PACKAGE") == "macos": diff --git a/tests/test_windows_portable.py b/tests/test_windows_portable.py new file mode 100644 index 000000000..913e13fb2 --- /dev/null +++ b/tests/test_windows_portable.py @@ -0,0 +1,63 @@ +"""The portable executable keeps working after relocation, without a registered Python install.""" +import base64 +import os +import subprocess +import sys +from pathlib import Path + +import pytest + +from decompnet.app import launcher + +ROOT = Path(__file__).resolve().parents[1] + + +def test_portable_app_does_not_create_shortcuts(monkeypatch): + monkeypatch.setenv('DECOMP_PORTABLE', '1') + monkeypatch.setattr(launcher.edition, 'DEV', False) + monkeypatch.setattr(launcher.Path, 'home', lambda: pytest.fail('Portable setup must not write launcher files')) + assert 'no shortcuts were installed' in launcher.install_launcher() + + +@pytest.mark.skipif(sys.platform != 'win32', reason='needs the native Windows C# compiler') +def test_portable_exe_forwards_arguments_and_exit_status_after_relocation(tmp_path): + compiler = Path(os.environ['WINDIR']) / 'Microsoft.NET/Framework64/v4.0.30319/csc.exe' + if not compiler.is_file(): + pytest.skip('needs the .NET Framework compiler') + original = tmp_path / 'original' + original.mkdir() + subprocess.run([str(compiler), '/nologo', '/target:winexe', '/platform:x64', + '/reference:System.Windows.Forms.dll', '/out:' + str(original / 'decompdecomp.exe'), + str(ROOT / 'packaging/windows/portable-launcher.cs')], check=True, capture_output=True) + helper = tmp_path / 'probe.cs' + helper.write_text('''using System; +using System.IO; +using System.Text; +class Probe { + static int Main(string[] args) { + var lines = new string[args.Length + 3]; + for (int i = 0; i < args.Length; i++) + lines[i] = Convert.ToBase64String(Encoding.UTF8.GetBytes(args[i])); + lines[args.Length] = Environment.GetEnvironmentVariable("DECOMP_PORTABLE"); + lines[args.Length + 1] = Environment.GetEnvironmentVariable("PYTHONHOME") ?? "absent"; + lines[args.Length + 2] = Environment.GetEnvironmentVariable("PYTHONPATH") ?? "absent"; + File.WriteAllLines(Environment.GetEnvironmentVariable("PORTABLE_PROBE_OUTPUT"), lines); + return 37; + } +} +''') + (original / 'python').mkdir() + (original / 'decomp-launch.pyw').touch() + subprocess.run([str(compiler), '/nologo', '/target:winexe', '/platform:x64', + '/out:' + str(original / 'python/pythonw.exe'), str(helper)], check=True, capture_output=True) + relocated = tmp_path / 'moved portable app ü' + original.rename(relocated) + output = tmp_path / 'arguments.txt' + arguments = ['', 'space in argument', 'embedded"quote', 'trailing\\', 'slash\\"quote', '日本語'] + env = dict(os.environ, PORTABLE_PROBE_OUTPUT=str(output), PYTHONHOME='unrelated', PYTHONPATH='unrelated') + result = subprocess.run([str(relocated / 'decompdecomp.exe'), *arguments], env=env, timeout=30) + assert result.returncode == 37 + lines = output.read_text(encoding='utf-8-sig').splitlines() + actual = [base64.b64decode(line).decode('utf-8') for line in lines[:-3]] + assert actual == [str(relocated / 'decomp-launch.pyw'), *arguments] + assert lines[-3:] == ['1', 'absent', 'absent'] From d3e002e8215434e3b7cc77980a907bdb09817707 Mon Sep 17 00:00:00 2001 From: RetroGameDeveloper <40120498+RetroGameDeveloper@users.noreply.github.com> Date: Sun, 8 Nov 2026 16:25:05 +0000 Subject: [PATCH 2/2] build: use Windows 2022 for bounded portable smoke checks --- .github/workflows/windows-portable.yml | 5 ++++- packaging/windows/build.ps1 | 6 +++++- packaging/windows/portable-launcher.cs | 3 +++ 3 files changed, 12 insertions(+), 2 deletions(-) diff --git a/.github/workflows/windows-portable.yml b/.github/workflows/windows-portable.yml index dd9a2febb..8c11a379e 100644 --- a/.github/workflows/windows-portable.yml +++ b/.github/workflows/windows-portable.yml @@ -7,11 +7,14 @@ on: - '.github/workflows/windows-portable.yml' - 'pyproject.toml' - 'uv.lock' + - 'tests/test_windows_portable.py' + - 'src/decompnet/app/launcher.py' permissions: contents: read jobs: portable: - runs-on: windows-latest + runs-on: windows-2022 + timeout-minutes: 15 steps: - uses: actions/checkout@v7 - uses: astral-sh/setup-uv@v10.3.0 diff --git a/packaging/windows/build.ps1 b/packaging/windows/build.ps1 index cfde9dc78..4c7449d0e 100644 --- a/packaging/windows/build.ps1 +++ b/packaging/windows/build.ps1 @@ -91,7 +91,11 @@ raise SystemExit(main()) $relocated = Join-Path $work 'relocated portable app' Expand-Archive -LiteralPath $portable -DestinationPath $relocated $portableRun = Start-Process -FilePath (Join-Path $relocated 'decompdecomp.exe') ` - -ArgumentList '--help' -Wait -PassThru + -ArgumentList '--help' -PassThru + if (-not $portableRun.WaitForExit(30000)) { + $portableRun.Kill() + throw 'The extracted portable EXE did not finish its launch check within 30 seconds.' + } if ($portableRun.ExitCode -ne 0) { throw 'The extracted portable EXE failed its relocated launch check.' } & (Join-Path $relocated 'python/python.exe') -c "import site,sys; site.addsitedir(sys.argv[1]); import decompnet.app.server" (Join-Path $relocated 'packages') if ($LASTEXITCODE -ne 0) { throw 'The extracted portable app failed its server import check.' } diff --git a/packaging/windows/portable-launcher.cs b/packaging/windows/portable-launcher.cs index 2b39e69ce..975371d97 100644 --- a/packaging/windows/portable-launcher.cs +++ b/packaging/windows/portable-launcher.cs @@ -46,6 +46,9 @@ private static int Main(string[] args) using (Process child = Process.Start(start)) { child.WaitForExit(); + if (child.ExitCode != 0 && args.Length == 0) + MessageBox.Show("The app could not start. Check README.txt for the Microsoft window prerequisites and .decomp/logs/decomp.log in your project data folder for details.", + "decompdecomp", MessageBoxButtons.OK, MessageBoxIcon.Error); return child.ExitCode; } }