The Hare programming language
git clone https://git.torresjrjr.com/hare.git
Log | Files | Refs | README | LICENSE

commit fb85756e46157afbce8f85807e2aec01713c9c2e
parent 7d892561ea68f3494a8c5beaa89c1709eba19be2
Author: Drew DeVault <sir@cmpwn.com>
Date:   Fri, 19 Mar 2021 10:55:13 -0400

hare(1): finish man page

Mdocs/hare.scd | 82++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++---
1 file changed, 79 insertions(+), 3 deletions(-)

diff --git a/docs/hare.scd b/docs/hare.scd @@ -176,15 +176,91 @@ some information about the build parameters. # MODULES -todo +The _path_ argument to *hare build* and *hare run* are used to identify the +inputs for the build. If this path is a file, it is treated as a single Hare +source file. If it is a directory, the directory is treated as a module, and is +placed in the global namespace for the build. + +All files which end in *.ha* and *.s* are treated as inputs to the module, and +are respectively treated as Hare sources and assembly sources. A module with a +mix of assembly and Hare sources are considered *mixed* modules, and have some +special semantics. + +The list of files considered eligible may be filtered by build tags. The format +for the filename is _name_[+_tags_]._ext_, where the _name_ is user-defined, the +_ext_ is either 'ha' or 's', and a list of tags are provided after the name. A +plus symbol ('+') will cause a file to be included only if that tag is present, +and a minus symbol ('-') will cause a file to be excluded if that tag is +present. Only one file for a given _name_ will be selected for the build, and +among files with eligible tags, the one with the most tag specifiers is +selected. + +For example, if the following files are present in a directory: + + foo.ha + bar.ha + bar+linux.ha + bar+plan9.ha + baz+x86_64.s + bat-x86_64.ha + +If the build tags are +linux+x86_64, then the files which are included in the +module are foo.ha, bar+linux.ha, and bar+x86_64.s. + +Additionally, subdirectories in a module will be considered part of that module +if their name consists *only* of a tag set, e.g. "+linux" or "-x86_64". A +directory with a name *and* tag set is never considered as part of any module, +such as "example+linux". A directory with only a name (e.g. "example") is +considered a sub-module of its parent directory and must be imported separately, +so "foo::bar" refers to foo/bar/. + +# DEPENDENCY RESOLUTION + +The "use" statements in each source file which is used as an input to *hare +build* or *hare run* are scanned and used to determine the dependencies for the +program, and this process is repeated for each dependency to obtain a complete +dependency graph. + +Dependencies are searched for by examining first the current working directory, +then each component of the *HAREPATH* environment variable in order, which is a +list of paths separated by colons. The default value of the *HAREPATH* may be +found with the *hare version* command. Typically, it is set to include the path +to the standard library installed on the system, as well as a system-provided +storage location for third-party modules installed via the system package +manager. # ARCHITECTURES -todo +The *-t* flag for *hare build* is used for cross-compilation, and selects a +architecture different from the host to target. The list of supported +architectures is: + +- x86_64 +- aarch64 + +The system usually provides reasonable defaults for the *AR*, *AS*, and *LD* +tools based on the desired target. However, you may wish to set these variables +yourself to control the cross toolchain in use. +; TODO: sysroots # ENVIRONMENT -todo +The following environment variables affect *hare*'s execution: + +|[ *HARECACHE* +:< The path to the object cache. Defaults to _~/.cache/hare_. +| *HAREPATH* +: See *DEPENDENCY RESOLUTION*. +| *HAREFLAGS* +: Applies additional flags to the command line arguments. +| *HAREC* +: Name of the *harec*(1) command to use. +| *AR* +: Name of the *ar*(1) command to use. +| *AS* +: Name of the *as*(1) command to use. +| *LD* +: Name of the *ld*(1) command to use. # SEE ALSO