--- name: "muon-meson" section: "1" platform: "linux" package: "muon-meson" version: "0.4.0-1" release: "Debian 13 (Trixie)" platforms: ["linux"] url: "https://new.carta.tech/muon-meson" --- # muon-meson(1) a meson-compatible build system ## NAME muon - a meson-compatible build system ## SYNOPSIS **muon** \[**-vh**\] \[**-C** \\] \ \[\\] **muon** **setup** \[**-D**\[subproject**:**\]option**=**value...\] build \ **cd** build\ \\ **muon** **test** \[options\] \ **muon** **install** \[options\] ## DESCRIPTION **muon** interprets *source files* written in the *meson dsl* and produces *buildfiles* for a backend. When building **meson** projects with **muon**, you typically first start by running the **setup** command in the project root. This will create *buildfiles* for the backend in the *build dir* you specify. You then invoke the backend, e.g. ``` ninja -C ``` If the project defines tests, you may run them with the **test** subcommand, and finally install the project with the **install** subcommand. ## OPTIONS - • **-v** - enable verbose output - • **-C** \ - chdir to *path* before executing a command - • **-h** - print a help message ## COMMANDS **muon** requires a command. All commands accept a **-h** option which prints a brief summary of their usage. ### analyze **muon** **analyze** \[command\] Run a static analyzer on the current project. **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. - • **-q** - only report errors - • **-O** \ - 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. - • **-i** \ - analyze the single file *path* in internal mode. This is useful for catching bugs in scripts that will be evaluated with **muon internal eval**. - • **-W** \[no-\]\ - enable or disable a particular diagnostic, e.g. unused-variable. - • **-W** list - list available diagnostics. - • **-W** error - turn all warnings into errors. **COMMANDS**: - • **trace** - print a tree of all meson source files that are evaluated - • **define** \ - print the location of the definition of *var* ### fmt **muon** **fmt** \[**-i**\] \[**-q**\] \[**-l**\] \[**-c** \\] \\[ \\[...\]\] Format a *source file*. **OPTIONS**: - • **-q** - exit with 1 if files would be modified by muon fmt - • **-l** - like -q but also print failing filenames - • **-i** - format files in-place - • **-c** \ - read configuration from *muon\_fmt.ini* - • **-e** - try to read configuration from .editorconfig. Only indentation related settings are recognized. **CONFIGURATION OPTIONS** | | | | | | --- | --- | --- | --- | | **key** | **type** | **default** | **description** | | max\_line\_len | int | 80 | The maximum length of lines before they are split | | indent\_style | space\|tab | space | Wether to use spaces or tabs for indentation | | indent\_size | int | 4 | For indent\_style = space, the number of spaces to indent by per level | | insert\_final\_newline | bool | true | Whether or not to insert a trailing newline at the end of the file | | end\_of\_line | lf\|crlf\|cr | \ | 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 will be used. | | space\_array | bool | false | Whether to include spaces around array elements (ex. \[1\] vs \[ 1 \]) | | kwargs\_force\_multiline | bool | false | Make every dictionary literal and function call with kwargs expand into multiple lines. | | wide\_colon | bool | false | Whether to put a space before the colon operator (ex. \`key : val\`) | | no\_single\_comma\_function | bool | false | Don't add a trailing comma to multi-line function calls with only one argument. | | sort\_files | bool | true | Whether to sort the arguments of files() | | group\_arg\_value | bool | 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 | | simplify\_string\_literals | bool | false | Whether to automatically convert multiline string literals without newlines, as well as f-strings without formatting into single-quoted string literals. | | indent\_before\_comments | str | ' ' | The indent to put before trailing comments | | sticky\_parens | bool | false | Controls whether parenthesis used for grouping are stuck to what they enclose or are exploded out to be on their own lines. | | continuation\_indent | bool | false | Controls whether a multiline conditional in an if statement gets an extra indent. | ### install **muon** **install** \[**-n**\] Installs the project. The *DESTDIR* environment variable is respected and will prefix all installation directories if it is present. **OPTIONS**: - • **-n** - dry run - • **-d** \ - set destdir ### internal **muon** **internal** \ \[\\] Internal contains several subcommands used by **muon** internally. These commands are subject to change at any time and should not be relied upon. Not all internal commands are 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**\\] \ Check if *filename* parses. **OPTIONS**: - • **-p** - print the parsed ast - • **-d** - print the dissasembly - • **-m** \ - set the compilation mode. \`f\` parses for formatting, \`x\` compiles for the extended language (e.g. user-defined functions) ### internal eval **muon** **internal** **eval** \[**-e**\] \[**-s**\] \ \[\\] Evaluate a *source file*. The interpreter environment is substantially different from the typical environment during **setup**. Build related functions are unavailable, as well as many other functions including **subdir**. Additionally, the variable **argv** is defined as an array containing the commandline starting at \. **OPTIONS**: - • **-e** - lookup \ 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', '/')\`. ### internal exe **muon** **internal** **exe** \[**-f** \\] \[**-c** \\] \[**-e** \\] \[**-a** \\] \[**-R** \\] \[-- \ \[\\]\] Execute \ with arguments \. **OPTIONS**: - • **-f** \ - pass *input file* as stdin to \ - • **-c** \ - capture stdout of \ and write it to *output* *file* - • **-e** \ - read and set environment variables from *env.dat* - • **-a** \ - read and set command from *args.dat* - • **-R** \ - remove *file* if it exists before executing the command ### internal repl **muon** **internal** **repl** Start a *meson dsl* repl. The functions available are limited as with **internal eval**. ### internal summary **muon** **internal** **summary** Print a previously configured project's summary. ### 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 -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. ### 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. 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. **OPTIONS**: - • **-a** - Include builtin global and per-project options in the output. - • **-m** - Only display option values that have been modified. ### samu **muon** **samu** \[\\] Executes an embedded copy of [**samu**(1)](/samu/1.md). This command requires that muon was compiled with **samu** enabled. ### setup **muon** **setup** \[**-D**\[subproject**:**\]option**=**value...\] \ Interpret all *source files* and generate *buildfiles* in *build dir*. **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. ### 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** \ - 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** \[**-b**\] \[**-d** \\] \[**-o** \\] \[**-e** \\] \[**-f**\] \[**-j** \\] \[**-l**\] \[**-R**\] \[**-s** \\] \[**-S**\] \[**-v \[**-v**\]**\] \[\ \[\\[...\]\] 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. \ 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**: - • **-b** - run benchmarks instead of tests - • **-d** \ - 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** \ - 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** \ - 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 \:\ - \. - • **-R** - No rebuild. Disable automatic build system invocation prior to running tests. - • **-s** \ - 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.build/5.md) [meson-reference(3)](/meson-reference/3.md) [meson(1)](/meson/1.md) ## AUTHORS Maintained by Stone Tickle \, who is assisted by other open source contributors. For more information about muon development, see \.