muon(1)

📦
version 0.5.0 · 4 versions
, in ubuntu resolute, ubuntu stonking

💖 muon — a meson-compatible build system 💖

okay bestie, sit down, we're learning muon (that's the manual page muon(1) from the General Commands Manual section, iykyk) and it's genuinely so good.

✨ NAME ✨

muon — a meson-compatible build system. that's it, that's the girl. she builds your stuff and she's compatible with meson and she eats every time. 👑

🌸 SYNOPSIS 🌸

muon [-vh] [-C <chdir>] <command> [<args>]

muon setup [-D[subproject:]option=value...] build
cd build
<invoke backend build tool>
muon test [options]
muon install [options]

look at that shape. it's giving workflow. 💅

🦋 DESCRIPTION 🦋

so here's the vibe: muon interprets source files written in the meson dsl and produces buildfiles for a backend. that's literally the whole job description. no cap.

when you're building meson projects with muon, you typically first start by running the setup command in the project root. this creates buildfiles for the backend in the build dir you specify. 🎀

then you invoke the backend, e.g.

ninja -C <build dir>

and if the project defines tests, you may run them with the test subcommand, and finally install the project with the install subcommand. chef's kiss, that's the full loop. 🌈

⭐ OPTIONS ⭐

the top-level flags, bestie, memorize them:

  • -v — enable verbose output. she's chatty, let her talk. 🗣️
  • -q — silence logging except for errors. quiet luxury. 🤫
  • -C <path> — chdir to path before executing a command. yes she'll walk there first. 🚶‍♀️
  • -h — print a help message. the classic. 🫶

👑 COMMANDS 👑

muon requires a command. like, you can't just show up with no command and expect the main character moment to happen. 🙈

all commands accept a -h option which prints a brief summary of their usage. so if you ever get lost, just -h and breathe. 💜

🔍 analyze

muon analyze [-l] [-m <mode>] [-q] [-O <path>] [-W
[no-]<diagnostic|list|error>] [command]

run a static analyzer on the current project. she's reading your code and she has opinions. 💅

OPTIONS:

  • -l — optimize output for editor linter plugins. for example, a diagnostic is added for the subdir() callsite, so that the editor can highlight subdirs with errors in them. lowkey genius. ✨
  • -m <mode> — set the language mode.
  • -q — only report errors. no side quests.
  • -O <path> — read project file with matching path from stdin. this is useful for editor linter plugins that run as you type on files that aren't saved to disk. not me saving nothing and still getting linted 😭
  • -W [no-]<diagnostic> — enable or disable a particular diagnostic, e.g. unused-variable.
  • -W list — list available diagnostics. window shopping, but for warnings. 🛍️
  • -W error — turn all warnings into errors. she's not playing around anymore. 🔥

COMMANDS:

  • trace — print a tree of all meson source files that are evaluated. 🌳
  • lsp — run the analyzer as a language server.
  • root-for <path> — given the path to a file, try to determine the project's root. detective energy. 🕵️‍♀️
  • file <path> — run the analyzer in single file mode. implies -m module, but -m script can be passed to analyze a file in script mode. this is useful for catching bugs in scripts that will be evaluated with muon internal eval, or script modules. 🐛

🎀 fmt

muon fmt [-i] [-q] [-l] [-c <muon_fmt.ini>] <file>[ <file>[...]]

format a source file. glow-up service, free of charge. 💖

OPTIONS:

  • -q — exit with 1 if files would be modified by muon fmt. the vibe check, essentially. 🫧
  • -l — like -q but also print failing filenames. so she names names. 👀
  • -i — format files in-place. yes she's editing your file. trust the process. 💅
  • -c <muon_fmt.ini> — read configuration from muon_fmt.ini.
  • -e — try to read configuration from .editorconfig. only indentation related settings are recognized. so don't get any ideas about the rest. 🙈

okay that's part 1, and there's more coming, so don't go anywhere bestie — we're not even close to done. 🧚‍♀️

✨ CONFIGURATION OPTIONS ✨

