Recipe reference

Every app on the menu is one YAML file. This is what may go in it — the fields, what has to be installed first, what the setup dialog asks for, and how one recipe builds on another. The recipes behind the apps that ship with Luminum are on the apps page, and copying the closest one is usually the fastest way to start.

A minimal recipe

A recipe says what to install, what to ask at setup time, and what to run. Writing one is how you put something on the menu that isn't in the catalogue. This is a complete, working app. It installs one package and runs one command:

title: Scratch Desktop
description: |
  **Scratch, installed right on the machine.** The same blocks, sprites
  and sounds as the website, with no login and no internet needed.
ageFrom: 6
tags:
  - coding
  - creativity
  - offline
dependencies:
  apt:
    - scratch3
type: gui
maximize: true
script: |
  scratch-desktop

Everything else in this page is optional detail on top of that shape: what it is called, what it needs, and what it runs.

Where recipes live

The catalogue that ships with Luminum is read-only. Your own recipes go in the shared apps folder, one folder each:

/home/luminum/apps/<name>/recipe.yaml

The folder name is the app's internal name; the title in the file is what appears on the menu. An app added this way is on the menu as soon as the file is there, but is not installed yet — the first time it is chosen, Luminum asks for the admin password and installs it before running. Writing your own walks through it.

Properties

Path variables

Two variables are expanded inside path fields, config file contents and the launch script's environment:

Two more are set for you at launch time: $RESOLUTION (the screen size, as 1920,1080, for GUI apps) and $FILEPATH (the file that was picked, inside a file-browser launcher). Any other $VAR is left alone for the shell to deal with.

Description, age and tags

These three fields are what the admin reads in the catalogue before installing, so they are worth writing carefully.

description is rendered as Markdown — bold, italics, bullet lists and code all work. Write it for whoever is installing it, not for a developer: say what the app is actually used for, what it needs (an account, a connection) and how it is locked down. Avoid naming the underlying programs — "books open full screen in a distraction-free reader" is more use than "EPUBs open in Arianna". A short opening paragraph and a handful of bullets is the right length; nobody reads past a screenful.

ageFrom is a plain number of years and tags a list of short lowercase words. Both are optional and independent. Leave the age out when it depends on how the app is set up — the Website app does exactly that, since the right age depends entirely on the site you point it at.

ageFrom: 9
tags:
  - coding
  - python
  - games

Dependencies

What has to be on the machine before the app can run. Installed in the order below when the app is installed, and skipped when already present.

apt — system packages

dependencies:
  apt:
    - thonny
    - python3-pygame

git — clone a repository

path is the folder the repository is cloned into; the repository name is appended automatically. An existing clone is left alone on reinstall.

dependencies:
  git:
    url: https://github.com/raspberrypipress/Code-the-Classics-Vol1
    path: $LUMINUM_USER_HOME/code

file — download a file

For books, datasets, worksheets and other static material. Already-downloaded files are skipped. Point path at $LUMINUM_SHARED/library to make a book show up in the Library app.

dependencies:
  file:
    - url: https://example.org/peter-pan.epub
      path: $LUMINUM_SHARED/library
      rename: peter-pan.epub

venv — a private Python environment

Created after the apt and git steps, so it can live inside a repository you just cloned. The packages are reinstalled on every install, so changing the list takes effect on reinstall.

dependencies:
  venv:
    path: $LUMINUM_USER_HOME/code/Code-the-Classics-Vol1/.venv
    requirements:
      - pgzero

Variables and parameters

variables are the questions asked in the setup dialog. Each answer is available to the launch script as an environment variable of the same name.

variables:
  WEBSITE:
    type: string
    title: Website address
    description: Enter website that should be launched by browser app
    required: true

script: |
  /usr/bin/chromium --kiosk $WEBSITE

parameters are the same thing with the answer already filled in. A parameter silences the question — that is how Scratch Online is built from the generic Website app:

parent: website
title: Scratch Online
parameters:
  WEBSITE: https://scratch.mit.edu

Config files

Files written after the dependencies are installed. Use them to set an application's own preferences so nobody has to set them up by hand.

configs:
  - path: $LUMINUM_USER_HOME/.config/Thonny/configuration.ini
    mode: create
    data: |
      [view]
      FilesView.visible = True

App types

type: gui

The app is started under a bare X session with no window manager and no desktop — it is the only thing on the screen. Because there is no window manager, the usual tricks for going full screen (F11, kiosk flags, wmctrl) may do nothing; set maximize: true and Luminum will resize the first window it sees to cover the screen. Electron apps generally need this.

type: console

The script runs directly in the terminal the menu came from. Right for a Python prompt, a text editor, a text adventure. This is the default when no type is given.

title: Python Shell
dependencies:
  apt:
    - python3
type: console
script: python3

type: files

Instead of running one program, the app opens a file browser — see below.

File-browser apps

A files app shows the contents of one folder, filtered to the file types you allow, and runs a different program depending on which file is picked. This is how the Library and Downloads apps work. There is no script; there are launchers, one per extension.

type: files
path: $LUMINUM_USER_HOME/Downloads
extensions:
  - pdf
  - mp4
launchers:
  pdf:
    mode: gui
    script: /usr/bin/mupdf "$FILEPATH"
  mp4:
    mode: gui
    script: /usr/bin/vlc --fullscreen "$FILEPATH"

mode: gui runs the launcher under X, the same as a gui app, and forces it full screen unless you set maximize: false on that launcher. mode: console runs it in the terminal. $FILEPATH is the file that was picked. Picking a file does not close the browser — you come back to it when the viewer exits, and escape closes it.

Which files are listed is decided in this order: the extensions list if there is one; otherwise a variable named EXTENSIONS, so the file types can be chosen at setup time (the Downloads app does this); otherwise whatever launchers are defined. Use * to show everything. Files with no matching launcher are listed but do nothing when picked.

showFolders controls whether subfolders can be opened. It defaults to true; set it to false to keep the app to a single flat folder.

Inheritance

A recipe can build on another one with parent, naming it by filename without the extension. Child values win; dictionaries such as dependencies and parameters are merged key by key, while plain values and lists are replaced outright. Chains work — a parent can have a parent of its own.

This is the cheapest way to write your own app: take the Website recipe and fix the address.

parent: website
title: Maths Practice
parameters:
  WEBSITE: https://example.org/maths
ageFrom: 8
tags:
  - maths
  - online

Where installed files end up

Recipes never say who should own the files they create; it follows from the path:

• Anything under $LUMINUM_USER_HOME belongs to the everyday account, and is written as it.
• Anything under $LUMINUM_SHARED is owned by the system and shared: the admin account can change it, the everyday account can read it. Books and other material meant for everyone belong here.

Installing always runs from the admin account, which is the only one that can install anything at all.

Trying a recipe before publishing it

The Try button in the setup dialog installs and runs the app as you, not as the everyday account. Anything it would have written into that account's home folder goes into yours instead, and it never appears on the menu. Shared files and system packages are installed for real, since they would be either way.

Every Try reinstalls from scratch, so edits to a recipe are always picked up — which makes it the loop to work in while writing one. When it does what you want, close the dialog and press Install.

Source

Luminum is free and open source software, developed in the open at codeberg.org/Luminum. The recipes that make up the catalogue live there too — the quickest way to read a few more worked examples.