Project files (.queen)

The .queen project file - its syntax and every chunk and key - PROJ, BUILD, DEPS, SOURCES, FILES, RESOURCES and HIVE.

Every project has a .queen file in its folder. It names the project and says how to build it, what it uses, and how it is published. larva build and larva run read it, and the editor checks it, completes its keys and explains them on hover.

.queen

queen 1.0;

// A program with built-in data and files copied next to it.
chunk PROJ:
   name: Res,
   type: exe,
   version: v2.0,
   author: "Ana Pérez",
   description: "A demo, with a comma"

chunk BUILD:
   gc: refcount,
   backend: x64,
   optimization: 2,
   output: out/Res.exe

chunk SOURCES:
   exclude: drafts/**

chunk FILES:
   copy: assets/**,
   into: config

chunk RESOURCES:
   embed: data/**

Syntax

The file starts with queen 1.0;.
chunk NAME: starts a chunk. Its entries are key: value, separated by commas or line ends.
Values without quotes can be true/false, numbers (1.5, -3), versions (v1.0.42), names (exe, refcount) or text. Quotes allow commas inside a value.
A list is [a, b, c] and may span several lines.
// and /* … */ are comments when they start a line or follow a space, so https://… and Tests/*.ant are values.
Paths are relative to the .queen file's folder. In patterns, * and ? match within a folder and ** across folders.
Some keys (in DEPS, FILES, RESOURCES) can be repeated.

PROJ

The project: its name, kind and version.

Key	Values	What it is
`name`	`MyApp`	The project's name, and the name of its executable or library.
`type`	`exe`, `library`	Whether it builds a program or a library.
`version`	`v1.0`	The project's version.
`author`	`My Organization`	Who wrote it.
`description`	text	What it is. Quote it if it has commas.

BUILD

How the project is compiled. Keys left out take your machine's defaults (larva config), then larva's own. Options on the larva build command line win over them.

Key	Values	What it is
`gc`	`default`, `tracing`, `refcount`, `arena`, `manual`, `custom`	How memory is managed. See Memory.
`gc.collector`	`MyApp.Memory.Collector`	With `gc: custom`: the class of the project's own collector.
`backend`	`llvm`, `x64`, `vm`	What compiles the program: LLVM, or Larva's own x86-64 back end.
`target`	`native`, `wasm`, `windows-x64`, `linux-x64`, `linux-arm64`, `macos-x64`, `macos-arm64`	Where it runs: this machine, WebAssembly, or a platform.
`optimization`	`0` to `3`	Optimization level.
`cpu`	`generic`, `native`, `x86-64-v2`, `x86-64-v3`, `x86-64-v4`…	The processor LLVM compiles for. `native` uses everything this machine has; the program may not start on an older processor.
`stdlib`	a folder, or `none`	The standard library.
`output`	`bin/MyApp.exe`	Where the build goes. By default `bin/<name>.exe`, or `bin/<name>.dll` for a library.
`ignore`	`[tests, drafts]`	Files or folders left out of the build.
`reflection`	`none`, `layout`, `full`	How much types describe of themselves at run time. `none` keeps only enum names, and makes large programs smaller and faster to build.
`borrowcheck`	`enforce`, `warn`, `off`	The borrow checker: errors, warnings, or off (references not available).
`unsafe`	`allow`, `deny`	Whether the project's code may use `unsafe` and pointers.
`generics`	`shared`, `specialize`	Whether generic code is shared between type arguments or copied for each one.
`access.default`	`public`, `private`, `internal`, `friendly`, `inherited`, `file`	The access of declarations that do not say one.

DEPS

What the project uses. Each key can appear any number of times.

Key	Example	What it is
`package`	`Acme/Json@^1.0`	A Hive package: `Author/Name`, optionally with a version. Installed with `larva hive install`.
`proj`	`../Shared/Shared.queen`	A project compiled with this one: its `.queen` file or its folder. It must be a library.
`assembly`	`bindings/SDL3.dll`	A compiled Larva library (`.dll`, or a bare `.lva`), such as the ones `larva lib` and `larva bind` write: compiled against and linked, with no source.
`larvaobj`	`libs/Geometry.lvo`	A compiled Larva object, or a folder of them: linked, not compiled again.
`lib`	`native/zlib.dll`	A native library (`.dll`, `.so`, `.dylib`, `.wasm`) the code imports functions from. It is copied next to the build.

.queen

chunk DEPS:
   proj: ../Shapes,
   package: Antril-Organization/SDL3@^3.5,
   assembly: bindings/Zip.Bindings.dll,
   lib: native/zip.dll

SOURCES

Which source files belong to the project. By default it is every source file of an installed language under the project's folder, except the folders that have their own .queen, hidden folders, and bin and obj.

Key	Example	What it is
`include`	`../Shared/**`	More source files: a file, a folder or a pattern, also outside the project's folder.
`exclude`	`drafts/**`	Files or folders left out.
`scan`	`true`, `false`	Whether the project's folder is searched at all. With `false`, only what `include` names is compiled.

FILES

Files copied next to the build, such as configuration or assets. Paths keep their place under the project.

Key	Example	What it is
`copy`	`assets/**`	A file, folder or pattern to copy. Can be repeated.
`into`	`data`	The folder, under the build's folder, the copies go to.

With the example at the top, assets/settings.json is copied to out/config/assets/settings.json.

RESOURCES

Files built into the program itself.

Key	Example	What it is
`embed`	`images/**`	A file, folder or pattern. Each file is named by its path under the project: `images/logo.png`.

The program reads them with System.Resources:

AntrilRun

import System;

Main()
{
	Console.Write(Resources.ReadText("data/greeting.txt") ?? "missing");
	loop (str name in Resources.Names())
		Console.WriteLine(name);
}

Resources.Read(name) gives the bytes (u8[]?), Resources.ReadText(name) the text, and Resources.Has(name) whether it exists.

HIVE

How the project's packages are found, and how the project is published. See Packages with Hive.

Key	Example	What it is
`provider`	`antril.org/hive`, `https://…`, `file:../registry`	The package registry: a web address or a folder. Without it, the machine's `hive.provider` setting is used.
`package`	`Acme/Json`	The name the project is published as. By default `PROJ`'s `author` and `name`.
`license`	`MIT`	The license it is published under, as an SPDX name.
`publish`	`compiled`, `source`	Whether the package carries only compiled code (the default, and the lightest) or its sources too.
`sign`	`keys/hive.key`	The private key that signs published packages, made by `larva hive key`.
`verify`	`strict`, `hashes`	How installed packages are checked: signatures and hashes (`strict`, the default), or hashes only.
`cache`	`.hive`	Where installed packages are kept. By default the user's Hive cache.
`private`	`true`, `false`	`true`: the project is never published.