Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Project Manifest (j3.toml)

Every project has a j3.toml at its root. Only [package] name is required.

[package]
name = "mygame"
entry = "src/main.j3"
version = "0.1.0"
description = "A small arcade game"

[emit]
opt = 2

[link]
libs = ["SDL2"]

[dist]
build_outputs = ["zip", "deb"]
icon = "assets/icon.png"

[package]

KeyMeaningDefault
nameBinary name; build writes target/<name>required
entryFile containing mainsrc/main.j3
versionPackage version (used for .deb)0.1.0
descriptionOne line for packages and the menu entry

[emit]

KeyMeaningDefault
backendllvm or cllvm
opt0, 1, 2, 3, s, z2
incrementalReuse one object file per module at opt 0 and 1 (opt 2 and up use ThinLTO objects on Linux with lld or mold). "all" does it at every level.true
debugDebug infotrue
fastStrip bounds-check aborts, like --fastfalse
targetA target triple or a list of them; empty is the hosthost
cpuCPU for clang, such as native
clangclang executableclang
flagsExtra clang flags
KeyMeaning
libsLibraries without -l ("SDL2" links -lSDL2)
searchLibrary search directories (-L)
filesExtra object files or archives
flagsExtra linker flags, such as an rpath

[dist]

What j3c build --release packages into target/dist/. See Shipping a Game.

KeyMeaning
build_outputsAny of "zip", "deb", "apk"
includeFiles and folders to ship. Default: whichever of assets, scripts, scenes, locales exist
icon.png (square 256 or 512) or .svg
titleMenu name. Default: the name, title-cased
categories.desktop categories. Default Game;
maintainerName <email>
dependsExtra Debian packages

[dependencies]

Path dependencies: name = { path = "../dir" } (or name = "../dir"), relative to the j3.toml that declares it. If <dir> is a package (a j3.toml and a src/), use name.a.b; loads <dir>/src/a/b.j3; otherwise <dir>/a/b.j3. The file’s first line is module name.a.b;, the same rule project files follow (module <package>.a.b;), so a package’s own files work unchanged. A dep’s [package] name must equal the key and its own [dependencies] are used too. Only the modules you import (and what they import) are compiled, for your package’s target; the dep’s main, [link] and other settings are not used. Deps are compiled in, so there is nothing to ship; their assets are not located for you. Type errors point at the dep’s own file:line; manifest errors name the j3.toml line: missing folder, a cycle, a key that is j3, the package name or a module of src/, one name with two paths. Editing a dep file rebuilds what uses it.

# android/j3.toml: the phone app shares the desktop app's wire protocol
[dependencies]
jzero = { path = ".." }
use jzero.remote.proto.{ Frame, encode, decode };

[ui]

KeyMeaningDefault
dirFolder of .j3ui components; they become the module <package>.uiui
themeA global CSS file
lintfalse turns off the CSS lint in j3c checktrue

[i18n]

KeyMeaningDefault
dirFolder of <locale>.txt string tableslocales
defaultLocale shown first, and the one check compares againsten
fallbackLocale used when a key is missingen

Environment variables

VariableEffect
J3_STDLIBUse the stdlib at this path (the parent of j3/) instead of the built-in copy
J3_EDITOR_SRCBuild the editor from this source directory

Build bookkeeping lives in target/.j3c/. Deleting it only costs a full rebuild.