Luce packages
LuceLuce BaseLuciaOS

dymokomi/luc

The project tool for Luce and Luce Base: create, build, run and test projects, fetch dependencies, install applications and publish releases.

An application written in luce-base. Latest release 0.24.3.

Install#

luc is the tool that installs everything else, so it comes with Luce itself. On macOS or Linux:

curl -fsSL https://luce.luciaos.com/install.sh | sh && . "$HOME/.local/luce/env"

On Windows, in PowerShell: irm https://luce.luciaos.com/install.ps1 | iex. Already installed? luc update.

Documentation#

luc

The project tool for Luce and Luce Base. One command creates, builds, runs, tests and formats a project, fetches its dependencies from pkg.luciaos.com, and installs applications. It is installed with the Luce compiler.

luc new hello --tool && cd hello    # a terminal program
luc run                             # build it and run it
luc add dymokomi/luce-json          # use a package from the registry

Projects

A project is a directory with a package.prisma that says what it is:

#prisma 4.0
def package "hello" {
    str owner = "dymokomi"
    str version = "0.1.0"
    str kind = "tool"
    str language = "luce"
    str entry = "src/main.luc"
}

kind is one of three things, and it decides what luc builds and installs:

KindWhat it isMade byInstalled as
packagea library other projects addluc new <dir> --packagenot installable; used with luc add
toola program run in a terminalluc new <dir> --tool (the default)a command on your PATH
applicationa windowed desktop programluc new <dir> --applicationName.app on macOS, a desktop entry on Linux

An application's def application "bundle" element names it for the desktop (name, identifier, optional icon) and says why it uses each protected resource it reaches, in a sentence the system shows the user the first time: `str microphone = "Luced Music records from your audio input.", and likewise camera, photos, location, contacts` and bluetooth (docs/PACKAGE_PRISMA.md in luce-pkg). macOS refuses the resource to a program without one; luc writes them into the bundle's Info.plist and signs the bundle ad hoc, so the plist is sealed and macOS remembers the user's answer by the bundle identifier. Windows and Linux ask without a sentence from the program, so there they change nothing.

A package published to the registry can also say what it is for and how it may be used: str description = "..." (one line), str license = "MIT OR Apache-2.0" (an SPDX expression) and str readme = "README.md"; the registry shows them on the package's page. Each property is set once in its element: luc refuses a repeated one at its line and column.

luc init does the same as luc new in the current directory. Every project file is described in luce-pkg/docs/PACKAGE_PRISMA.md.

Building and running

CommandDoes
luc build [--release] [--diagnostic]builds into build/<name>; an application also gets build/Name.app
luc run [--release] [--diagnostic] [-- args]builds and runs the program
luc test [--diagnostic] [--jobs N]runs the test blocks of every module, imported or not, and every test program under tests/, N programs at a time
luc test --listnames the test programs and the test blocks without running them
luc check [-- args]type-checks every module, imported or not, without building: the Base ones for the host and again for each other system's target (--target), so an error only Windows sees is found on a Mac; args go to the compiler (-- -W prints warnings)
luc fmt [--check]formats the sources
luc clean [cache]removes build/, or only its cache
luc run <task>runs a named task from package.prisma, after the tasks it depends on

--diagnostic builds with the compiler's diagnostic profile (--profile diagnostic): storage the program has not written yet (---, new T[n] ---, memory.allocate, memory.frame) reads as 0xAA, and the allocators trap on a double free or a write after free, so a half-initialised value or a use after free fails the same way on every run. The build goes to build/<name>-diagnostic, beside the normal one, and is never bundled as an application. For a Luce project, luc test --diagnostic runs the tests as a built program, since the interpreter has no profile.

Testing

luc test is the one test command of every package. It runs two kinds of test, the way pytest collects both test functions and test files without being told where they are:

  • test blocks in the modules under the source root and in their test fragments (tests/<module>/TESTS). luc test hands the .luc modules to luce test --package and the .lucb modules to luce-base test --package, so a package that mixes the two runs both. Each run starts from the entry when it is in that language, and otherwise from the first module, so a library needs no module named after the package to be tested; a run that finds no test block shows nothing, and the total line counts both. A run that fails without reporting a failed test, a module that does not build or a crash, is shown as FAIL the Base test blocks: ... (or Luce) and counts as one failure in the total, as do sources that declare tests when no run reported any, rather than passing on 0 passed.
  • Test programs: every directory tests/<name>/ that holds a main.luc or main.lucb (with pub func main). It suits a check that needs a process of its own: fixtures read from disk, a server, a window or the GPU, a comparison with another tool. luc test builds each with the package's dependencies and runs it from the package root, as luc test itself runs, with LUC_TEST_DIR naming the program's own directory for the files beside it. It counts as passed when it exits 0 and, if its directory has a file named expected, when its standard output is exactly that file; one that exits 0 after printing a line skip: reason (no GPU here, say) counts as skipped. A program may import any module of the package, private ones too, as code under src/ does, and the package's dependencies; one with a package.prisma of its own is a package of its own, with dependencies only it needs, and imports the package's public modules as any dependent does. Each runs with HOME and LUC_HOME pointing at a fresh scratch directory that is removed afterwards, so no test touches your settings, libraries, crash reports or keychain, and with LUCE and LUCE_BASE naming the compilers luc test uses. luc builds each into build/luc-test/<name>/; build/tests/<name>/ is the program's own scratch space, which luc makes a directory (replacing a file left there) and otherwise leaves to the program. A directory under tests/ without a main, or with an ORDER or TESTS file, is not a program and stays as it is.

