Every Mica compilation is described by two kinds of information, and telling them apart is the whole idea of this page.

The facts belong to the source tree itself: which files form the program, which string encoding they are written against, which libraries they consume. Move the tree to another machine and the facts travel with it — they were never about the machine.

The choices belong to one invocation: which architecture to target, which optimization tier, where the build artifacts go. The same tree builds for ARM64 at the debug tier this minute and for x86-64 fully optimized the next, and no fact changed.

Flags are the right home for choices. The project file is the home for facts.

Three lines

A mica.project sits beside the sources it describes. This is the fullest shape — a program consuming the starter repository’s Utilities library through the contract its build emits:

{
    "sources": ["Consumer.mica"],
    "contracts": ["../build/Utilities"]
}

Three kinds of entry, all optional:

  • sources — the files of the compilation, relative to the project file. A program built from several units lists them all.
  • encoding — "utf-32" (the default) or "utf-8". This is a fact, not a flag: the sources are written against one encoding — their format strings say %ls or %s accordingly — so the file that owns the sources owns the encoding.
  • contracts — the libraries this program consumes, each named by the location of the contract the compiler emitted when that library was built. Several entries mean several libraries, each imported through its own contract.

The editor reads it — that is the point

Open any source file in VS Code and the Mica language server looks for a mica.project, walking up from the file’s directory — the familiar module-file convention. No settings, no configuration. Whatever it finds governs the analysis: the companion sources are enrolled, the encoding is applied, the contracts are loaded.

The consequence is simple to state: the diagnostics in your editor are the diagnostics of your build. A program importing a library shows no false namespace not found on lines that link fine. A utf-8 source is checked under utf-8 rules while you type. Every example in the starter repository carries its project file, so this is the behavior you meet from the first git clone.

The build reads the same file

--project points the compiler at a project file or the directory holding one:

mica --compile --link --project . --build ../build/MicaCallsLinux --platform linux,arm64
Compiling source '.../MicaCallsLinux.mica' to assembly code for platform 'linux arm64 AArch64_V8 utf-8 AArch64_ELF_GNU_AAPCS64'

Look at what happened there. The command named no source files — the project supplied them. And --platform linux,arm64 named no encoding — the project’s "encoding": "utf-8" completed it, and the platform line of the compile confirms it.

The precedence rule is one sentence: explicit flags override project entries, fact by fact. Pass --source and it wins over the project’s sources; the other entries still apply. The file describes; the invocation decides.

Try it

Open examples/MicaCallsLinux/mica.project in the starter repository and change "utf-8" to "utf-16". The editor reacts first: one error diagnostic at the top of the file, carrying the message below — the language server refuses to analyze under a project it cannot honor. Now ask the compiler directly, from the example’s directory:

mica --compile --link --project . --build ../build/MicaCallsLinux --platform linux,arm64
project file mica.project: unknown encoding "utf-16" (valid: utf-32, utf-8)

A project file that cannot be honored is refused loudly, in the editor and in the build alike — the compiler never falls back to defaults you did not ask for, because building something other than what the file describes would be worse than stopping. Change it back.

When you do not need one

A single file compiled with the default encoding and no libraries needs no project file at all — examples/Hello would work without one. The file earns its place the moment any fact departs from the trivial: a second source unit, a utf-8 surface, a consumed library. The starter repository gives one to every example anyway, so the editor’s behavior is uniform across the whole learning path.

Where this is going

A file that both the build and the editor read is also the natural place for a future dependency description — that is the direction the project model is built to grow in, and the announcement article sketches it.

The project model ships with compiler release 6.12.5. Project files written earlier are inert for older compilers and become active the moment you upgrade — nothing to migrate, nothing to undo.

Next