App Spin-up

How to fork and configure a Desktop App repo built on Pankosmia

Table of Contents

Fork desktop-app-template

Desktop-app-template is a repo designed to be forked to spin up and maintain new Desktop App repos built on Pankosmia.

  1. Start at https://github.com/pankosmia/desktop-app-template/fork

  2. Choose a repository name of 30 characters or less if you want to keep Windows developers from needing to clone to a shorter local repo name. The windows cargo build c compiler requires repos names of 30 characters or less.

  3. Create Fork

Setup 

    |-- repos
    |-- pankosmia
        |-- [your-desktop-app-repo-name] (30 characters or less on windows!)

package.json

Replace all instances of “desktop-app-template” in package.json with “[your-desktop-app-repo-name]”

At the root of your clone of this repo, run: 

    npm install

Edit app_config.env

Entering the App Name, version number, Apps Short Name for working directory, assets, and clients.

Required Assets:

  • ASSET1=resource-core
  • ASSET1_PATH=/runtime_resources
  • ASSET1_NAME=app_resources
  • ASSET2=resource-core
  • ASSET2_PATH=/templates
  • ASSET2_NAME=templates
  • ASSET3=webfonts-core
  • ASSET3_PATH=/
  • ASSET3_NAME=webfonts

Required Clients:

  • CLIENT1=core-client-dashboard
  • CLIENT2=core-client-content
  • CLIENT[any number]=core-client-settings
  • CLIENT[any number]=core-contenthandler-generic
  • # Keep numbering sequential. Do not skip numbers.

Branding

Change /globalBuildResources/theme.json directly to customize your app. For helful tips, see the Theme section of UX/UI guidelines.

For implementing your logo, see the Branding README for scripts to customize /globalBuildResources/.ico, /globalBuildResources/.png, and /globalBuildResources/icon.icns, along with info on how each is used.

Setup Scripts

cd [os]/scripts

Run[1] the clone script to clone all repos listed in app_config.env (assets and clients)

Run[1] the app_setup script to generate the config files to match app_config.env. Re-run[1] the app_setup script anytime app_config.env is modified.

Run[1] the build_clients script to build all clients. Be patient. This will take a while.

  • This script defaults to all main branches, pulls the latest, and builds every client each time it is run.
  • Specify branches other than main as arguments: ./build_clients.[ext] [my-branch|dev|qa] [dev|qa][1]. 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. To build repos manually, run npm run build on just those repos as needed.

Run[1] the build_server script to build the Pankosmia server and assemble the build environment. When /local_server.env has different versions from the panksomia_web in /local_server/Cargo.toml, then use ./build_server.[ext] dev to build a local dev server, and ./build_server.[ext] qa to build a local qa server. Be patient. This will take a while.

(Optional) Run[1] the build_viewer script to create an Electronite viewer for use with the local development environment. Be patient, especially in Windows.

Running your Setup

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

  • Only one instance of the same server can be running at a time.

Run the viewer script to use the Electronite viewer with the local dev build environment, or launch a browser at the location indicated.

Footnotes

[1] … Windows developers, run .bat scripts from a Powershell or Command prompt:
…repos\pankosmia[your-desktop-app-repo-name]\windows\scripts> .[scriptname].bat
The .\ is optional from a command prompt.
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