.\" Generated by scdoc  1.11.2
.\" Complete documentation for this program is not available as a GNU info page
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.nh
.ad l
.\" Begin generated content:
.TH "muon" "1" "2023-06-11"
.P
.P
.SH NAME
.P
muon - a meson-compatible build system
.P
.SH SYNOPSIS
.P
\fBmuon\fR [\fB-vh\fR] [\fB-C\fR <chdir>] <command> [<args>]
.P
\fBmuon\fR \fBsetup\fR [\fB-D\fR[subproject\fB:\fR]option\fB=\fRvalue.\&.\&.\&] build 
.br
\fBcd\fR build
.br
<invoke backend build tool>
.br
\fBmuon\fR \fBtest\fR [options] 
.br
\fBmuon\fR \fBinstall\fR [options]
.P
.SH DESCRIPTION
.P
\fBmuon\fR interprets \fIsource files\fR written in the \fImeson dsl\fR and produces
\fIbuildfiles\fR for a backend.\&  Currently the only supported backend is \fIninja\fR.\&
.P
When building \fBmeson\fR projects with \fBmuon\fR, you typically first start by
running the \fBsetup\fR command in the project root.\&  This will create \fIbuildfiles\fR
for the backend in the \fIbuild dir\fR you specify.\&  You then invoke the backend,
e.\&g.\&
.P
.nf
.RS 4
ninja -C <build dir>
.fi
.RE
.P
If the project defines tests, you may run them with the \fBtest\fR subcommand, and
finally install the project with the \fBinstall\fR subcommand.\&
.P
.SH OPTIONS
.P
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.IP \(bu 4
.\}
\fB-v\fR - enable verbose output
.RE
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.IP \(bu 4
.\}
\fB-C\fR <path> - chdir to \fIpath\fR before executing a command
.RE
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.IP \(bu 4
.\}
\fB-h\fR - print a help message

.RE
.P
.SH COMMANDS
.P
\fBmuon\fR requires a command.\&
.P
All commands accept a \fB-h\fR option which prints a brief summary of their usage.\&
.P
.SS analyze
.RS 4
\fBmuon\fR \fBanalyze\fR
.P
Run a static analyzer on the current project.\&
.P
\fBOPTIONS\fR:
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.IP \(bu 4
.\}
\fB-l\fR - 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.\&
.RE
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.IP \(bu 4
.\}
\fB-q\fR - only report errors
.RE
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.IP \(bu 4
.\}
\fB-O\fR <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.\&
.RE
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.IP \(bu 4
.\}
\fB-i\fR <path> - analyze the single file \fIpath\fR in internal mode.\&  This
is useful for catching bugs in scripts that will be evaluated with
\fBmuon internal eval\fR.\&
.RE
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.IP \(bu 4
.\}
\fB-W\fR [no-]<diagnostic> - enable or disable a particular diagnostic,

.RE
.RE
e.\&g.\& unused-variable.\&
.RS 4
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.IP \(bu 4
.\}
\fB-W\fR list - list available diagnostics.\&
.RE
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.IP \(bu 4
.\}
\fB-W\fR error - turn all warnings into errors.\&

.RE
.P
.RE
.SS benchmark
.RS 4
See documentation for the \fBtest\fR subcommand.\&
.P
.RE
.SS check
.RS 4
\fBmuon\fR \fBcheck\fR [\fB-p\fR|\fB-P\fR] <filename>
.P
Check if \fIfilename\fR parses.\&
.P
\fBOPTIONS\fR:
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.IP \(bu 4
.\}
\fB-p\fR - print the parsed ast
.RE
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.IP \(bu 4
.\}
\fB-P\fR - print the parsed formatting ast

.RE
.P
.RE
.SS fmt
.RS 4
\fBmuon\fR \fBfmt\fR [\fB-i\fR] [\fB-q\fR] [\fB-c\fR <muon_fmt.\&ini>] <file>[ <file>[.\&.\&.\&]]
.P
Format a \fIsource file\fR.\&  The formatting is currently minimally
configurable, and is based on the official meson style guide
<https://mesonbuild.\&com/Style-guide.\&html>.\&
.P
\fBOPTIONS\fR:
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.IP \(bu 4
.\}
\fB-q\fR - exit with 1 if files would be modified by muon fmt
.RE
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.IP \(bu 4
.\}
\fB-i\fR - format files in-place
.RE
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.IP \(bu 4
.\}
\fB-c\fR <muon_fmt.\&ini> - read configuration from \fImuon_fmt.\&ini\fR

