Product

Desktop apps built on Pankosmia and what a product contains

Table of Contents

Desktop apps

A product is a desktop app repository (desktop-app-*). It assembles the server, a chosen list of clients, the branding and the product resources. The existing repositories are:

  • desktop-app-template: the template to fork when creating a new desktop app. It is the reference for the rest of this page.
  • desktop-app-pithekos: the Pithekos desktop app, with the same structure as the template and its own name, version and branding.
  • desktop-app-renaissance: the Renaissance desktop app built on Pankosmia.
  • desktop-app-tc4: the tC4 desktop app built on Pankosmia.
  • desktop-app-test-rcl: a desktop app used to test the RCL.

Structure of a desktop app

Item What it does
app_config.env Main configuration: APP_NAME, APP_SHORT_NAME, APP_VERSION, START_OFFLINE, the assets (ASSETn, ASSETn_PATH, ASSETn_NAME), the HOMEPAGE client and the ordered list of clients (CLIENT1, CLIENT2…). Keep core-client-dashboard as CLIENT1.
buildSpec.json The build recipe generated by the app_setup script: app name and version, server binary (bin), folders to bundle (lib), client repositories to include (libClients) and the paths of the favicon, theme, product and client config files.
buildCommon.js Shared build logic: copies the libs and clients, patches the i18n template and copies the product files.
globalBuildResources/ Everything specific to the product that is common to all operating systems (see below).
branding/ Icon sources and scripts that generate the favicons and the Windows and macOS icons.
linux/, macos/, windows/ Per-OS scripts (app_setup, run, sync, build_server…), setup files and build output.
local_server/, local_server.env, Rocket.toml The server and its versions: dev and qa give a version number, and main uses the one in local_server/Cargo.toml.
releases/, CHANGES.md Release folders per OS and the change log.

globalBuildResources

This folder holds everything that makes the product different from another one. The build copies it into the app under lib/app_resources/product/.

File What it does
product.json Identity of the product: name, short_name, version, datetime (build date), homepage (the client opened first) and start_offline. It is regenerated by the build scripts from app_config.env.
client_config.json Default settings of the clients. Keys are client ids, or _global for settings shared by all clients. Each value is a list of groups with an id, an i18n label and fields (each with an id, an i18n label and a value). Example: internetConnectionAccess in _global, read by the dashboard.
theme.json The MUI theme of the product (palette with primary, secondary…).
favicon*.png, favicon.ico, icon.ico, icon.icns, linux_icon.png Icons of the app for the browser, Windows, macOS and Linux.
i18nPatch.json, i18n-overrides.json Product-level text changes, see the i18n page.
product_resources/ Product-specific data, see below.

product_resources

globalBuildResources/product_resources houses the app-specific data. Its content is copied to lib/app_resources/product/product_resources in the built app (when you run in development, to <os>/build/lib/app_resources/product/product_resources).

The convention is one sub-folder per client id, holding the data that this client needs. In the template, core-client-remote-repos/organizations/organization.json lists the Git organizations offered to the remote repos client, so two products can offer different organizations without changing the client:

{
  "organizations": [
    { "name": "BurritoTruck", "url": "git.door43.org/burritotruck" },
    { "name": "unfoldingWord", "url": "git.door43.org/unfoldingword" }
  ]
}