Manifest reference
A package's package.kdl manifest names it, versions it and says what it
needs. It is written in KDL: each key is a node, its name followed by its
values, and requires holds its entries in a block.
kdl
name "@alice/ball-pit"
title "Ball Pit"
version "0.1.0"
api_version "*"
kind "app"
author "Alice"
description "Balls that bounce off the walls."
icon "assets/icon.png"
license "MIT-0"
tags "physics" "toy"
capabilities "screenshot"
What a package is, and how its name makes it yours, is in Packages and identity. The licenses a package can declare are in Package licenses, and what each permission allows is in Permissions and capabilities.
Manifest keys
Every manifest has name, version, api_version and kind; every other key may be left out. A misspelled key is an error.
| Key | Description |
|---|---|
name | The package's identity, @scope/name. The scope is the person or team that owns the package. Each part is 1 to 128 lowercase letters, digits, _ and -, starting with a letter or a digit, and _ reads as -: @alice/ball_pit and @alice/ball-pit are one package. Publishing checks the scope against your sign-in. For example, name "@alice/ball-pit". |
version | The package's version, a SemVer version such as 1.4.0. For example, version "0.1.0". |
api_version | The versions of the DatumHue Lua API the package works with, as a SemVer range such as ^0.3; * takes any. DatumHue loads the package only when its own API version is in the range. datumhue pkg new writes the range from the API version you have up to its next breaking change. For example, api_version "^0.3". |
kind | What the package is: an app is a program people run, a library holds modules other packages load with require, and an asset pack holds files and no code. Takes app, library or asset_pack. For example, kind "app". |
title | The name people see in place of name: one line of 1 to 40 characters with no control characters. Invisible formatting characters, such as zero-width spaces, count as control characters, and a title of only spaces and invisible characters counts as empty. Left out, the title is made from name: the scope dropped, _ and - read as spaces and each word capitalized, so @alice/ball-pit reads Ball Pit. For example, title "Ball Pit". |
description | A short description, shown with the package wherever it is listed. For example, description "Balls that bounce off the walls.". |
author | The person or team that made the package, shown with it. For example, author "Alice". |
icon | The path of the package's icon, an image under assets/. For example, icon "assets/icon.png". |
readme | The path of the package's README, a Markdown file under assets/. For example, readme "assets/README.md". |
screenshots | The paths of screenshots of the package, images under assets/, in the order they show. For example, screenshots "assets/shot-1.png" "assets/shot-2.png". |
tags | Keywords people find the package by. For example, tags "physics" "toy". |
content_type | What an asset pack holds, such as theme, book, dataset, template, font_pack, shader_pack or media; listings filter by it. An app that is mostly content, such as an interactive book, may set it too. It is 1 to 64 lowercase letters, digits, _ and -. Only app and asset_pack packages take it. For example, content_type "book". |
license | The license the package is offered under, as an SPDX id. Publishing a free package needs one that lets DatumHue pass the package on as it is, which LicenseRef-Proprietary does not, and CC0-1.0 does only for an asset pack. A paid package may leave it out, and is then offered under its creator's own terms. Takes 0BSD, MIT-0, CC0-1.0, LicenseRef-DatumHue-Freeware or LicenseRef-Proprietary. For example, license "MIT-0". |
monetization | Whether the package is sold. A buyer pays once for every version of it. The price is set when you list the package for sale, not here, and a paid package without a price cannot be bought. A paid app must be sealed. Left out, the package is free. Takes free or paid. For example, monetization "paid". |
sealed | Packing compiles the app's Lua, and other apps cannot read its files: one that loads the package sees its manifest, but its Package:dir is nil. The app itself still reads its own files. Sealing is not encryption: compiled code can still be taken apart. A library or asset pack always ships as source. Only app packages take it. For example, sealed #true. |
exports | The modules other packages may require from this one, as dotted names under lib/, such as shapes.circle for lib/shapes/circle.lua. Left out, they may require every module. The package's init.lua is always reachable, and its own modules always reach each other. For example, exports "shapes" "shapes.circle". |
requires | The packages this one uses, one package node each, by @scope/name; workspace=#true takes it from the workspace this package belongs to. A published dependency takes a version range instead; namespace= names the namespace it is published in when that is not yours, and publishing writes a workspace dependency's range from its version at the time. For example, requires { package "@alice/geometry" workspace=#true }. |
capabilities | The permissions the app needs to run. Before init.lua runs, DatumHue asks the app's parent for each one, and the app does not start if one is refused. An app asks for a permission it can do without while it runs, with datumhue.app.request_permission. Takes identity, screenshot, network, commerce, packages or devices. Only app packages take it. For example, capabilities "screenshot". |
service | Runs the app with no UI: its datumhue table has none of the namespaces that draw or read input, such as datumhue.ui, datumhue.draw and datumhue.scene, and it runs while it has a callback registered. It works with other apps through datumhue.messaging, and datumhue.app.is_service reports the flag. Only app packages take it. For example, service #true. |
Reference used on this page: Package:dir datumhue.app.request_permission datumhue.ui datumhue.draw datumhue.scene datumhue.messaging datumhue.app.is_service