okay bestie, this is the whole vibe-tuning section 🎀 every one of these keys lives in your config, and here's the tea on each one: its type, its default, and what it actually does to your precious code. 👑

  • max_line_len — int, default 80 — the maximum length of lines before they get split. yes, she's strict. yes, she's doing it for your own good. ✂️
  • indent_style — space or tab, default space — whether you're a spaces girlie or a tabs girlie for indentation. choose your fighter. 💅
  • indent_size — int, default 4 — when indent_style = space, this is how many spaces you indent by per level. four. it's always four. 🌸
  • insert_final_newline — bool, default true — whether or not to insert a trailing newline at the end of the file. yes queen, end your files politely. 🫶
  • end_of_line — lf, crlf, or cr, default <unset> — the type of line ending to use. if this value is not set, then the line ending of the first line in the source file gets used instead. no cap, she just copies the first line's whole energy. 🦋
  • space_array — bool, default false — whether to include spaces around array elements (ex. [1] vs [ 1 ]). pick a lane and commit bestie. ✨
  • kwargs_force_multiline — bool, default false — makes every dictionary literal and function call with kwargs expand into multiple lines. she's dramatic like that, everything gets the full spread. 🔥
  • wide_colon — bool, default false — whether to put a space before the colon operator (ex. key : val). wide. colon. energy. 👑
  • no_single_comma_function — bool, default false — don't add a trailing comma to multi-line function calls with only one argument. sometimes one arg is enough, and that's valid. 😌
  • sort_files — bool, default true — whether to sort the arguments of files(). alphabetical besties stay winning. 🌈
  • group_arg_value — bool, default true — whether to group strings in array literals such that command line arguments that take a value remain on the same line as the value. the heuristic used is that if a string starts with - and the next string does not, put both strings on the same line. so -o and its lil buddy stay together, they're a package deal. 💖
  • simplify_string_literals — bool, default false — whether to automatically convert multiline string literals without newlines, as well as f-strings without formatting, into single-quoted string literals. glow-down for the better. ✨
  • indent_before_comments — str, default ' ' — the indent to put before trailing comments. one lil space of respect. 🎀
  • sticky_parens — bool, default false — controls whether parenthesis used for grouping are stuck to what they enclose, or are exploded out to be on their own lines. clingy or independent, her choice. 💜
  • continuation_indent — bool, default false — controls whether a multiline conditional in
  • …and an if statement gets an extra indent. yes bestie that's the whole rule, slay 🎀

✨ install ✨

muon install [-n]

Installs the project, fr fr. The DESTDIR environment variable is respected and will prefix all installation directories if it's present. 👑

OPTIONS:

  • -n — dry run 🙈
  • -d <destdir> — set destdir

🌸 internal 🌸

muon internal <command> [<args>]

internal holds a bunch of subcommands that muon uses on itself. Heads up though bestie: these commands are subject to change at any time and you should not rely on them. Also not all internal commands are even documented. 😭

COMMANDS:

  • eval — evaluate a source file
  • exe — execute a command
  • repl — start a meson dsl repl
  • dump_funcs — output all supported functions and arguments

💅 internal check 💅

muon internal check [-p|-d] [-m <mode>] <filename>

Checks if filename parses. vibe check but for syntax, iykyk 🦋

OPTIONS:

  • -p — print the parsed ast
  • -d — print the dissasembly
  • -m <mode> — set the compilation mode
  • -f — parse in formatting mode

✨ internal eval ✨

muon internal eval [-e] [-s] -c <command> | <filename> [<args>]

Evaluate a source file. Lowkey important: the interpreter environment here is substantially different from the typical environment you get during setup. Build related functions are unavailable, plus a bunch of other functions including subdir. And on top of that, the variable argv is defined as an array containing the commandline starting at <filename>. 📝

OPTIONS:

  • -e — lookup <filename> as an embedded script
  • -s — disable functions that are unsafe to be called at random, particularly run_command(). The motivation for this flag is so that automated fuzz testing can be used without accidentally executing something like run_command('rm', '-rf', '/'). 💀 genuinely do not skip this one
  • -c <command> — evaluate the string command rather than reading from a file

🧚 internal exe 🧚

muon internal exe [-f <input file>] [-c <output file>] [-e <env.dat>] [-a <args.dat>] [-R <file>] [-- <cmd> [<args>]]

Execute <cmd> with arguments <args>. 🫶

OPTIONS:

  • -f <input file> — pass input file as stdin to <cmd>
  • -c <output file> — capture stdout of <cmd> and write it to output file
  • -e <env.dat> — read and set environment variables from env.dat
  • -a <args.dat> — read and set command from args.dat
  • -R <file> — remove file if it exists before executing the command

🌈 internal repl 🌈

muon internal repl

Start a meson dsl repl. The functions available are limited, same energy as with internal eval. 🎀

⭐ internal summary ⭐

muon internal summary

Print a previously configured project's summary. receipts, but for your build ✨

🦋 internal dump_funcs 🦋

muon internal dump_funcs

Print all supported functions, methods, and module functions — with their arguments, argument types, and return types — to stdout. This subcommand is mainly useful for generating https://muon.build/status.html. 👑

💜 meson 💜

[muon] meson ...

A compatibility layer that attempts to translate all flags and operands from meson cli syntax to muon cli syntax. For example, the following two commands:

