# A tour of Louise This tour builds a small program step by step: data and pattern matching, then effects, actors, a web page served by a supervised HTTP server, and finally a cluster of two programs whose actors talk across hosts. Each step is a complete file you can run. [The language reference](reference/language.md) has the details. **Setup:** ```sh cargo build --release -p louise -p louise_rt # the compiler and the runtime export PATH="$PWD/target/release:$PATH" ``` **Two ways to run a program:** - `louise run file.lse` interprets it. - `louise run --native file.lse` compiles it through C (needs clang 13+ or GCC 15+). It prints the same thing. ## 1. Data and functions ```louise import std/io import std/list @derive Eq Show pub type Task { Task(title: String, done: Bool, minutes: Int) } fn remaining :: tasks: List -> Int { let open = tasks |> list.filter fn t { !t.done } use acc, t <- list.fold open 0 acc + t.minutes } pub fn main :: -> () / { let tasks = [ Task("write the tour", True, 90) , Task("review it", False, 30) , Task("publish", False, 5) ] io.println "minutes left: {remaining tasks}" io.println (show (list.map tasks fn t { t.title })) } ``` A few things to notice: - `remaining` has no signature, and its parameter and result types are inferred. The editor shows them as inlay hints. Only `pub` functions must spell out their signature. - `|>` pipes a value into a call, as in Gleam: `tasks |> list.filter keep` is `list.filter tasks keep`. To put the value elsewhere than first, mark its place with `_`, as in `x |> f a _`. Without a pipe, a call with a `_` is a one-argument function: `list.map xs (add 1 _)`. Calls need no parentheses: `f x y` applies `f` to `x` and `y`, and a function applied to fewer arguments than it takes is the function of the rest (currying, ADR 0062). - `use acc, t <- list.fold xs 0` passes the rest of the block to `list.fold` as its last argument: it is `list.fold xs 0 (fn acc t { acc + t.minutes })`, as in Gleam. - `@derive` writes the `Eq` and `Show` instances. - Lists are linked lists. For indexing, `std/array` has `Array`: `array.get a i` is O(1), and `array.set` and `array.push` return a new array, changing the old one in place when nothing else refers to it. - `main`'s type ends with `/ `: it is allowed to print. - `"minutes left: {remaining tasks}"` interpolates: `{e}` is `show e`. **Records.** A constructor with named fields is a record: - **Labels:** arguments can be named, in any order: `Task(title: "publish", minutes: 5, done: False)`. - **Record update:** `Task(..t, done: True)` copies `t` with `done` changed; the fields you don't name come from `t`. - **Labelled patterns:** `Task(done: d, ..)` matches the fields it names; `..` stands for the rest. ```louise fn finish :: t: Task -> Task { Task(..t, done: True) } fn is_done :: t: Task -> Bool { match t { Task(done: d, ..) -> d } } ``` Record update needs a type with one constructor: for a type with several, `match` on it and rebuild the case you have. ## 2. Effects Effects are interfaces whose implementation the *caller* chooses. Here the planning code asks for a clock, and `main` decides what time it is: ```louise import std/io effect clock { fn now :: -> Int } effect fail { final ctl fail :: reason: String -> Never } fn deadline :: minutes: Int -> Int / { if minutes < 0 { fail "negative duration" } else { now () + minutes } } fn at_nine :: action: fn() -> a / -> a / { handle { action () } with { now -> 9 * 60 } } fn or_message :: action: fn() -> Int / -> String / { handle { show (action ()) } with { fail reason -> "error: " <> reason } } pub fn main :: -> () / { io.println (or_message fn { at_nine fn { deadline 30 } }) io.println (or_message fn { at_nine fn { deadline (-5) } }) } ``` This prints `570` and then `error: negative duration`: - **`clock`:** `now` is a `fn` operation, so the handler's clause gives its result. - **`fail`:** `final ctl` abandons the rest of the computation; the handler's clause gives the result instead. - **Tests** can run `deadline` with a different clock, which makes them deterministic. **Handlers are lexical.** `deadline`'s `now ()` goes to the handler of its caller's choosing. A library that installs its own `clock` handler internally can't intercept it. ## 3. Errors as values A function that can fail returns a `Result`: `Ok(value)`, or `Error(reason)`. The caller matches on it, and the compiler checks that both cases are handled: ```louise import std/io import std/list import std/result import std/string pub type OrderError { NotANumber(String), TooMany(Int) } fn quantity :: text: String -> Result { use n <- result.try (string.to_int (string.trim text) |> result.map_error NotANumber) if n > 10 { Error(TooMany(n)) } else { Ok(n) } } fn total :: lines: List -> Result { use quantities <- result.try (list.try_map lines quantity) Ok(list.sum quantities) } fn report :: r: Result -> String { match r { Ok(n) -> "total: " <> show n , Error(NotANumber(reason)) -> "rejected: " <> reason , Error(TooMany(n)) -> "rejected: " <> show n <> " is more than 10" } } pub fn main :: -> () / { io.println (report (total ["2", " 3", "1"])) io.println (report (total ["2", "two"])) io.println (report (total ["2", "12"])) } ``` This prints `total: 6`, then `rejected: not an integer: "two"`, then `rejected: 12 is more than 10`: - **`use n <- result.try(r)`** continues with the value of an `Ok`, and returns an `Error` as it is. The first error stops the chain. - **`result.map_error NotANumber`** wraps `string.to_int`'s message in this program's error type. A constructor is a value. - **`list.try_map lines quantity`** applies `quantity` to each line while it succeeds: `Ok` with every quantity, or the first `Error`, after which no other line is read. - **`|>`** passes the value on its left as the first argument: `r |> result.map_error f` is `result.map_error r f`. **Which to use:** - `Result` when something fails and the caller should know why; - `Option` when something may be absent without being a failure (`dict.get`); - `Bool` for a yes-or-no question; - a panic for a bug; - an effect, like `fail` above, when the caller's handler should decide what failing means. [ADR 0024](adr/0024-errors-as-values.md) has the details. ## 4. Mutable state, safely References live in a `region`. They cannot escape it, so cycles cannot leak: ```louise import std/io import std/list import std/ref import std/string fn longest :: words: List -> String { region { let best = ref.new "" { use w <- list.each words if string.length w > string.length (ref.get best) { ref.set best w } else { () } } ref.get best } } pub fn main :: -> () / { io.println (longest ["Louise", "is", "an", "effectful", "language"]) } ``` ## 5. Actors Actors share nothing and talk through typed subjects. A supervisor restarts the ones that crash: ```louise import std/io import std/process.{type proc} import std/supervisor.{Child, OneForOne} fn worker :: name: String attempts: Int -> () / { io.println (name <> " working") if attempts > 0 { panic "flaky" } else { () } } pub fn main :: -> () / { supervisor.supervise OneForOne [Child("flaky", fn { worker "flaky" 0 })] 3 io.println "all children finished" } ``` ### What can be sent: `Send` A message leaves its actor, maybe for another thread — so not everything can be sent. The compiler decides it from the type's structure alone: there is nothing to derive or implement, and it costs nothing at run time. The three things that cannot cross: - a `Ref` — it belongs to its region, in one actor (send the value it holds instead); - a `Resource` whose kind is not marked `@thread_safe` — only the actor that made it may use it; - a closure that captured one of those — which is why `spawn` takes a `send fn`, a function whose captures can be sent. Everything else goes: values, strings, lists, your own types, as long as what they hold goes. Generic code that sends says so with a bound (and an unannotated function just infers it): ```louise fn relay :: to: Subject message: m -> () / where Send { process.send to message } ``` Try to `process.send` a `ref.new 0` and the program does not compile (E0704). What a foreign function hides behind a sendable signature can still slip past the compiler, so the runtime walks every message as a backstop — a failure there panics the *sending* actor, which "let it crash" handles like any other panic. Things to try: - Make `worker` crash every time: after three restarts the supervisor gives up and crashes too. - Supervisors nest, as in OTP. ## 6. A web page `std/http` serves pages rendered on the server. HTML literals are typed expressions: ```louise import std/html.{type Html} import std/http import std/io import std/net import std/process.{type proc} fn page :: path: String -> Html {

