Script Reference

Additional Info TL;DR - For reference when needed on developer scripts for an app repos built on Pankosmia

Table of Contents

Ecosystem setup and configuration

This repo pulls together several libraries and projects into a single app. The projects are spread across several repos to allow modular reuse. Scripts follow for assisting in setup, though it can also all be setup manually. The following assume the repos are installed with the following directory structure.

This is an example. Clients in use may vary. Configuration is handled via app_config.envand the app_setup script.

|-- repos
    |-- pankosmia
        |-- core-client-content repository
        |-- core-client-dashboard repository
        |-- core-client-i18n-editor repository
        |-- core-client-remote-repos repository
        |-- core-client-settings repository
        |-- core-client-workspace repository
        |-- [your-desktop-app-repo-name] (30 characters or less on windows!)
        |-- resource-core
        |-- webfonts-core

Installing the clients

The local_server (pankosmia_web) serves compiled files from the build directory of each client, so each client must be built.

This is handled by the clone and build_clients scripts, though can also all be run manually which is helpful during development.

# In each client repo, NOT this repo!
npm ci
npm run build

Running run, build_server, or bundle_... all copy the latest build to the build environment.

Scripts

Scripts are located in <os>/scripts/ and must be run from that directory (e.g., cd linux/scripts/, cd windows\scripts\, cd macos/scripts/). Scripts will fail if run from a different location. File extensions by OS: Linux → .bsh, macOS → .zsh, Windows → .bat (unless otherwise noted). Paths use / on Linux/macOS and \ on Windows. [1]

Configuration

Config files must match clients and assets utilized. Scripts that write them are provided, as per app_config.env. Files created by the app_setup script are:

  • buildSpec.json
  • /globalBuildResources/i18nPatch.json
  • /globalBuildResources/product.json
  • /<os>/buildResources/setup/app_setup.json

Review app_config.env and adjust as needed, then run one of the setup scripts that follow. Re-run the app_setup script anytime app_config.env is changed.

Config scripts:

Run from the provided location:

Description Script & Arguments
cd <os>/scripts/
Linux: `.bsh` | macOS: `.zsh` | Win: `.bat`
Uses app_config.env to generate/rebuild/replace app_setup.json, buildSpec.json, product.json, and i18nPatch.json app_setup

Setup scripts:

Run from the provided location:

Description Script & Arguments
cd <os>/scripts/
Linux: `.bsh` | macOS: `.zsh` | Win: `.bat`
Clones all repos in /app_config.env if a directory by that name does not already exist clone
  Default clones via HTTPS.
Optional argument:
clone -s
  Clones via SSH.
For each asset repo in /app_config.env: git checkout main, git pull
For each client repo in /app_config.env: git checkout main, git pull, npm ci, and npm run build.
Dev’s should build manually when testing branch(es).		 build_clients
Optional arguments:
build_clients [branch|dev|qa] [dev|qa]
  Where “my-branch” does not exist, then fallback will be “main” unless the next argument is specified. If “dev” is indicated then a “dev” → “qa” → “main” fallback is implied. If “qa” is indicated then a “qa” → “main” fallback is implied.
build_clients -d
  Deletes past logs without asking.
build_clients -f
  Skip pull because all repos are known to be fresh clones.
Create an Electronite viewer for use with the local dev build environment. build_viewer
Windows: uses .ps1 (use a PowerShell terminal)

Usage scripts:

Note: Multiple arguments can be applied in any order, e.g., build_server -s dev debug is the same as build_server debug dev -s

Description Script & Arguments
cd <os>/scripts/
Linux: `.bsh` | macOS: `.zsh` | Win: `.bat`
Removes the build directory and runs cargo clean [4] clean
Optional argument:
clean -s
  Will not ask if server is off
Runs cargo build and node build.js build_server
Optional arguments:
build_server dev
  Uses the “dev” version in /local_server.env
build_server qa
  Uses the “qa” version in /local_server.env
build_server -s
  Will not ask if server is off
build_server [ critical | normal (default) | debug | off ]
  Re-writes log level in Rocket.toml
Assembles the build environment (clients) and starts the server [2] run
Optional argument:
run -s
  Will not ask if server is off
Launches the Electronite viewer for use with the dev environment. (Requires the viewer having previously been created via the build_viewer script.) viewer
Dev Tools: Ctrl + Shift + I (macOS: Cmd + Option + I)
Optional argument:
viewer [PORT#]
(default is 19119)
Deletes the last bundles and temp contents for the given OS (if they exist), then on this repo runs git checkout main, git pull, and npm ci, runs app_setup to ensure version consistency, runs node build.js, then makes a zip release bundle and a stand-alone installer. (*) (•) bundle_viewer
Linux: No optional arguments. Only builds and bundles the viewer. Do all else in the description manually or through other scripts listed here.
Windows: Uses .ps1. Optional argument:
bundle_viewer.ps1 -ServerOff "Y"
  Will not ask if server is off
macOS: Optional argument:
bundle_viewer -s
  Will not ask if server is off
Deletes the last release bundle if it exists, then on this repo runs git checkout main, git pull, and npm ci, runs app_setup to ensure version consistency, runs node build.js, then makes a zip/tgz release bundle [2] Linux: bundle_tgz
Windows: bundle_zip.ps1
macOS: bundle_zip
Optional arguments:
Linux/macOS:
bundle_tgz -s / bundle_zip -s
  Will not ask if server is off
bundle_tgz -g / bundle_zip -g
  Run from GitHub Actions
Windows:
bundle_zip.ps1 -ServerOff "Y"
  or: “y”; Will not ask if server is off
bundle_zip.ps1 -IsGHA "Y"
  or: “y”; Run from GitHub Actions

Maintenance scripts:

Run from the provided location:

Description Script & Arguments
cd <os>/scripts/
Linux: `.bsh` | macOS: `.zsh` | Win: `.bat`
Facilitates syncing with upstream with exclusion of files expected to differ: sync
Optional argument:
sync -p
  Will not ask if latest is already pulled.

Footnotes

[1] … When running a bat script from a command prompt, the .\ included in the examples is optional.

[2] … Ensure the local server is current! This is the build_server script, or build_server dev or build_server qa if /local_server.env has different versions from the panksomia_web in /local_server/Cargo.toml.

[3] … Environment prerequisite for running the exe build locally: Install Inno Setup - tested with v6.4.3

[4] … Targeted clean tips:

  • To clean just the local server: cd to the /local_server directory and run cargo clean
  • To clean just the build environment, cd to the subdirectory for your OS (i.e., /macos, /linux, or /windows), then recursively remove its build subdirectory.
  • (The clean script does all of the above.)