The test programs build and run in parallel, --jobs N at a time, beside the test-block runs. The default is half the processors (8 on a 16-core machine): each build is itself parallel inside the compiler, so half as many builds as processors keeps every core busy without each build waiting on the others. A build or run beside others gets LUCE_BASE_JOBS set to its share, the processors divided by the programs running at once, and the test-block runs get the same share; set LUCE_BASE_JOBS yourself and luc leaves it as it is. Whatever order the programs finish in, they are reported in the order of their names, so the output of two runs can be compared line by line.

A program that needs the machine to itself, a heavy one with time limits say, has a file named serial in its directory (what it holds is ignored). It is built with the others, and runs after everything else is through, one at a time, with nothing else running and every processor its own; it is still reported in its place by name, and luc test --list marks it (serial).

ok    parses a header
ok    rejects a bad header
2 passed
ok    tests/roundtrip
skip  tests/gpu: no Metal device
FAIL  tests/vectors
      exit status 1
      case 17: expected 3f, got 3e
total: 3 passed, 1 failed, 1 skipped (2 test blocks, 3 programs)

A failed program is shown with the end of its output. A package with no test at all, no test block and no test program, fails with "no tests found".

A task is a def task "name" { str cmd = "..." } entry, optionally with `str[] depends. luc run <task> -- a bpassesa b` through to the command.

Dependencies

CommandDoes
luc add owner/nameadds a registry package with no version (its newest release) and locks it
luc add owner/name@^1.2.0the same, held to a caret requirement (or an exact version)
luc add ../pathadds a package checked out beside this one, for working on both
luc remove nameremoves a dependency
luc lockresolves every dependency against the registry and writes luc.lock
luc sync [--offline]makes .luc/deps/ match luc.lock, downloading what is missing

luc.lock records each package's exact version and the SHA-256 of its source. A build syncs automatically, so luc add followed by luc run just works. Downloads are cached in ~/.luce/cache; with --offline nothing is fetched, and a cached package whose checksum differs from the lock is refused. Registry access needs no account.

Installing applications and tools

CommandDoes
luc install owner/name[@version]downloads, builds and installs a tool or application, without its development paths
luc install namethe same for the one registry package called name; when several owners publish that name, luc lists them and asks for owner/name
luc install owner/name --devthe same with the whole release tree: tests, dev and every declared development path
luc update [owner/]namebrings an installed tool or application to its newest version, replacing the installed one
luc listshows what is installed
luc uninstall nameremoves it, including whatever was placed for the desktop

An install builds a working program, not a development checkout. It leaves out each package's development paths, for the package itself and for every dependency: tests/, dev/, and whatever the package lists in str[] development in package.prisma. Keep tests and test data under tests/.

An application installs where the system keeps applications and opens like any other program:

SystemThe applicationFound by
macOS/Applications/Name.app (~/Applications when you cannot write to /Applications)Finder, Launchpad, Spotlight
Linux~/.local/share/luce/apps/Name.AppDira desktop entry in ~/.local/share/applications
Windows%LOCALAPPDATA%\Programs\Namea Start Menu shortcut

A tool installs under ~/.luce/apps/<name>/<version>/, which for an application only records what was placed. Either way its command is linked into ~/.luce/bin, which the Luce installer puts on your PATH. luc never replaces an application of the same name that it did not install. Installing builds from source, so luc reports each step: fetching, compiling (with a running time), and where the result went.

An application may ship an install.luc that runs in the Luce sandbox and prints extra copy and link steps; the format is in the package.prisma document above.

Configuration

VariableMeaning
LUCE_BASE, LUCEthe compilers to use instead of the ones on your PATH
LUC_APPLICATIONSwhere applications install instead of the system's place
LUC_START_MENUWindows: where the Start Menu shortcut goes
LUC_HOMEwhere installs and commands live (default ~/.luce)
LUC_CACHEthe download cache (default ~/.luce/cache)
LUC_REGISTRYanother registry, for testing (default https://pkg.luciaos.com)

luc update reinstalls the latest luce, luce-base and luc together, through the installer at luce.luciaos.com, into the release tree this luc runs from (following a link to it), so a toolchain installed somewhere else stays there; installed applications stay. The installer edits the shell's startup file (the user PATH on Windows) only for its default place, ~/.local/luce (%LOCALAPPDATA%\luce) with ~/.luce, so an update in another tree, or with LUC_HOME set elsewhere, leaves every startup file alone; its env file (<tree>/env) puts that tree's bin and LUC_HOME/bin on PATH and keeps LUC_HOME set. luc update --dry-run prints the installer's command instead of running it; a LUC_HOME other than ~/.luce is named in it, so it installs the same way from a shell that does not have it set.

License

MIT OR Apache-2.0.

Dependencies#

Versions#

0.24.3

Browse source · pack · commit 99d4eb196ef3

SHA-256 e03875699f2de8525ff27806804f5740c998fb742f32193d3ead2d451af916bf

luc 0.24.3: batch release

0.24.2

Browse source · pack · commit 52cd942d0a7d

SHA-256 96203294fe5e51b1b4784b2b0953f825320aa3e3cdb4f89935f19930df5404cb

luc 0.24.2: batch release

0.24.1

Browse source · pack · commit ad0e2822e1c0

SHA-256 f9e21b13f378183dba590ed47005a1d63294ae0ab06b992397e900a718097022

luc 0.24.1: batch release

0.24.0

Browse source · pack · commit 9ff72c9224ee

SHA-256 90088d610a8ee40706ec6f97e5a6a0c0a8a7ccd1984eef9dacebcdfe41ab89bd

luc add writes no version (name@^x.y.z holds a project back); luc test runs every module's tests; gate reports name the condition