Packaging a release

A Paracosm release is one folder, made by one command, build/make_release.py (below). Building the server from the source (quickstart.md section 4) is the primary path: it is the only one on Linux and macOS, and the one for anyone who changes the source. For Windows x64 the release also carries a prebuilt server, built from the release's own source zip and never started, so it holds no config, region UUID or token: each install makes its own with tools/make_config.py.

The release version is the one line in VERSION at the repository root (1.0.0).

Making a release: build/make_release.py

Commit everything first: the release is HEAD as committed. Then, from the repository root:

python build/make_release.py --sqlite3-dll PATH/sqlite3.dll [--starter-oar PATH] [--island-oar PATH]

It writes <the repository's parent>/paracosm-release/<version>/ (or --out DIR, which must be outside the repository) and refuses a folder that is not empty unless --clean. It prints PASS or FAIL for every check, a table of the files (size, SHA-256 prefix) at the end, and exits 1 on any failure. A failure in the source stops the run before anything is built from it. The server build takes several minutes (dotnet at idle priority).

What it does and checks:

The demo token is public (it shipped in the source) and every WorldBridge since the fail-closed change refuses it, so it may stay in the files that refuse or document it and in the early scenes/ scripts that still send it (handbook/README.md); the script lists them, and it anywhere else is a failure. The two versioned files under assets/ (assets/firestorm-ref-skin.json, assets/boulders/originals.json) are allowed; anything else there is not.

The server zip holds one folder, paracosm-server-<version>/:

The source by hand

make_release.py does this for you. By hand, ship an export of one commit, not the repository:

git archive --format=zip --prefix=paracosm/ -o ../paracosm-src.zip HEAD

git archive writes the tracked files of that commit and no history. The history still holds retired demo values (the old WorldBridge demo token and earlier default passwords), so it is not published. Everything git ignores stays out by construction: .env, backups/, assets/, opensim-src/, *.zip, *.db, *.log, *.bak. build/source-commit is marked export-subst in .gitattributes, so the export holds the commit's hash there, and a server built from the export records it in paracosm-build.json.

The export carries the OpenSim patches (opensim-patches/), WorldBridge, the MCP server, the tools, the config templates, the build and run scripts, the viewer patches and build scripts (the LGPL source for the viewer, against the base commit named in viewer-patches/README.md), the handbook, LICENSE, NOTICE.md and .env.example.

Before exporting, check that no value from your own .env is tracked: for each password or token, git grep -n -F "<value>" must print nothing.

The portable viewer zip (Windows x64)

Prerequisites

Not needed: FMOD, Havok, KDU (nothing licensed), NSIS (the package is a zip, not an installer).

Steps

The scripts default to the folder C:\fs; set FS_ROOT (and VCVARS, PY_SCRIPTS, see viewer-build/configure.bat) if yours differ.

1. Get the pinned sources and apply the ten patches (viewer-patches/README.md):

   cd /d C:\fs
   git clone https://github.com/FirestormViewer/phoenix-firestorm.git
   git clone https://github.com/FirestormViewer/fs-build-variables.git
   git -C fs-build-variables checkout c17312d3
   cd phoenix-firestorm
   git checkout -b paracosm 3125052b
   git am C:/paracosm/viewer-patches/00*.patch
   

2. Configure: C:\paracosm\viewer-build\configure.bat (autobuild with --opensim --chan Paracosm and LL_TESTS=FALSE). It ends with CONFIGURE_EXIT=0.

3. Build: C:\paracosm\viewer-build\build.bat (msbuild directly, at low priority). It ends with BUILD_EXIT=0. A first build takes about half an hour.

4. Package:

   python C:/paracosm/viewer-build/package.py [--out C:/fs/paracosm-package]
   

   It runs Firestorm's own viewer_manifest.py with the copy package actions into <out>/Firestorm-Paracosm/, which lays out a runnable viewer (the exe with its app_settings, character, fonts, skins and plugins). The manifest's last step builds an NSIS installer and fails without NSIS; the script says so and carries on, because the staging is complete by then. It then removes the Vivox voice binaries (SLVoice.exe, vivoxsdk_x64.dll, ortp_x64.dll, VivoxAUP.txt) and the installer script, adds the licence files and the patch source (below), writes README-FIRST.txt, and zips the folder as <out>/Firestorm-Paracosm-<version>-win64-portable.zip (the version from the build's viewer_version.txt).

The reference package is Firestorm-Paracosm-7.2.5.1-win64-portable.zip, 341 MB. The zip holds one folder, Firestorm-Paracosm/, whose FirestormOS-Paracosm.exe runs from wherever it is unzipped. Its launch on a clean Windows account has not been checked yet.

Licences in the viewer package

The viewer is LGPL 2.1. Firestorm-Paracosm/ in the zip carries:

package.py stops before running the manifest if either Firestorm licence file, LICENSE, NOTICE.md or the patches are missing. The source offer is the patch series in the zip plus the upstream base commit; the full source export above carries the same patches. Firestorm-Paracosm is a downstream modified build, not an official Firestorm release (NOTICE.md).

macOS and Linux viewer builds are not made or documented here; Firestorm's own doc/building_*.md cover them.

The server build output

build/build_server.py <out> leaves:

A bin/ is per-install once it has config or has run. A prebuilt server is built from a fresh source export that has no .env (the config step is then skipped and prints the command to run later) and is never started before shipping; make_release.py does exactly that and checks the result. Ship bin/ with none of the items below.

The docs as web pages

The docs are also published as plain web pages beside the Paracosm page (neap.systems/paracosm/docs/), so they can be read without downloading a release. From the repository root:

python build/make_docs_site.py [OUT_DIR]
python build/check_docs_site.py [OUT_DIR]

OUT_DIR defaults to build/out/docs (git-ignored). make_docs_site.py needs markdown-it-py (in requirements.txt, used by nothing else). It renders the root README.md as the docs home, with the handbook's contents listed under it, then the handbook in the order of its contents page, the MCP server's, WorldBridge's, the viewer patches' and each OpenSimulator patch's notes, and NOTICE.md; plan_docs() in the script is the list, and it prints what it made and what it left out. A link to another rendered doc becomes a link to its page (headings get GitHub's ids, so #anchors carry over); a link to any other file in the repository is shown as its path in code style, because that file is only in the source zip. Every page shares one stylesheet, docs.css (from build/docs.css), and there is no JavaScript, no web font and nothing fetched from another host.

check_docs_site.py parses every page and fails unless every internal link and #anchor resolves inside OUT_DIR (the one link out is the header's, up to the Paracosm page), no page and no stylesheet fetches anything from another host, every doc in the list has its page and a <doc title> - Paracosm docs title, and every table sits in its own scrolling box. Publish by copying OUT_DIR as it is to docs/ beside the Paracosm page.

Never in a release

make_release.py refuses any of these in the source zip or the server zip.