.RE
.P
\fBCONFIGURATION OPTIONS\fR
.RE
.TS
allbox;l l l l
l l l l
l l l l
l l l l
l l l l
l l l l
l l l l.
T{
\fBkey\fR
T}	T{
\fBtype\fR
T}	T{
\fBdefault\fR
T}	T{
\fBdescription\fR
T}
T{
max_line_len
T}	T{
uint
T}	T{
80
T}	T{
The maximum length of lines before they are split
T}
T{
indent_by
T}	T{
str
T}	T{
\&'\&    '\&
T}	T{
A string that will be used to indent with
T}
T{
space_array
T}	T{
bool
T}	T{
false
T}	T{
Whether to include spaces around array elements (ex.\& [1] vs [ 1 ])
T}
T{
kwargs_force_multiline
T}	T{
bool
T}	T{
false
T}	T{
Make every dictionary literal and function call with kwargs expand into multiple lines.\&
T}
T{
wide_colon
T}	T{
bool
T}	T{
false
T}	T{
Whether to put a space before the colon operator (ex.\& `key : val`)
T}
T{
no_single_comma_function
T}	T{
bool
T}	T{
false
T}	T{
Don'\&t add a trailing comma to multi-line function calls with only one argument.\&
T}
.TE
.sp 1
.SS install
.RS 4
\fBmuon\fR \fBinstall\fR [\fB-n\fR]
.P
Installs the project.\& The \fIDESTDIR\fR environment variable is respected
and will prefix all installation directories if it is present.\&
.P
\fBOPTIONS\fR:
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.IP \(bu 4
.\}
\fB-n\fR - dry run

.RE
.P
.RE
.SS internal
.RS 4
\fBmuon\fR \fBinternal\fR <command> [<args>]
.P
Internal contains several subcommands used by \fBmuon\fR internally.\&  These
commands are subject to change at any time and this should not be
relied upon.\&
.P
\fBSUBCOMMANDS\fR:
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.IP \(bu 4
.\}
\fBeval\fR - evaluate a \fIsource file\fR
.RE
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.IP \(bu 4
.\}
\fBexe\fR - execute a command
.RE
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.IP \(bu 4
.\}
\fBrepl\fR - start a \fImeson dsl\fR repl
.RE
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.IP \(bu 4
.\}
\fBdump_funcs\fR - output all supported functions and arguments

.RE
.P
.RE
.SS internal eval
.RS 4
\fBmuon\fR \fBinternal\fR \fBeval\fR [\fB-e\fR] [\fB-s\fR] <filename> [<args>]
.P
Interpret a \fIsource file\fR.\&  The interpreter environment is
substantially different from the typical environment during \fBsetup\fR.\&
Build related functions are unavailable, as well as many other
functions including \fBsubdir\fR.\&  Additionally, the variable \fBargv\fR is
defined as an array containing the commandline starting at <filename>.\&
.P
\fBOPTIONS\fR:
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.IP \(bu 4
.\}
\fB-e\fR - lookup <filename> as an embedded script
.RE
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.IP \(bu 4
.\}
\fB-s\fR - disable functions that are unsafe to be called at random,

.RE
.RE
particularly `run_command()`.\&  The motivation for this flag is so that
.RS 4
automated fuzz testing can be used without accidentally executing
something like `run_command('\&rm'\&, '\&-rf'\&, '\&/'\&)`.\&
.P
.RE
.SS internal exe
.RS 4
\fBmuon\fR \fBinternal\fR \fBexe\fR [\fB-f\fR <input file>] [\fB-c\fR <output file>] [\fB-e\fR
<env.\&dat>] [\fB-a\fR <args.\&dat>] [-- <cmd> [<args>]]
.P
Execute <cmd> with arguments <args>.\&
.P
\fBOPTIONS\fR:
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.IP \(bu 4
.\}
\fB-f\fR <input file> - pass \fIinput file\fR as stdin to <cmd>
.RE
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.IP \(bu 4
.\}
\fB-c\fR <output file> - capture stdout of <cmd> and write it to \fIoutput
file\fR
.RE
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.IP \(bu 4
.\}
\fB-e\fR <env.\&dat> - read and set environment variables from \fIenv.\&dat\fR
.RE
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.IP \(bu 4
.\}
\fB-a\fR <args.\&dat> - read and set command from \fIargs.\&dat\fR

.RE
.P
.RE
.SS internal repl
.RS 4
\fBmuon\fR \fBinternal\fR \fBrepl\fR
.P
Start a \fImeson dsl\fR repl.\&  The functions available are limited as with
\fBinternal eval\fR.\&
.P
.RE
.SS internal dump_funcs
.RS 4
\fBmuon\fR \fBinternal\fR \fBdump_funcs\fR
.P
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.\&
.P
.RE
.SS meson
.RS 4
\fBmeson\fR .\&.\&.\&
.P
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:
.P
.nf
.RS 4
muon meson setup build --werror --prefix=/
muon meson test -C build --list
.fi
.RE
.P
Would be translated into the following two muon versions respectively:
.P
.nf
.RS 4
muon setup -Dwerror=true -Dprefix=/ build
muon -C build test -l
.fi
.RE
.P
This compatibility layer is also enabled when muon'\&s executable is named
\fImeson\fR.\&
.P
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.\&
.P
.RE
.SS options
.RS 4
\fBmuon\fR \fBoptions\fR [\fB-a\fR] [\fB-m\fR]
.P
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.\&
.P
\fBOPTIONS\fR:
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.IP \(bu 4
.\}
\fB-a\fR - Include builtin global and per-project options in the output.\&
.RE
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.IP \(bu 4
.\}
\fB-m\fR - Only display option values that have been modified.\&

