Developer Scripts

Developer scripts for an app repos built on Pankosmia

Use
- Client development:
- To generate artifacts:
Maintenance
Footnotes
Additional Info TL;DR - For reference when needed!

Use

Run^[1] the run script to start the server without a browser launch.

Consider also if you need to delete ~/pankosmia_working first.
You’ll want to restart the server if deleting ~/pankosmia_working after starting the server. To restart, exit the terminal window where the server is running the run the run script^[1] again.
Only one instance of the server can be running at a time.^[3]

Client development:

Manually build the client(s) changed, stop the server it is is running, then start the server (run). The run script will re-assemble the environment to include your build.

Run the viewer script to use the Electronite viewer with the local dev build environment.

To generate a release package for the OS you are using, edit the version number for the release in app_config.env then run^[1] the bundle_... script.

To generate artifacts:

Manually run the desired workflow (Actions > [select workflow] > Run workflow).

The current main branch of client repo and resource at the time of running the workflow will be used.

Download resulting artifacts (Actions > click the name of a run to see the workflow run summary > scroll down to the bottom to the Artifacts section > to download, click either the name of each artifact or the down arrow on each row

Any double-compressed artifacts should have one layer uncompressed before release, e.g.:

Strip *.tgz.zip down to *.tgz
Strip *.zip.zip down to *.zip
If working from windows, avoid releasing a re-zipping a macos or linux zip package if a .pkg, .sh, .bsh, .zsh was in the layer re-zipped in windows. Doing so would otherwise remove file permission settings of chmod +x where they are needed.
Release the *.pkg.zip layer as .zip as it includes a README file in the same layer as the pkg, which contains installation and upgrade instructions / info.

Upload releases manually by going to the Release section of your repo and selecting “Draft a new release”.

Maintenance

To update the server, change the latest version of panksomia-web in /local_server/Cargo.toml and re-run the build_server script.

To sync this repo with its upstream, run the sync script.

Footnotes

[1] … Windows developers, run .bat scripts from a Powershell or Command terminal:
             …repos\pankosmia[your-desktop-app-repo-name]\windows\scripts> .\[scriptname].bat
             Use a powershell terminal for the .ps1 build scripts.
MacOS developers, run .bsh scripts from a MacOS terminal:
             …repos/pankosmia/[your-desktop-app-repo-name]/macos/scripts> ./[scriptname].bsh
Linux developers, run .zsh scripts from a linux terminal:
             …repos/pankosmia/[your-desktop-app-repo-name]/linux/scripts> ./[scriptname].zsh

[2] … The build script will fail on any clients set to a different branch with uncommitted changes or with conflicts vs, the latest main pull. Scroll back up in the terminal to find any build errors and address them.

[3] … If running into an error saying that another instance is running, you can either find the other instance and stop it, or simply reboot. Another instance could be one started from a .zip, .tgz, installed version, run from a different repo, or a manually started panksomia-web.

Additional Info TL;DR - For reference when needed!

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, 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 install
npm run build

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

Scripts

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:

Linux	Windows	MacOS
<pre>buildSpec.json /globalBuildResources/i18nPatch.json /globalBuildResources/product.json /linux/buildResources/setup/app_setup.json</pre>	<pre>buildSpec.json \globalBuildResources\i18nPatch.json \globalBuildResources\product.json \windows\buildResources\setup\app_setup.json</pre>	<pre>buildSpec.json /globalBuildResources/i18nPatch.json /globalBuildResources/product.json /macos/buildResources/setup/app_setup.json</pre>

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:

Setup scripts:

Run from the provided location: | Description | Linux | Windows | MacOS | |——-|——-|———|——-| | Clones all repos in /app_config.env if a directory by that name does not already exit | /linux/scripts/clone.bsh
Default clones via HTTPS.
Optional argument:
./clone.bsh -s
Clones via SSH. | \windows\scripts\clone.bat
Default clones via HTTPS.
Optional argument:
.\clone.bat -s
Clones via SSH. | /macos/scripts/clone.zsh
Default clones via HTTPS.
Optional argument:
./clone.zsh -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 install, and npm run build.
Dev’s should build manually when testing branch(es). | /linux/scripts/build_clients.bsh | \windows\scripts\build_clients.bat | /macos/scripts/build_clients.zsh | | Create an Electronite viewer for use with the local dev build environment. | /linux/scripts/build_viewer.bsh | \windows\scripts\build_viewer.ps1
(use a powershell terminal) | /macos/scripts/build_viewer.zsh |

Usage scripts:

Note: Multiple arguments can be applied in any order, e.g., ./run.zsh -s -d is the same as ./run.zsh -d -s

Description	Linux	Windows	MacOS
removes the build directory and runs `cargo clean` (%)	/linux/scripts/clean.bsh Optional arguments: `./clean.bsh -s` Will not ask if server is off	\windows\scripts\clean.bat Optional arguments: `.\clean.bat -s` Will not ask if server is off	/macos/scripts/clean.zsh Optional arguments: `./clean.zsh -s` Will not ask if server is off
runs cargo build, and `node build.js`	/linux/scripts/build_server.bsh Optional arguments: `./build_server.bsh -s` Will not ask if server is off `./build_server.bsh -d` Builds server in debug mode	\windows\scripts\build_server.bat Optional arguments: `.\build_server.bat -s` Will not ask if server is off `.\build_server.bat -d` Builds server in debug mode	/macos/scripts/build_server.zsh Optional arguments: `./build_server.zsh -s` Will not ask if server is off `./build_server.zsh -d` Builds server in debug mode
Assembles the build environment (clients) and starts the server *()**	/linux/scripts/run.bsh Optional arguments: `./run.bsh -s` Will not ask if server is off `.\run.bsh -d` Runs with server in debug mode	\windows\scripts\run.bat Optional arguments: `.\run.bat -s` Will not ask if server is off `.\run.bat -d` Runs with server in debug mode	/macos/scripts/run.zsh Optional arguments: `./run.zsh -s` Will not ask if server is off `.\run.zsh -d` Runs with server in debug mode
Launches the Electronite viewer for use with the dev environment. (Requires the viewer having previously been created via the `build_viewer` script.)	/linux/scripts/viewer.bsh Dev Tools: Ctrl + Shift + I Optional argument: `./viewer.bsh [PORT#]` (default is 19119)	\windows\scripts\viewer.bat Dev Tools: Ctrl + Shift + I Optional argument: `.\viewer.bat [PORT#]` (default is 19119)	/macos/scripts/viewer.zsh Dev Tools: Cmd + Option + I Optional argument: `./viewer.zsh [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 install`, runs `app_setup.bat` to ensure version consistency, runs `node build.js`, then makes a zip release bundle and a stand-alone installer. *() (•)**	/linux/scripts/bundle_viewer.bsh (Only builds and bundles the viewer. Do all else in the description manually or through other scripts listed here.)	\windows\scripts\bundle_viewer.ps1 Optional arguments: `.\bundle_viewer.ps1 -ServerOff "Y"` or: “y”; Will not ask if server is off	/macos/scripts/bundle_viewer.zsh Optional arguments: `./bundle_viewer.zsh -s` Will not ask if server is off
Deletes the last .zip release bundle if it it exists, then on this repo runs `git checkout main`, `git pull`, and `npm install`, runs `app_setup.bat` to ensure version consistency, runs `node build.js`, then makes a zip release bundle *()**	/linux/scripts/bundle_tgz.bsh Optional arguments: `./bundle_tgz.bsh -s` Will not ask if server is off `/bundle_tgz.bsh -g` Run from Github Actions	\windows\scripts\bundle_zip.ps1 Optional arguments: -ServerOff “Y” or: “y”; Will not ask if server is off -IsGHA “Y” or: “y”; Run from Gihtub Actions	/macos/scripts/bundle_zip.zsh Optional arguments: `/bundle_zip.zsh -s` Will not ask if server is off `/bundle_zip.zsh -g` Run from Github Actions
Deletes the last .exe release bundle if it it exists, then on this repo runs `git checkout main`, `git pull`, and `npm install`, runs `app_setup.bat` to ensure version consistency, runs `node build.js`, then makes an exe installer *() (•)**		\windows\scripts\bundle_exe.ps1 Optional arguments: `bundle_exe.ps1 -ServerOff "Y"` or: “y”; Will not ask if server is off (•)

()** **Ensure the server (build_server.bat) is current!
(•) *Environment prerequisite for running the exe build locally: Install Inno Setup -tested with v6.4.3
(%) Targeted clean tips:

To clean just the dev server: cd to the /local_server directory and run cargo clean --target-dir target/debug
To clean just the dev server: cd to the /local_server directory and run cargo clean --target-dir target/release
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.)

Maintenance scripts: