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.