Luce packages
LuceLuce BaseLuciaOS

dymokomi/luce-pkg

Source of release 0.6.3

0.6.3 / docs / PACKAGE_PRISMA.md

# package.prisma

`package.prisma` is the one project file, read by `luc` and by both compilers. It is
ordinary Prism text, read with Prism's own decoder.

```text
#prisma 4.0
def package "luced" {
    str owner = "dymokomi"
    str version = "0.3.0"
    str kind = "application"
    str language = "luce"
    str description = "A text editor written in Luce"
    str readme = "README.md"
    str entry = "src/main.luc"
    str install = "install.luc"
    str[] public = ["editor"]

    def dependency "luce_ui" {
        str owner = "dymokomi"
        str path = "../luce-ui"
    }
    def application "bundle" {
        str name = "Luced"
        str identifier = "com.luciaos.luced"
        str icon = "assets/luced.icns"
    }
    def task "ci" {
        str description = "Everything CI runs"
        str[] depends = ["check", "unit"]
    }
    def task "unit" {
        str cmd = "luc test"
    }
}
```

## Fields

One root `def package "<name>"`. The registry coordinate is `<owner>/<name>`.

| Property | Required | Meaning |
| --- | --- | --- |
| `owner` | yes | Registry account that owns the package. |
| `version` | yes | Numeric `major.minor.patch`. A release tag `v<version>` must match it. |
| `kind` | yes | `package` (a library others import), `application` (a desktop program) or `tool` (a terminal program). A package has no `entry`; a tool has an `entry`; an application has an `entry` and an `application` element. |
| `language` | yes | `luce` or `luce-base`. |
| `source` | no | Source directory, default `src`. |
| `description` | no | One line, at most 256 bytes. Shown on the website and in search. |
| `license` | no | The package's license as an SPDX expression: `MIT`, `MIT OR Apache-2.0`, `GPL-2.0+ WITH Classpath-exception-2.0`. Shown on the package page. |
| `readme` | no | Relative path to a Markdown file rendered on the package page. |
| `entry` | for a tool or application | Relative path to the program entry. |
| `install` | no | Relative path to a post-compile install script. Only valid with `entry`. |
| `public` | for a package others import | `str[]` of the modules other packages may import, by their paths under the source root: `["ui", "widgets.button"]`. A consumer writes `from luce_ui import ui` (or `import luce_ui.ui`); a module not listed is the package's own. Sources sit directly under the source root, never under a folder repeating the package's name. |
| `development` | no | `str[]` of paths, relative to the root, that are only for developing the package: tool scripts, benchmarks, internal docs. `tests` and `dev` are development paths in every package without being listed. |

Each property is set at most once in its element; a second setting is refused as
`package.prisma:<line>:<column>: a property is set twice in one element`, as is any text
Prism cannot read, at the place it stops.

Children of the root:

- `def dependency "<name>"` — `<name>` is the dependency's package name, which is
  also the key the compiler requires. `owner` is required. Leave `version` out: the
  dependency is then the newest release, which `luc.lock` records. A project that must
  hold back gives a caret requirement (`^0.4.0`) or an exact version (`luc add
  owner/name@^0.4.0` writes one); the registry coordinate is `<owner>/<name>`.
  Optional `path` points at a local checkout that is used instead of the registry
  release, for working across repositories.
- `def application "<any-name>"`, at most one and only with `entry`: how the program
  is bundled for the desktop. `name` is the display name (letters, digits, spaces,
  `-`, `_`, `.`), `identifier` is reverse-DNS, and optional `icon` is a relative path
  (`.icns` on macOS, `.png` on Linux). `luc build` then also produces
  `build/<name>.app` on macOS, with `Info.plist`, the executable and the icon, or
  `build/<name>.AppDir` on Linux, with `AppRun`, a `.desktop` entry and the icon. A
  bundle opens as an application instead of in a terminal. `luc install` installs
  the bundle, links the command into `~/.luce/bin`, and on macOS links the bundle
  into `~/Applications`.
  A program that uses a protected resource says why, in a sentence the system shows
  the user when it first asks: `microphone`, `camera`, `photos`, `location`,
  `contacts` or `bluetooth`, each a `str` of 1 to 256 bytes on one line, such as
  `str microphone = "Luced Music records from your audio input."`. On macOS they
  become the bundle's usage descriptions (`NSMicrophoneUsageDescription`,
  `NSCameraUsageDescription`, `NSPhotoLibraryUsageDescription`,
  `NSLocationUsageDescription` with `NSLocationWhenInUseUsageDescription`,
  `NSContactsUsageDescription`, `NSBluetoothAlwaysUsageDescription`), without which
  macOS refuses the program the resource. Windows and Linux ask the user without a
  sentence from the program (Windows' privacy settings, Linux's portals), so there
  they change nothing.
- `def native "<any-name>"`, at most one: C inputs built and linked with the package,
  as `str[]` properties `sources` and `link_search` (relative paths), and `libraries`,
  `frameworks` and `pkg_config` (plain names, never options).
- `def task "<name>"` with `cmd`, optional `description` and optional
  `str[] depends`: a workflow run by `luc run <name>`.

Names match `[a-z0-9][a-z0-9_-]{0,63}`. Paths are relative, `/`-separated, and
contain no empty, `.` or `..` segment, backslash, colon or NUL. Any other element
kind or property is an error, so a typo is reported rather than ignored. The file
is at most 64 KiB with at most 128 dependencies.

## Development paths

`luc install` builds a working package or application, not a development checkout. When
it unpacks a release, for the package being installed and for every dependency, it leaves
out the development paths: `tests/` and `dev/` in every package, and whatever
`development` lists. `luc install --dev` installs the package's whole tree. A release
always contains everything, so a clone or `--dev` install can run the tests.

Keep tests, fixtures and test vectors under `tests/`. What an install builds may not be
development material: a definition is refused when its `entry`, `install` script, source
root or any public module lies in a development path.

## Install scripts

`luc install owner/name[@version]` downloads the release, checks its SHA-256,
builds it, and installs it under `~/.luce/apps/<name>/<version>/`.

An application may name an `install` script. It is high-level Luce run with

```text
luce run --sandbox <package-root> install.luc -- <os> <arch> <name> <version>
```

In the sandbox a script has no file, network or process access and cannot import
Luce Base, so it cannot install anything itself. It prints a plan, one
instruction a line, and `luc` carries it out:

```text
copy <path-in-package> -> <path-in-install-directory>
link <command-name> -> <path-in-install-directory>
```

```luce
pub func main(arguments: list[str]) -> int!:
    let name = arguments[2]
    print(f"copy build/{name} -> bin/{name}")
    print("copy themes -> share/themes")
    print(f"link {name} -> bin/{name}")
    return 0
```

`copy` takes a file or a whole directory; the built executable is
`build/<name>` and a declared application's bundle is `build/<display name>.app`
(or `.AppDir`). Paths may contain spaces; only ` -> ` separates them. Both paths must be relative with no `.` or `..` segment, a path
may be written once, and symlinks and special files are refused. `link` exposes a
copied file as `~/.luce/bin/<command-name>`. Any other line is an error. Without
a script the plan is the executable as `bin/<name>`, linked as `<name>`.

`luc list` shows installed applications. `luc uninstall <name>` removes the
application's directory and the links that point into it; it runs no package code.

## Releases and locks

A release is the source tree at a pushed tag `v<version>`. The registry publishes
it as an immutable tarball with its SHA-256. `luc.lock` records, for every package
in the resolved graph, the coordinate, exact version and that SHA-256; `luc sync`
refuses a download whose digest differs.