Hello from Louise

You asked for {path}.

} pub fn main :: -> () / { match http.listen "127.0.0.1" 8080 { Ok(server) -> { io.println ("http://127.0.0.1:" <> show (net.port server)) use req <- http.serve server http.html (page req.path) } , Error(e) -> io.eprintln e } } ``` Run it with `louise run --native` (networking needs the native runtime), then open the address it prints. - Every connection is handled by its own actor. - A crashing handler loses only its own request. Markup can also be written as a **tagged template** (`std/template`), here in the pug shorthand — the holes are the same and typed by their position, a malformed template is a compile error, and editors highlight the contents by the tag: ```louise import std/template.{pug} fn page :: path: String -> Html { pug` html body h1 Hello from Louise p You asked for code {path}. ` } ``` ### Per-client limits `http.client_address req trusted` is the client's IP address: the other end of the connection, or, behind proxies you name, the client they forwarded the request for (a client's own `X-Forwarded-For` is ignored, since anyone can send one). With it, an actor can count each client's requests and refuse the excess with 429: ```louise import std/dict.{type Dict} import std/http import std/io import std/net import std/option import std/process.{type Subject, type proc} /// What the limiter is told. type Limit { /// May `client` make one more request? The answer goes to `reply`. Ask(client: String, reply: Subject) /// A new minute: every client starts again. , Reset } /// Start an actor allowing each client `per_minute` requests a minute. fn start_limiter :: per_minute: Int -> Subject / { let ready = process.subject () let _ = process.spawn fn { let limits = process.subject () process.send ready limits let _ = process.spawn fn { every_minute limits } limit limits per_minute (dict.empty ()) } process.receive_forever ready } fn every_minute :: limits: Subject -> () / { process.sleep 60000 process.send limits Reset every_minute limits } fn limit :: limits: Subject per_minute: Int counts: Dict -> () / { match process.receive_forever limits { Reset -> limit limits per_minute (dict.empty ()) , Ask(client, reply) -> { let n = dict.get counts client |> option.unwrap_or 0 process.send reply (n < per_minute) limit limits per_minute (dict.insert counts client (n + 1)) } } } pub fn main :: -> () / { match http.listen "127.0.0.1" 8080 { Ok(server) -> { io.println ("http://127.0.0.1:" <> show (net.port server)) let limits = start_limiter 60 use req <- http.serve server // Behind a proxy, name it: http.client_address(req, ["10.0.0.2"]). let client = http.client_address req [] |> option.unwrap_or "?" let reply = process.subject () process.send limits Ask(client, reply) if process.receive_forever reply { http.text 200 ("hello, " <> client) } else { http.text 429 "too many requests" } } , Error(e) -> io.eprintln e } } ``` Things to try: - `http.peer req` gives the port too; `http.wire_headers req` the headers as the client sent them, for an access log. - Count by account as well as by client, as a login form should. ### Running in a container A container stops a program by sending it SIGTERM, then SIGKILL after a grace period (`podman stop`, `docker stop`, Kubernetes). A Louise program ends at once on SIGTERM, even as the container's PID 1, where Linux would otherwise drop the signal. To finish the requests in flight first, stop the server on it: `os.signals` delivers signals as messages, and `http.serve_until` stops accepting, lets the requests in flight finish, and returns: ```louise import std/http import std/io import std/os.{Term} import std/process.{type proc} pub fn main :: -> () / { match http.listen "0.0.0.0" 8080 { Ok(server) -> { // SIGTERM stops the server: requests in flight finish first. let stop = os.signals [Term] http.serve_until server (http.defaults ()) fn _ { http.text 200 "hello" } stop io.println "stopped" } , Error(e) -> io.eprintln e } } ``` Or let the runtime supervise `main`. With an `[application]` section in `louise.toml`, a crash restarts `main` (a few times a minute at most), and SIGTERM or SIGINT stops it with `Shutdown`: ```toml [application] restart = "transient" shutdown_timeout_ms = 10000 ``` ```louise import std/http import std/io import std/process.{type proc} pub fn main :: -> () / { match http.listen "0.0.0.0" 8080 { Ok(server) -> { // Under `[application]`, a signal stops `main` with `Shutdown`: // trapping exits, it drains, then returns. process.trap_exits True http.serve_until server (http.defaults ()) fn _ { http.text 200 "hello" } (process.exits ()) io.println "stopped" } , Error(e) -> io.eprintln e } } ``` Things to try: - `podman run --rm` the program, then `podman stop` it during a slow request: the request completes, and the container stops at once after. - Nest supervisors (`supervisor.run (Spec(...))`) under `main` for its long-lived actors: on shutdown, a supervisor stops its children last-started first. ## 7. A cluster A **node** is one running native program. Nodes of a **cluster**, on one host or many, connect to each other and send messages to each other's actors as they do locally: through typed subjects, with links, monitors and `actor.call` ([ADR 0072](adr/0072-distribution.md)). This chapter's program is a package, [`examples/cluster`](../examples/cluster): one build that runs as two nodes. Node b keeps a key-value store; node a finds it, calls it, starts a worker on node b, and watches node b until it goes. The snippets are taken from it, and [its README](../examples/cluster/README.md) has the commands to run both nodes on your machine. ### What can cross: `Wire` The store is an ordinary actor (`src/kv.lse`, started with `actor.start`). Its messages are what node a sends across: ```louise /// What the store is asked. Every field can cross hosts (`Wire`): /// strings, and the subjects the answers go to, so `dist.name` accepts /// this type and `actor.call` works across nodes. pub type Request { /// Set `key` to `value`; the answer is its previous value. Put(key: String, value: String, reply: Subject>) , Get(key: String, reply: Subject>) /// How many keys the store holds. , Size(reply: Subject) } ``` A message crosses hosts only if its type is `Wire`, a stricter sibling of `Send` (chapter 5), decided by the compiler from the type's structure: - values, strings, lists, tuples, your own types, as long as what they hold crosses, and `Pid`s; - a `Subject` when `m` crosses: `reply` above is node a's subject, and node b's answer comes back on it; - never a function, a `Ref`, a `Resource` (even `@thread_safe`) or a `Dynamic`. A field that cannot cross is a compile error that names it. Give `Put` a callback, `on_done: send fn() -> ()`: it may be sent to a local actor, but not to another host, and `dist.name "store"` no longer compiles: ```text [E0706] Error: `Request` cannot cross hosts Note: `Request` has a field `on_done` that cannot cross hosts: a function's code and what it captured exist only in this process: send the data it needs instead ``` On the wire, a value travels with its type's hash, and the receiving node decodes it with its own description of that type. Every node of a cluster must therefore be built from the same types: nodes compare a hash of the program's types (its *schema*) when they connect, and refuse a different build. ### Certificates Nodes authenticate each other with **mutual TLS**: - each node presents a certificate for its own name, from the cluster's authority, and accepts only peers whose certificate chains to that authority (never to the system's); - a node's name is a lowercase DNS name (`b.cluster.example`), and is checked against the certificate's subject names: a wildcard certificate (`*.cluster.example`) is valid for every node under it; - there is no plaintext mode and no shared cookie. `examples/cluster/make-certs.sh DIR` makes an authority and certificates for `a.cluster.example` and `b.cluster.example` with `openssl`, for trying the example. A real cluster's come from its own authority. ### Policy and identity What every node shares is the package's: `[cluster]` in `louise.toml` names the cluster, and sets its delays and limits ([the reference](reference/language.md#distributed-programs) lists them): ```toml [cluster] name = "demo" listen = "127.0.0.1:4370" heartbeat_ms = 500 node_down_after_ms = 3000 ``` What each node is comes from its environment, so one build runs as every node: | Variable | | |---|---| | `LOUISE_NODE` | This node's name. | | `LOUISE_CERT`, `LOUISE_KEY` | Its certificate chain and key (PEM files). | | `LOUISE_CA` | The cluster's authorities (PEM files, separated by commas). | | `LOUISE_CLUSTER` | The cluster's name; optional with `[cluster]`, which it may repeat but not change. | | `LOUISE_LISTEN` | `host:port` to listen on, over `[cluster]`'s `listen` (optional; port 0 picks a free one). | | `LOUISE_SEEDS` | Nodes to connect to at start, and again whenever their connection is lost: `name:port`, or `name@host:port` (optional, separated by commas). | ### Starting a node and naming an actor Node b starts, then gives its store a name the whole cluster can find: ```louise /// The store's name, the same on every node. It carries its message type: /// `whereis` refuses a subject registered for another (`WrongType`). fn store_name :: -> Name { dist.name "store" } /// Node b: start, register the store, and serve until stopped. fn store :: -> Result<(), String> / { use config <- result.try (dist.from_env ()) use port <- result.try (dist.start config |> result.map_error describe) let store = kv.start () use _ <- result.try (dist.register (store_name ()) store |> result.map_error describe) io.println "store: listening on port {port}" // The program ends when the store does: never, unless it crashes, or the // program is stopped (Ctrl-C). let Down(_, why) = process.receive_forever (process.monitor (process.owner store)) Error("the store stopped: {why}") } ``` A few things to notice: - **`dist.from_env ()`** reads the variables above into a `dist.Config`; `dist.config` makes one in code, to change with record update (`dist.Config(..c, seeds: [...])`). `dist.start` listens, connects to the seeds, and returns the port it listens on. Once per program. - **`dist.name "store"`** is a `Name`: the name and the type of the messages its subject takes. `register` gives it to a local subject until its actor exits. - **`describe`** turns a `dist.DistError` into text (`"{e:?}"`). ### Calling across nodes Node a starts the same way (its seed is node b), then finds the store with `dist.whereis`, asking again while the name is not registered yet: ```louise /// `whereis` the store on `peer`, `tries` times while it is not registered /// yet. fn find :: peer: String tries: Int -> Result, String> / { match dist.whereis (store_name ()) peer 5000 { Ok(store) -> Ok(store) , Error(NoName(_, _)) if tries > 1 -> { process.sleep 100 find peer (tries - 1) } , Error(e) -> Error(describe e) } } ``` and calls it, as it would call a local actor: ```louise /// Calls across nodes: each request carries its reply subject. fn use_store :: store: Subject -> () / { let put = actor.call store fn r { kv.Put("language", "louise", r) } 5000 io.println "put: {put:?}" let get = actor.call store fn r { kv.Get("language", r) } 5000 io.println "get: {get:?}" io.println "size: {actor.call store kv.Size 5000}" } ``` - **`whereis name node timeout`** asks `node` and waits for its answer: a `Subject`, used as a local one. Or `NoName` (nothing registered under it), `WrongType` (registered for another message type), `NotConnected` (with why the last connection failed) or `Timeout`. - **Delivery is at most once.** A message to a node that is not connected, or lost with its connection, is gone. That is why a call has a timeout, and why links and monitors matter more across nodes. - **Order is kept** per sender and receiver, exits and `Down`s included: a message sent before a crash arrives before the crash's signal. ### Links and monitors across nodes `process.link`, `monitor`, `kill` and `stop` take another node's pid (`process.owner` of a subject `whereis` gave, or a pid in a message) as they take a local one, and a supervisor can restart a child that links to a remote actor. Node a monitors the store, then waits for it to go: ```louise /// Monitor the store across nodes until it goes: its exit, or /// `noconnection` if its node is lost first. The node's `NodeDown` comes /// after its ties' `noconnection`. fn watch :: peer: String store: Subject events: Subject -> () / { let down = process.monitor (process.owner store) io.println "watching {peer}: stop it to see it go" let Down(_, why) = process.receive_forever down io.println "store: {why}" match process.receive_forever events { NodeDown(node, _) -> io.println "{node} is down" , NodeUp(node) -> io.println "{node} is up again" } } ``` - The store's exit reason crosses as it is: `Normal`, `Killed`, `Crashed(text)`, `Shutdown`. - **A lost node is `Crashed("noconnection")`** on every link and monitor across it, once: stop node b, and node a prints `store: Crashed(noconnection)`. A connection is lost when it closes, or when the node is silent for `node_down_after_ms`. - Linking to or monitoring an actor that is already gone gives `Crashed("noproc")`, as Erlang does. - There is no distributed garbage collection: an actor lives until it exits, whoever holds its pid. ### Following a node: `monitor_node` `dist.monitor_node node` returns a subject of `NodeEvent`s: the node's state now (`NodeUp`, or `NodeDown` with why), then each change. Node a uses it to wait for its seed's connection: ```louise /// Wait up to `timeout` milliseconds for `peer`'s `NodeUp`, past the /// `NodeDown`s of a node not connected yet. A failed connection is /// redialed and leaves the node down: `dist.peers` says why it failed. fn up :: peer: String events: Subject timeout: Int -> Result<(), String> / { match process.receive events timeout { Some(NodeUp(_)) -> Ok(()) , Some(NodeDown(_, _)) -> up peer events timeout , None -> { let why = match peer_of peer { Some(Peer(state: dist.Down(why), ..)) -> why, _ -> "" } Error("cannot reach {peer} within {timeout} ms: {why}") } } } ``` `watch`, above, reads the same subject at the end: after the store's `noconnection`, a `NodeDown` says node b is gone. `peer_of` finds a node in `dist.peers` (below). ### Spawning on another node: `@remote` A node runs another's code only through a **`@remote` function**: a top-level function of one argument that crosses, returning `()`, which another node may start as an actor: ```louise /// Count `job`'s words and reply. Its argument came off the wire, checked /// against `Job`'s type; its reply subject is the asking node's. @remote pub fn count :: job: Job -> () / { let words = string.split job.text " " |> list.filter fn w { w != "" } |> list.length let node = match os.env "LOUISE_NODE" { Some(n) -> n, None -> "?" } process.send job.reply Counted(words, node) } ``` Node a starts it on node b, and waits for its reply: ```louise /// Run `words.count` on `peer`: it replies on a subject of this node. fn count_on :: peer: String -> Result<(), String> / { let counted = process.subject () let job = Job("a cluster of two nodes", counted) use _ <- result.try (dist.spawn_on peer words.count job 5000 |> result.map_error describe) match process.receive counted 5000 { Some(Counted(n, node)) -> Ok(io.println "counted {n} words on {node}") , None -> Error("no count from {peer}") } } ``` - **`words.count` called is a function; its name used as a value is a `dist.Remote`**: a key, the hash of its qualified name, the same on every node. No code and no address crosses: node b looks the key up among its own `@remote` functions, checks the argument's type, decodes it, and spawns. - `spawn_on` returns the new actor's pid, not linked to the caller (`spawn_link_on` links them before the actor runs); `UnknownEntry` or `WrongType` if node b has no such function, or one of another argument type. - **`@remote` is an allowlist:** any node of the cluster may start any `@remote` function, with any argument of its type. Audit them as you would a public endpoint. ### Peers and back-pressure `dist.peers ()` lists every node this one knows: its state (`Up`, or `Down` with why), the round-trip time of the last heartbeat, the bytes queued for it, and counts of messages sent, received, unsent and dropped. Node a prints `peer: Up, 3 messages sent, 4 received`. Each peer has an outbound queue of `[cluster]`'s `outbound_queue_bytes`: a `send` to a node whose queue is full parks the sending actor (not its thread) until the queue drains, so a fast sender cannot grow its node's memory without bound. The receiving side has no such bound: a slow consumer's mailbox grows, as locally. ### Caveats - **Native only.** `louise run --native` and `louise build`; in the interpreter, `std/dist`'s functions fail with "distribution needs --native". `louise check` checks `Wire` and `@remote` either way, and code that does not call `std/dist` (the store) tests as usual (`examples/cluster/test`). - **One build per cluster**, for now: nodes built from other types refuse each other. - **Security review needed before production use.** A node the cluster's authority certified is trusted as much as local code, as in Erlang: it can send a local actor messages of another type than its subject takes (the receiving node checks that a message is well-formed, not which subject it is for), kill or stop any actor, and start any `@remote` function. The [ADR's *Trust* section](adr/0072-distribution.md#settled-while-implementing) lists what the review must cover. - A program that never calls `dist.start` links neither the transport nor its TLS: distribution costs it nothing. Things to try: - Call the store in a loop with `actor.try_call`, which returns `Error(Timeout)` rather than panicking, and restart node b: node a redials its seed, and once `monitor_node` says `NodeUp`, `whereis` finds the new store. The old subject named node b's previous run, whose pids never reach the new one. - Register a second store on node a, and have node b `whereis` it: every node is both a server and a client. ## Where next - **`examples/http_demo`:** the full v0 demo. - a supervision tree with a session-store actor; - argon2 logins through a native C dependency; - pages as pug templates, styled by a stylesheet served from disk, like every asset under `/static/` ([`std/file`](reference/language.md#the-standard-library)); - routes written against `log` and `users` effects, tested with mock handlers under `test/`, and private helpers tested next to their code (`louise test --native` runs both). - **`examples/cluster`:** chapter 7's two nodes, and [ADR 0072](adr/0072-distribution.md) for how distribution works and what stage 1 leaves for later (#404). - **Using other packages:** list them under `[dependencies]` in `louise.toml`, as a `path` or a `git` URL with a `tag`, `branch` or `rev`. The first build writes `louise.lock`; see [Dependencies](reference/language.md#dependencies). - **[The language reference](reference/language.md)** and the [design decisions](adr/README.md).