.\" 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-module" "5" "2026-06-01"
.PP
.SH NAME
.PP
hare-module - Hare module layout
.PP
.SH DESCRIPTION
.PP
Hare modules are represented as directories in the filesystem.\& A directory is a
valid Hare module if it contains at least one Hare source file (with the file
extension \fB.\&ha\fR), or if it contains a file named \fBREADME\fR.\&
.PP
All files which end in \fB.\&ha\fR, \fB.\&s\fR, and \fB.\&o\fR are treated as inputs to the
module, and are respectively treated as Hare sources, assembly sources, and
objects to be linked into the final binary.\&
.PP
The list of files considered eligible may be filtered by build tags (see \fBBUILD
TAGS\fR below).\& The format for the filename is \fIname\fR[\fItagset\fR].\&\fIext\fR, where the
\fIname\fR is user-defined, the \fIext\fR is either \fBha\fR, \fBs\fR, or \fBo\fR, and a tagset (see
\fBBUILD TAGS\fR) is optionally provided after the name.\& A file will only be
included if all tags included (with +) in the tagset are present, and no tags
excluded (with -) in the tagset are present.\&
.PP
Only one file for a given combination of \fIname\fR and \fIext\fR will be selected for
the build; the file selected is the one with the most tag specifiers.\& If there
are two or more such files, the build driver will error out.\&
.PP
For example, if the following files are present in a directory:
.PP
.PD 0
.IP \(bu 4
foo.\&ha
.IP \(bu 4
bar.\&ha
.IP \(bu 4
bar+linux.\&ha
.IP \(bu 4
bar+plan9.\&ha
.IP \(bu 4
baz+x86_64.\&s
.IP \(bu 4
bat-x86_64.\&ha
.PD
.PP
If the build tags are +linux+x86_64, then the files which are included in the
module are foo.\&ha, bar+linux.\&ha, and baz+x86_64.\&s.\& If the following files are
added:
.PP
.PD 0
.IP \(bu 4
meep+linux-libc.\&ha
.IP \(bu 4
meep+linux+x86_64.\&ha
.PD
.PP
then the build driver will error out, unless +libc is added to the build tags.\&
.PP
Additionally, subdirectories in a module will be considered part of that module
if their name consists only of a tagset, e.\&g.\& "+linux" or "-x86_64".\& A directory
with only a name (but without a tagset, e.\&g.\& "example") is considered a
submodule, and as such must be imported separately.\& For example, "foo::bar"
refers to foo/bar/.\& If a directory name contains both a name and a tagset, the
build driver will error out.\&
.PP
.SH DEPENDENCY RESOLUTION
.PP
The "use" directives in each Hare source file used as an input to
\fBhare-build\fR(1), \fBhare-run\fR(1), or \fBhare-test\fR(1) are scanned and used to
determine the dependencies for a program.\& This process is repeated for each
dependency to obtain a complete dependency tree.\&
.PP
Dependencies are searched for by examining first the current working directory,
then each component of the \fBHAREPATH\fR, which is a list of paths separated by
colons.\& \fBHAREPATH\fR is obtained from the environment variable of the same name.\&
If the environment variable is unset, a default value is used, which can be
viewed with the \fBhare version -v\fR command.\& Typically, it is set to include the
path to the standard library installed on the system, as well as a
system-provided location for third-party modules installed via the system
package manager.\&
.PP
\fBhare-deps\fR(1) may be used to print the dependency tree of a Hare module.\&
.PP
.SH BUILD TAGS
.PP
Build tags allow you to add constraints on what features or platforms are
enabled for your build.\& A tag is a name, consisting of characters which aren'\&t
any of '\&+'\&, '\&-'\&, or '\&.\&'\&, and a '\&+'\& or '\&-'\& prefix to signal inclusivity or
exclusivity.\&
.PP
To add or remove build tags, use the \fB-T\fR flag.\& For example, \fB-T +foo-bar\fR will
add the '\&foo'\& tag and remove the '\&bar'\& tag.\&
.PP
Some tags are enabled by default, enabling features for the host platform.\& You
can view the default tagset by running \fBhare version -v\fR.\& To remove all default
tags, use \fB-T\(ha\fR.\&
.PP
.SH SEE ALSO
.PP
\fBhare\fR(1), \fBhare-build\fR(1), \fBhare-run\fR(1), \fBhare-test\fR(1)