.RE
.P
.RE
.SS samu
.RS 4
\fBmuon\fR \fBsamu\fR [<args>]
.P
Executes an embedded copy of \fBsamu\fR(1).\&  This command requires that muon
was compiled with \fBsamu\fR enabled.\&
.P
.RE
.SS setup
.RS 4
\fBmuon\fR \fBsetup\fR [\fB-D\fR[subproject\fB:\fR]option\fB=\fRvalue.\&.\&.\&] [\fB-c\fR <compiler
check cache.\&dat>] [\fB-b\fR] <build dir>
.P
Interpret all \fIsource files\fR and generate \fIbuildfiles\fR in \fIbuild dir\fR.\&
.P
\fBOPTIONS\fR:
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.IP \(bu 4
.\}
\fB-D\fR [subproject\fB:\fR]option\fB=\fRvalue - 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
\fBoption\fR.\&  This option may be specified multiple times.\&
.RE
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.IP \(bu 4
.\}
\fB-c\fR <path> - load compiler check cache dump from path.\&  This is used
internally when creating the regeneration command.\&
.RE
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.IP \(bu 4
.\}
\fB-b\fR - Break on error.\&  When this option is passed, muon will enter a
debugging repl when a fatal error is encountered.\&  From there you can
inspect and modify state, and optionally continue setup.\&

.RE
.P
.RE
.SS summary
.RS 4
\fBmuon\fR \fBsummary\fR
.P
Print a previously configured project'\&s summary.\&
.P
.RE
.SS test
.RS 4
\fBmuon\fR \fBtest\fR [\fB-d\fR <display mode>] [\fB-e\fR <setup>] [\fB-f\fR] [\fB-j\fR <jobs>]
[\fB-l\fR] [\fB-R\fR] [\fB-s\fR <suite>] [\fB-S\fR] [\fB-v [\fR-v\fB]\fR]
.P
Execute tests defined in \fIsource files\fR.\&
.P
\fBOPTIONS\fR:
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.IP \(bu 4
.\}
\fB-d\fR <display mode> - Control test output.\&  \fIdisplay mode\fR can be one
of \fBauto\fR, \fBdots\fR, or \fBbar\fR.\&  \fBdots\fR prints a '\&.\&'\& for success and '\&E'\&
for error, \fBbar\fR prints a progress bar with an error count.\&  The
default mode, \fBauto\fR, selects \fBbar\fR if the output device is a
terminal or \fBdots\fR otherwise.\&
.RE
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.IP \(bu 4
.\}
\fB-e\fR <setup> - Use test setup \fIsetup\fR.\&
.RE
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.IP \(bu 4
.\}
\fB-f\fR - Fail fast.\& exit after first test failure is encountered.\&
.RE
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.IP \(bu 4
.\}
\fB-j\fR - Set the number of jobs used when running tests.\&
.RE
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.IP \(bu 4
.\}
\fB-l\fR - 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>.\&
.RE
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.IP \(bu 4
.\}
\fB-R\fR - No rebuild.\& Disable automatic build system invocation prior to
running tests.\&
.RE
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.IP \(bu 4
.\}
\fB-s\fR <suite> - Only run tests in suite \fIsuite\fR.\&  This option may be
specified multiple times.\&
.RE
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.IP \(bu 4
.\}
\fB-S\fR - print a summary of test results, including the duration of
each test
.RE
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.IP \(bu 4
.\}
\fB-v\fR - Increase verbosity.\&  When passed once, print test results as
they are completed.\&  When passed twice, the stdout/stderr of tests is
not captured.\&

.RE
.P
.RE
.SS version
.RS 4
\fBmuon\fR \fBversion\fR
.P
Print out version information as well as enabled features.\&
.P
.RE
.SH EXTENSIONS
.P
\fBmuon\fR provides some extra functions that may be called within \fIsource files\fR.\&
They are documented below.\&
.P
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.IP \(bu 4
.\}
\fBdbg()\fR - Begin an interactive debugger.\&
.RE
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.IP \(bu 4
.\}
\fBp(value)\fR - Print any value'\&s internal representation.\&  For example,
`p('\&hello'\&)` prints `'\&hello'\&`.\&

.RE
.P
.SH SEE ALSO
.P
meson.\&build(5) meson-reference(3) meson(1)
.P
.SH AUTHORS
.P
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>.\&
