# install_app

> **Tool `tools/install/install_app.py`** (program, Installing builds). Build a project's release programs and install them in the GameFrame folder, as an application the player can open.

Run it with `./gameframe run install_app ARGS` or `python3 tools/install/install_app.py`. [Source on GitHub](https://github.com/tanepiper/game-frame/blob/main/tools/install/install_app.py).

## Its own help

This is the help text in the tool itself, as `./gameframe tool install_app` prints it.

```text
Build a project's release programs and install them in the GameFrame folder, as an
application the player can open.

Usage:
  install_app.py [vanilla | extra] [--project DIR] [--dest DIR] [--data-root DIR]
                 [--no-build] [--no-menu] [--force] [--dry-run] [--system NAME]
  install_app.py --list [--dest DIR]
  gameframe install [...]      the same, from GameFrame or a project's ./gameframe; with no
                               arguments it installs the vanilla build

  vanilla     (the default) the game with the frame only. The frame's own switches turn the
              window off and on again (--no-frame, --frame), and the build's --vanilla switch,
              if it has one, still applies
  extra       both builds: vanilla, then the extra build, with the additions turned on (hooks,
              capture, input, renderers, mods), installed as "NAME Extra" beside it
  --project   the project with install.json (default: $GAMEFRAME_PROJECT, else this folder)
  --dest      the GameFrame folder for the programs (default: see Where)
  --data-root the GameFrame folder for the data (default: see Where)
  --no-build  install what the last build left, without running the build commands. After
              `extra` that is the extra build's programs, so build vanilla again first
  --no-menu   no Start menu shortcut or desktop menu entry (Windows, Linux)
  --force     replace a folder of the same name that this command did not install
  --dry-run   print the commands and the places, and change nothing
  --system    macos, windows or linux: the kind of install to write (default: this system's)
  --list      the builds installed in the GameFrame folder

install.json, at the project's root. Keys at the top apply to both builds; "vanilla" and
"extra" add to them, and "extra" starts from "vanilla":

  {"name": "Un-POD", "id": "dev.gameframe.unpod", "version": "0.1.0", "icon": "apps/icon.png",
   "vanilla": {"build": [["cargo", "build", "--release", "-p", "unpod", "-p", "pod-frame"]],
               "programs": ["target/release/unpod", "target/release/pod-frame"],
               "start": "pod-frame", "args": ["--data", "{data}"],
               "resources": ["apps/pod-frame/library.json"]},
   "extra":   {"build": [["cargo", "build", "--release", "-p", "unpod", "-p", "pod-frame",
                          "--features", "extras"]]}}

  name        the application's name; the extra build is "NAME Extra" unless it names itself
  id          a reverse-domain identifier (macOS); the extra build adds ".extra"
  build       commands run in the project's folder, in order, each a list of words
  programs    the files the build makes, copied in. On Windows ".exe" is added when the file
              without it does not exist
  start       which program starts, by file name
  args        its arguments before the player's own. {data} is the build's data folder and
              {resources} the folder that holds the resources
  resources   files and folders copied beside the programs (Contents/Resources on macOS)
  icon        a PNG or an .icns (macOS), copied in as the icon

Where (places.py): macOS /Applications/GameFrame/NAME.app, or ~/Applications/GameFrame when
/Applications is not writable; data in ~/Library/Application Support/GameFrame/NAME. Windows
%LOCALAPPDATA%\Programs\GameFrame\NAME, data in %APPDATA%\GameFrame\NAME. Linux
~/.local/share/GameFrame/NAME, data in ~/.config/GameFrame/NAME. Each folder is made when it
is missing. The program starts in its data folder, so files it keeps in the current folder
land there. A new install replaces the programs and never touches the data.

Output: the commands as they run, then one line per installed build with its place, its data
folder and any notes (a missing icon, a signature or shortcut that failed).

What it does not do: cross-compile (build each system's install on that system), sign with a
Developer ID or notarise, make an installer package (.dmg, .msi, .deb), copy the game's own
files (the player adds them in the frame's library), or uninstall: delete the folder; the data
stays.
```