.\" Generated by scdoc 1.11.4
.\" 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 "hare-build" "1" "2026-06-01"
.PP
.SH NAME
.PP
hare build - compile a Hare program or module
.PP
.SH SYNOPSIS
.PP
\fBhare build\fR [-hFqv]
.br
[-a \fIarch\fR]
.br
[-D \fIident[:type]=value\fR]
.br
[-j \fIjobs\fR]
.br
[-L \fIlibdir\fR]
.br
[-l \fIlibname\fR]
.br
[-N \fInamespace\fR]
.br
[-o \fIpath\fR]
.br
[-R]
.br
[-T \fItagset\fR]
.br
[-t \fItype\fR]
.br
[\fIpath\fR]
.PP
.SH DESCRIPTION
.PP
\fBhare build\fR compiles a Hare program or module.\& The \fIpath\fR argument is a path to
a Hare source file or to a directory which contains a Hare module (see
\fBhare-module\fR(5)).\& If no path is given, the Hare module contained in the current
working directory is built.\&
.PP
.SH OPTIONS
.PP
\fB-h\fR
.RS 4
Print the help text.\&
.PP
.RE
\fB-F\fR
.RS 4
Build for freestanding (non-hosted) environment.\& See \fBFREESTANDING
ENVIRONMENT\fR.\&
.PP
.RE
\fB-q\fR
.RS 4
Outside of errors, don'\&t write anything to stdout while building.\&
.PP
.RE
\fB-v\fR
.RS 4
Enable verbose logging.\& Specify twice to increase verbosity.\&
.PP
.RE
\fB-a\fR \fIarch\fR
.RS 4
Set the desired architecture for cross-compiling.\& See \fBARCHITECTURES\fR
for supported architecture names.\&
.PP
.RE
\fB-D\fR \fIident[:type]=value\fR
.RS 4
Define a constant in the type system.\& \fIident\fR is parsed as a Hare
identifier (e.\&g.\& "foo::bar::baz"), \fItype\fR as a Hare type (e.\&g.\& "str" or
"struct { x: int, y: int }"), and \fIvalue\fR as a Hare expression (e.\&g.\&
"42").\& Take care to address any necessary escaping to avoid conflicts
between your shell syntax and Hare syntax.\&
.PP
.RE
\fB-j\fR \fIjobs\fR
.RS 4
Set the maximum number of jobs to execute in parallel.\& The default is
the number of processors available on the host.\&
.PP
.RE
\fB-L\fR \fIlibdir\fR
.RS 4
Add a directory to the linker library search path.\&
.PP
.RE
\fB-l\fR \fIlibname\fR
.RS 4
Link with the named system library.\& The name is passed directly to the
linker.\& Linking with any library will also link with \fBlibc\fR(7) and add
the +libc tag to the default build tags (see \fBBUILD TAGS\fR in
\fBhare-module\fR(5)).\&
.PP
.RE
\fB-N\fR \fInamespace\fR
.RS 4
Override the namespace for the module.\&
.PP
.RE
\fB-o\fR \fIpath\fR
.RS 4
Set the output file to the given path.\& Setting the path to \fB-\fR causes
output to be written to stdout.\&
.PP
.RE
\fB-R\fR
.RS 4
Build in release mode.\& In debug mode (the default), the debug:: module
is imported as a dependency, which automatically installs a number of
runtime debugging features in your executable.\& See this module'\&s
documentation for details on these features.\&
.PP
.RE
\fB-T\fR \fItagset\fR
.RS 4
Set or unset build tags.\& See \fBBUILD TAGS\fR in \fBhare-module\fR(5).\&
.PP
.RE
\fB-t\fR \fItype\fR
.RS 4
Set the build type.\& \fItype\fR should be one of s, o, or bin, for assembly,
compiled object, or compiled binary, respectively.\& The default build
type is compiled binary.\&
.PP
.RE
.SH ARCHITECTURES
.PP
The \fB-a\fR flag is used for cross-compilation to a target architecture different
from the host architecture.\& The following architectures are currently supported:
.PP
.PD 0
.IP \(bu 4
aarch64
.IP \(bu 4
riscv64
.IP \(bu 4
x86_64
.PD
.PP
The system usually provides reasonable defaults for the \fBAR\fR, \fBAS\fR, \fBLD\fR, and
\fBCC\fR tools based on the desired target.\& However, you may wish to set these
variables yourself to control the cross toolchain in use.\&
.PP
.SH FREESTANDING ENVIRONMENT
.PP
If run with \fB-F\fR, hare build will target a freestanding environment.\& This has
the following effects:
.PP
.PD 0
.IP \(bu 4
No constraints are imposed on the signature of "main"
.IP \(bu 4
Specifying external libraries with \fB-l\fR will \fBnot\fR automatically:
.RS 4
.IP \(bu 4
Link with libc (add \fB-lc\fR manually if required)
.IP \(bu 4
Add the +libc flag (add \fB-T+libc\fR manually if required)
.IP \(bu 4
Use the C compiler for linking (use \fBLD=cc\fR if required)
.PD
.PP
.RE
.SH ENVIRONMENT
.PP
The following environment variables affect \fBhare build\fR'\&s execution:
.PP
.TS
l lx
l lx
l lx
l lx
l lx
l lx
l lx
l lx
l lx
l lx
l lx
l lx
l lx
l lx
l lx
l lx.
T{
\fBHARECACHE\fR
T}	T{
The path to the build cache.\& Defaults to \fB$XDG_CACHE_HOME/hare\fR, or \fB\(ti/.\&cache/hare\fR if \fB$XDG_CACHE_HOME\fR isn'\&t set.\&
T}
T{
\fBHAREPATH\fR
T}	T{
The list of directories to search for module dependencies in.\& See \fBhare-module\fR(5).\&
T}
T{
\fBNO_COLOR\fR
T}	T{
Disables all color output when set to a non-empty string.\&
T}
T{
\fBHAREC_COLOR\fR
T}	T{
Disables color output for \fBharec\fR when set to 0, enables it when set to any other value.\& This overrides \fBNO_COLOR\fR.\&
T}
T{
\fBHAREC\fR
T}	T{
Name of the \fBharec\fR command to use.\&
T}
T{
\fBHARECFLAGS\fR
T}	T{
Additional flags to pass to \fBharec\fR.\&
T}
T{
\fBQBE\fR
T}	T{
Name of the \fBqbe\fR command to use.\&
T}
T{
\fBQBEFLAGS\fR
T}	T{
Additional flags to pass to \fBqbe\fR.\&
T}
T{
\fBAR\fR
T}	T{
Name of the \fBar\fR(1) command to use.\&
T}
T{
\fBARFLAGS\fR
T}	T{
Additional flags to pass to \fBar\fR(1).\&
T}
T{
\fBAS\fR
T}	T{
Name of the \fBas\fR(1) command to use.\&
T}
T{
\fBASFLAGS\fR
T}	T{
Additional flags to pass to \fBas\fR(1).\&
T}
T{
\fBLD\fR
T}	T{
Name of the \fBld\fR(1) command to use.\&
T}
T{
\fBLDLINKFLAGS\fR
T}	T{
Additional flags to pass to \fBld\fR(1).\&
T}
T{
\fBCC\fR
T}	T{
Name of the \fBcc\fR(1) command to use when linking external libraries.\&
T}
T{
\fBLDFLAGS\fR
T}	T{
Additional linker flags to pass to \fBcc\fR(1).\&
T}
.TE
.sp 1
.SH SEE ALSO
.PP
\fBhare-run\fR(1), \fBhare-test\fR(1), \fBhare-module\fR(5), \fBar\fR(1), \fBas\fR(1), \fBcc\fR(1),
\fBld\fR(1)