Packaging & Distribution¶

VSView uses PyApp to create standalone, self-installing executables for Windows, Linux, and macOS.

A custom CLI tool, vsapp, is provided to streamline wheel generation, offline Python distribution bundling, icon generation, and macOS app bundling.

Prerequisites¶

To build the standalone application, you need the following tools installed and available in your PATH:

Python 3.14 or later.
Rust & Cargo: Required to compile the PyApp bootstrapper.
Git Submodules: PyApp source code lives in submodules/pyapp. Ensure submodules are initialized:
```
git submodule update --init --recursive submodules/pyapp
```
ImageMagick 7 (Optional): Required for the vsapp icon command to generate cross-platform icon sets.
iconutil: (macOS only) Required for creating App Bundles (.app) and Macintosh icons (.icns).

The `vsapp` CLI¶

The packaging logic is contained within the vsview-pyapp package (src/pyapp). Ensure your workspace environment is synced:

uv sync

Then you can run the CLI using uv:

uv run vsapp --help

1. Generating Icons¶

The vsapp icon command processes a source image and generates icon formats for Windows, macOS, and Linux.

uv run vsapp icon [OPTIONS] [SOURCE_IMAGE]

Formats:
- Windows: vsview.ico (multi-size icon)
- macOS: vsview.iconset/ (for iconutil conversion)
- Linux: PNGs in standard sizes (16x16, 32x32, etc.)

Pre-generated Icons

The repository includes pre-generated icons in src/pyapp/icons/.

2. Building Executables¶

The vsapp build command automatically packages workspace wheels, sets up the PyApp environment, and compiles the Rust bootstrapper.

uv run vsapp build [OPTIONS]

Build Modes¶

vsapp supports two distinct build modes:

Online (Lightweight)Offline (Self-Contained)

Builds a lightweight VSView executable. At first run, the executable uses uv to dynamically fetch and install vsview and its dependencies from PyPI / index servers.

uv run vsapp build

Builds a fully self-contained VSView-offline executable with an embedded Python 3.14 runtime and pre-installed workspace wheels. Requires no internet access or local Python installation at runtime.

uv run vsapp build --offline

3. macOS App Bundling & Disk Image¶

On macOS, applications are distributed as .app bundles or Disk Images (.dmg).

Generating the App Bundle¶

The vsapp bundle command constructs a standard macOS bundle layout and converts .iconset into a .icns file using iconutil.

uv run vsapp bundle SOURCE VERSION [OPTIONS]

Converts the iconset generated by vsapp icon into a .icns file using iconutil.
Creates the standard macOS bundle structure (Contents/MacOS, Contents/Resources).
Generates a valid Info.plist.

Creating a DMG Installer¶

To package the built .app bundle into a distributable Disk Image with an /Applications shortcut:

mkdir dmg_staging
ditto dist/AppBundle dmg_staging/VSView.app
ln -s /Applications dmg_staging/Applications

hdiutil create -volname VSView -srcfolder dmg_staging -ov -format UDZO dist/VSView.dmg

Configuration¶

The vsapp tool reads configuration from a .env file specified by --env (defaults to src/pyapp/.env.example).