muon meson setup build --werror --prefix=/
muon meson test -C build --list

Would be translated into the following two muon versions respectively:

muon setup -Dwerror=true -Dprefix=/ build
muon -C build test -l

This compatibility layer is also enabled when muon's executable is named meson.

For a more detailed usage information you can use the following two commands:

muon meson -h
muon meson <subcommand> -h
NOTE: This is a best-effort translation and does not guarantee or imply full cli compatibility. Many unimplemented flags are ignored and attempting to use an unsupported subcommands will result in an error. no cap.

🎀 options 🎀

muon options [-a] [-m]

Lists available project options and defaults. This command may either be run from the project root or from a build directory. The way that it works: running this command from a build directory highlights configured option values in the output, whereas running it from the project root causes the default value for each option to be highlighted. iconic behaviour honestly 💅

OPTIONS:

  • -a — Include builtin global and per-project options in the output.
  • -m — Only display option values that have been modified.

🌸 samu 🌸

muon samu [<args>]

Executes an embedded copy of samu(1). This command requires that muon was compiled with samu enabled. 🫶

✨ setup ✨

muon setup [-D[subproject:]option=value...] [-#] <build dir>

Interpret all source files and generate buildfiles in build dir. main character energy tbh 👑

OPTIONS:

  • -D [subproject:]option=value — Set build options. Options are either built in or project-defined. Subproject options can be specified by prepending the subproject's name and a colon to the option. This option may be specified multiple times.
  • -# — Display a progress bar during setup. Can be combined with muon -q to only display a progress bar.

🦋 subprojects 🦋

muon subprojects

Run various commands over all subprojects. Only subprojects with .wrap files are supported. Most commands accept a list of projects as trailing arguments. 📦

OPTIONS:

  • -d <directory> — manually specify subprojects directory. By default muon will evaluate the current project's project() call to determine the value for subproject_dir.

COMMANDS:

  • check-wrap — check if a wrap file is valid
  • update — update subprojects with .wrap files
  • list — list subprojects with .wrap files and their status
  • clean — clean wrap-git subprojects

🔥 test 🔥

muon test [-a] [-b] [-d <display mode>] [-o <output>] [-e <setup>] [-f] [-j <jobs>] [-l] [-R] [-s <suite>] [-S] [-v [-v]] [<test> [<test>[...]]

Execute tests defined in source files. 🧪

The default is to execute all tests, but you can also specify which tests to execute on the command line.

<test> should consist of an optional project name, followed by a colon and then a test name. Either may be omitted. For example,

"test name" and ":test name" will match all tests named 'test name'
in any project.
"proj:test name" will match all tests named 'test name' in the
project 'proj'.
"proj:" will match all tests in the project 'proj'.

Additionally, the test name may be a glob expression. For example,

"proj:long*" will match all tests with names starting with 'long' in
the project 'proj'.

OPTIONS:

  • -a — include all tests from all projects
  • -b — run benchmarks instead of tests
  • -d <display mode> — Control test progress output. display mode can be one of auto, dots, or bar. dots prints a '.' for success and 'E' for error, bar prints a progress bar with an error count. The default mode, auto, selects bar if the output device is a terminal or dots otherwise.
  • -o <output mode> — Control test results output. term prints failures and output to the terminal, html generates a single-page html report, and json outputs test information to a json file.
  • -e <setup> — Use test setup setup.
  • -f — Fail fast. exit after first test failure is encountered.
  • -j — Set the number of jobs used when running tests.
  • -l — List tests that would be run with the current setup, suites, etc. The format of the output is <project name>:<list of suites> - <test_name>.
  • -R — No rebuild. Disable automatic build system invocation prior to running tests.
  • -s <suite> — Only run tests in suite suite. This option may be specified multiple times.
  • -S — print a summary of test results, including the duration of each test
  • -v — Increase verbosity. When passed once, print test results as they are completed. When passed twice, the stdout/stderr of tests is not captured.

💅 version 💅

muon version

Print out version information as well as enabled features. 🎀

🌈 EXTENSIONS 🌈

muon provides some extra functions that may be called within source files. They are documented below. 👇

  • dbg() — Begin an interactive debugger.
  • p(value) — Print any value's internal representation. For example, p('hello') prints 'hello'.

🌸 SEE ALSO 🌸

meson.build(5) meson-reference(3) meson(1)

💜 AUTHORS 💜

Maintained by Stone Tickle <lattis@mochiro.moe>, who is assisted by other open source contributors. For more information about muon development, see <https://sr.ht/~lattis/muon>. 🫶

okay bestie that's a wrap 💖 this page is muon(1), dated 2026-02-23, so go forth and build something iconic. periodt. 👑✨

📦 where this page comes from