commit acee14d7de4a42d4b5a98b0db076e749dbf59988
parent 1f0371367008289040e8f2c72d37649bd4e2ca44
Author: Sebastian <sebastian@sebsite.pw>
Date: Sun, 1 Oct 2023 00:08:30 -0400
hare.1: update and split up
Also updates haredoc(1) and hare-doc(5)
Signed-off-by: Sebastian <sebastian@sebsite.pw>
Diffstat:
10 files changed, 523 insertions(+), 389 deletions(-)
diff --git a/Makefile b/Makefile
@@ -71,18 +71,25 @@ docs/html: $(BINOUT)/haredoc
$(BINOUT)/haredoc -Fhtml $$mod > docs/html/$$path/index.html; \
done
-docs/hare.1: docs/hare.1.scd
-docs/haredoc.1: docs/haredoc.1.scd
-docs/hare-doc.5: docs/hare-doc.5.scd
-
-docs: docs/hare.1 docs/haredoc.1 docs/hare-doc.5
+docs: \
+ docs/hare.1 \
+ docs/hare-build.1 \
+ docs/hare-cache.1 \
+ docs/hare-deps.1 \
+ docs/haredoc.1 \
+ docs/hare-run.1 \
+ docs/hare-test.1 \
+ docs/hare-doc.5 \
+ docs/hare-module.5
+
+MAN1 = hare hare-build hare-cache hare-deps haredoc hare-run hare-test
+MAN5 = hare-doc hare-module
bootstrap:
@BINOUT=$(BINOUT) ./scripts/genbootstrap
clean:
- rm -rf -- '$(HARECACHE)' '$(BINOUT)' docs/hare.1 docs/haredoc.1 \
- docs/hare-doc.5 docs/html
+ rm -rf -- '$(HARECACHE)' '$(BINOUT)' docs/*.1 docs/*.5 docs/html
check: $(BINOUT)/hare
@env HAREPATH=. HAREC=$(HAREC) QBE=$(QBE) AS=$(AS) LD=$(LD) \
@@ -98,9 +105,8 @@ install-cmd:
'$(DESTDIR)$(BINDIR)' '$(DESTDIR)$(MANDIR)/man5'
install -m755 '$(BINOUT)/hare' '$(DESTDIR)$(BINDIR)/hare'
install -m755 '$(BINOUT)/haredoc' '$(DESTDIR)$(BINDIR)/haredoc'
- install -m644 docs/hare.1 '$(DESTDIR)$(MANDIR)/man1/hare.1'
- install -m644 docs/haredoc.1 '$(DESTDIR)$(MANDIR)/man1/haredoc.1'
- install -m644 docs/hare-doc.5 '$(DESTDIR)$(MANDIR)/man5/hare-doc.5'
+ for i in $(MAN1); do install -m644 docs/$$i.1 $(DESTDIR)$(MANDIR)/man1/$$i.1; done
+ for i in $(MAN5); do install -m644 docs/$$i.5 $(DESTDIR)$(MANDIR)/man5/$$i.5; done
install-mods:
rm -rf -- '$(DESTDIR)$(STDLIB)'
@@ -110,9 +116,8 @@ install-mods:
uninstall:
rm -- '$(DESTDIR)$(BINDIR)/hare'
rm -- '$(DESTDIR)$(BINDIR)/haredoc'
- rm -- '$(DESTDIR)$(MANDIR)/man1/hare.1'
- rm -- '$(DESTDIR)$(MANDIR)/man1/haredoc.1'
- rm -- '$(DESTDIR)$(MANDIR)/man5/hare-doc.5'
+ for i in $(MAN1); do rm -- $(DESTDIR)$(MANDIR)/man1/$$i.1; done
+ for i in $(MAN5); do rm -- $(DESTDIR)$(MANDIR)/man5/$$i.5; done
rm -r -- '$(DESTDIR)$(STDLIB)'
.PHONY: all $(BINOUT)/harec2 $(BINOUT)/haredoc bootstrap clean check docs \
diff --git a/docs/hare-build.1.scd b/docs/hare-build.1.scd
@@ -0,0 +1,140 @@
+hare-build(1)
+
+# NAME
+
+hare build - compile a Hare program or module
+
+# SYNOPSIS
+
+*hare build* [-hqv]++
+ [-a _arch_]++
+ [-D _ident[:type]=value_]++
+ [-F]++
+ [-j _jobs_]++
+ [-L _libdir_]++
+ [-l _libname_]++
+ [-N _namespace_]++
+ [-o _path_]++
+ [-T _tagset_]++
+ [-t _type_]++
+ [_path_]
+
+# DESCRIPTION
+
+; TODO: Decide on and document driver exit statuses
+*hare build* compiles a Hare program or module. The _path_ argument is a path to
+a Hare source file or to a directory which contains a Hare module (see
+*hare-module*(5)). If no path is given, the Hare module contained in the current
+working directory is built.
+
+# OPTIONS
+
+*-h*
+ Print the help text.
+
+*-q*
+ Outside of errors, don't write anything to stdout while building.
+
+*-v*
+ Enable verbose logging. Specify twice to increase verbosity.
+
+*-a* _arch_
+ Set the desired architecture for cross-compiling. See *ARCHITECTURES*
+ for supported architecture names.
+
+*-D* _ident[:type]=value_
+ Define a constant in the type system. _ident_ is parsed as a Hare
+ identifier (e.g. "foo::bar::baz"), _type_ as a Hare type (e.g. "str" or
+ "struct { x: int, y: int }"), and _value_ as a Hare expression (e.g.
+ "42"). Take care to address any necessary escaping to avoid conflicts
+ between your shell syntax and Hare syntax.
+
+*-F*
+ Build for freestanding (non-hosted) environment. This allows a
+ declaration whose symbol is main to take on any form.
+
+*-j* _jobs_
+ Set the maximum number of jobs to execute in parallel. The default is
+ the number of processors available on the host.
+
+*-L* _libdir_
+ Add a directory to the linker library search path.
+
+*-l* _libname_
+ Link with the named system library. The name is passed directly to the
+ linker. Linking with any library will also link with *libc*(7) and add
+ the +libc tag to the default build tags (see *BUILD TAGS* in
+ *hare-module*(5)).
+
+*-N* _namespace_
+ Override the namespace for the module.
+
+*-o* _path_
+ Set the output file to the given path. Setting the path to *-* causes
+ output to be written to stdout.
+
+*-T* _tagset_
+ Set or unset build tags. See *BUILD TAGS* in *hare-module*(5).
+
+*-t* _type_
+ Set the build type. _type_ should be one of s, o, or bin, for assembly,
+ compiled object, or compiled binary, respectively. The default build
+ type is compiled binary.
+
+# ARCHITECTURES
+
+The *-a* flag is used for cross-compilation to a target architecture different
+from the host architecture. The following architectures are currently supported:
+
+- aarch64
+- riscv64
+- x86_64
+
+The system usually provides reasonable defaults for the *AR*, *AS*, *LD*, and
+*CC* tools based on the desired target. However, you may wish to set these
+variables yourself to control the cross toolchain in use.
+
+# ENVIRONMENT
+
+The following environment variables affect *hare build*'s execution:
+
+|[ *HARECACHE*
+:< The path to the build cache. Defaults to *$XDG_CACHE_HOME/hare*, or
+ *~/.cache/hare* if *$XDG_CACHE_HOME* isn't set.
+| *HAREPATH*
+: The list of directories to search for module dependencies in. See
+ *hare-module*(5).
+| *NO_COLOR*
+: Disables all color output when set to a non-empty string.
+| *HAREC_COLOR*
+: Disables color output for *harec* when set to 0, enables it when set to any
+ other value. This overrides *NO_COLOR*.
+| *HAREC*
+: Name of the *harec* command to use.
+| *HARECFLAGS*
+: Additional flags to pass to *harec*.
+| *QBE*
+: Name of the *qbe* command to use.
+| *QBEFLAGS*
+: Additional flags to pass to *qbe*.
+| *AR*
+: Name of the *ar*(1) command to use.
+| *ARFLAGS*
+: Additional flags to pass to *ar*(1).
+| *AS*
+: Name of the *as*(1) command to use.
+| *ASFLAGS*
+: Additional flags to pass to *as*(1).
+| *LD*
+: Name of the *ld*(1) command to use.
+| *LDLINKFLAGS*
+: Additional flags to pass to *ld*(1).
+| *CC*
+: Name of the *cc*(1) command to use when linking external libraries.
+| *LDFLAGS*
+: Additional linker flags to pass to *cc*(1).
+
+# SEE ALSO
+
+*hare-run*(1), *hare-test*(1), *hare-module*(5), *ar*(1), *as*(1), *cc*(1),
+*ld*(1)
diff --git a/docs/hare-cache.1.scd b/docs/hare-cache.1.scd
@@ -0,0 +1,34 @@
+hare-cache(1)
+
+# NAME
+
+hare cache - inspect and manage the build cache
+
+# SYNOPSIS
+
+*hare cache* [-hc]
+
+# DESCRIPTION
+
+*hare cache* provides tools to manage the build cache. If no options are
+supplied, the path and disk usage of the cache are printed.
+
+# OPTIONS
+
+*-h*
+ Print the help text.
+
+*-c*
+ Clear the cache.
+
+# ENVIRONMENT
+
+The following environment variables affect *hare cache*'s execution:
+
+|[ *HARECACHE*
+:< The path to the build cache. Defaults to *$XDG_CACHE_HOME/hare*, or
+ *~/.cache/hare* if *$XDG_CACHE_HOME* isn't set.
+
+# SEE ALSO
+
+*hare-build*(1), *hare-run*(1), *hare-test*(1)
diff --git a/docs/hare-deps.1.scd b/docs/hare-deps.1.scd
@@ -0,0 +1,44 @@
+hare-deps(1)
+
+# NAME
+
+hare deps - display the dependency tree of a Hare program or module
+
+# SYNOPSIS
+
+*hare deps* [-hd] [-T _tagset_] [_path_|_module_]
+
+# DESCRIPTION
+
+*hare deps* displays the dependency tree of a Hare program or module, as per the
+algorithm described in *DEPENDENCY RESOLUTION* in *hare-module*(5). The _path_
+argument is a path to a Hare source file or a directory which contains a Hare
+module (see *hare-module*(5)). If no path is given, the Hare module contained in
+the current working directly is used.
+
+By default, the dependency tree is pretty-printed using Unicode box-drawing
+characters.
+
+# OPTIONS
+
+*-h*
+ Print the help text.
+
+*-d*
+ Print the dependency tree as a dot file for use with *graphviz*(1).
+
+*-T* _tagset_
+ Set or unset build tags. See *BUILD TAGS* in *hare-module*(5).
+
+# ENVIRONMENT
+
+The following environment variables affect *hare deps*' execution:
+
+|[ *HAREPATH*
+:< The list of directories to search for dependencies in.
+| *NO_COLOR*
+: Disables all color output when set to a non-empty string.
+
+# SEE ALSO
+
+*hare-module*(5)
diff --git a/docs/hare-doc.5.scd b/docs/hare-doc.5.scd
@@ -2,28 +2,65 @@ hare-doc(5)
# NAME
-hare-doc - hare documentation format.
+hare-doc - Hare documentation format
# DESCRIPTION
-The Hare formatting markup is a very simple markup language. Text may be written
-normally, broken into several lines to conform to the column limit. Repeated
-whitespace will be collapsed. To begin a new paragraph, insert an empty line.
+Hare documentation is written in a simple markup language. *haredoc*(1) will
+display the documentation literally, without any additional formatting. Other
+tools may format Hare documentation into other formats.
-Links to Hare symbols may be written in brackets, like this: [[os::stdout]]. A
-bulleted list can be started by opening a line with "-". To complete the list,
-insert an empty line. Code samples may be used by using more than one space
-character at the start of a line (a tab character counts as 8 spaces).
+Text may be written normally, broken into several lines to conform to the
+80-column limit. To begin a new paragraph, insert an empty line.
+
+References to other declarations and modules may be written in brackets, like
+this: [[os::stdout]].
+
+A bulleted list can be started by opening a line with "-", optionally preceded
+by a space. Each line opened like this begins a new list item. To complete the
+list, insert an empty line.
+
+Code samples may be used by starting a line with a single tab, optionally
+preceded by a space.
This markup language is extracted from Hare comments preceding exported symbols
in your source code, and from a file named "README" in your module directory, if
present.
+# EXAMPLE
+
```
// Foos the bars. See also [[foobar]].
-export fn example() int;
+//
+// If you instead want to bar the foos, use one of the functions in
+// [[bar::foo]].
+//
+// - First, the bars are obtained.
+// - They are then fooed.
+// - Finally, the result is returned.
+//
+// let x = example();
+// assert(x == 0);
+export fn example() int = 0;
```
+# NOTES
+
+It's expected that tools which parse documentation for the purpose of converting
+it into another format will perform additional processing to decouple the
+content from its original textual representation:
+
+- Line breaks within a paragraph or list item should be ignored.
+- Repeated whitespace outside of a code sample should be collapsed.
+- Multiple code samples separated by empty lines should be collapsed into one
+ code sample, so the empty lines are moved into the code sample itself.
+
+*hare::parse::doc* in the standard library handles all of this processing for
+you.
+
+Parsers are permitted (and encouraged) to error out on invalid input, such as a
+malformed or unterminated [[reference]].
+
# SEE ALSO
-*hare*(1)
+*haredoc*(1)
diff --git a/docs/hare-module.5.scd b/docs/hare-module.5.scd
@@ -0,0 +1,87 @@
+hare-module(5)
+
+# NAME
+
+hare-module - Hare module layout
+
+# DESCRIPTION
+
+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 *.ha*), or if it contains a file named *README*.
+
+All files which end in *.ha*, *.s*, and *.o* 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.
+
+The list of files considered eligible may be filtered by build tags (see *BUILD
+TAGS* below). The format for the filename is _name_[_tagset_]._ext_, where the
+_name_ is user-defined, the _ext_ is either *ha*, *s*, or *o*, and a tagset (see
+*BUILD TAGS*) 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.
+
+Only one file for a given combination of _name_ and _ext_ 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.
+
+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 baz+x86_64.s. If the following files are
+added:
+
+- meep+linux-libc.ha
+- meep+linux+x86_64.ha
+
+then the build driver will error out, unless +libc is added to the build tags.
+
+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.
+
+# DEPENDENCY RESOLUTION
+
+The "use" directives in each Hare source file used as an input to
+*hare-build*(1), *hare-run*(1), or *hare-test*(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.
+
+Dependencies are searched for by examining first the current working directory,
+then each component of the *HAREPATH*, which is a list of paths separated by
+colons. *HAREPATH* 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 *hare version -v* 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.
+
+*hare-deps*(1) may be used to print the dependency tree of a Hare module.
+
+# BUILD TAGS
+
+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.
+
+To add or remove build tags, use the *-T* flag. For example, *-T +foo-bar* will
+add the 'foo' tag and remove the 'bar' tag.
+
+Some tags are enabled by default, enabling features for the host platform. You
+can view the default tagset by running *hare version -v*. To remove all default
+tags, use *-T^*.
+
+# SEE ALSO
+
+*hare*(1), *hare-build*(1), *hare-run*(1), *hare-test*(1)
diff --git a/docs/hare-run.1.scd b/docs/hare-run.1.scd
@@ -0,0 +1,36 @@
+hare-run(1)
+
+# NAME
+
+hare run - compile and run a Hare program or module
+
+# SYNOPSIS
+
+*hare run* [-hqv]++
+ [-a _arch_]++
+ [-D _ident[:type]=value_]++
+ [-j _jobs_]++
+ [-L _libdir_]++
+ [-l _libname_]++
+ [-T _tagset_]++
+ [_path_ [_args_...]]
+
+# DESCRIPTION
+
+*hare run* compiles and runs a Hare program or module. The _path_ argument is a
+path to a Hare source file or to a directory which contains a Hare module (see
+*hare-module*(5)). If no path is given, the Hare module contained in the current
+working directory is run. The remaining _args_ are passed to the compiled
+program.
+
+# OPTIONS
+
+Refer to *hare-build*(1).
+
+# ENVIRONMENT
+
+Refer to *hare-build*(1).
+
+# SEE ALSO
+
+*hare-build*(1), *hare-test*(1), *hare-module*(5)
diff --git a/docs/hare-test.1.scd b/docs/hare-test.1.scd
@@ -0,0 +1,40 @@
+hare-test(1)
+
+# NAME
+
+hare test - compile and run tests for Hare code
+
+# SYNOPSIS
+
+*hare test* [-hqv]++
+ [-a _arch_]++
+ [-D _ident[:type]=value_]++
+ [-j _jobs_]++
+ [-L _libdir_]++
+ [-l _libname_]++
+ [-o _path_]++
+ [-T _tagset_]++
+ [_path_ [_tests_...]]
+
+# DESCRIPTION
+
+*hare test* compiles and runs tests for a Hare program or module. The +test tag
+is added to the default build tags (see *BUILD TAGS* in *hare-module*(5)). If no
+_path_ is given, all Hare modules in the current working directory are
+recursively discovered, built, and their tests made eligible for the test run.
+Otherwise, if a _path_ is given, the source file or module is built and tested.
+
+If no _tests_ are supplied, all eligible tests are run. Otherwise, each argument
+is interpreted as a *glob*(7) pattern, giving the names of the tests to run.
+
+# OPTIONS
+
+Refer to *hare-build*(1).
+
+# ENVIRONMENT
+
+Refer to *hare-build*(1).
+
+# SEE ALSO
+
+*hare-build*(1), *hare-run*(1), *hare-module*(5)
diff --git a/docs/hare.1.scd b/docs/hare.1.scd
@@ -2,358 +2,48 @@ hare(1)
# NAME
-hare - compiles, runs, and tests Hare programs
+hare - compile, run, test, and inspect Hare programs and modules
# SYNOPSIS
-*hare* build [-hqv]++
- [-a _arch_]++
- [-D _ident[:type]=value_]++
- [-j _jobs_]++
- [-L _libdir_]++
- [-l _libname_]++
- [-N _namespace_]++
- [-o _path_]++
- [-T _tagset_]++
- [-t _type_]++
- [_path_]
-
-*hare* cache [-hc]
-
-*hare* deps [-hd] [-T _tagset_] [_path_|_module_]
-
-*hare* run [-hqv]++
- [-a _arch_]++
- [-D _ident[:type]=value_]++
- [-j _jobs_]++
- [-L _libdir_]++
- [-l _libname_]++
- [-T _tagset_]++
- [_path_ [_args_...]]
-
-*hare* test [-hqv]++
- [-a _arch_]++
- [-D _ident[:type]=value_]++
- [-j _jobs_]++
- [-L _libdir_]++
- [-l _libname_]++
- [-o _path_]++
- [-T _tagset_]++
- [_path_]
+*hare* -h
*hare* version [-hv]
-# DESCRIPTION
+*hare* _command_ [_arguments_...]
-; TODO: Decide on and document driver exit statuses
-*hare build* compiles a Hare program into an executable. The _path_ argument is
-a path to a Hare source file or a directory which contains a Hare module (see
-*MODULES* below). If no path is given, the Hare module contained in the current
-working directory is built.
-
-*hare cache* displays information about the build cache.
-
-*hare deps* displays the dependency graph of a Hare program. The _path_ argument
-is equivalent in usage to *hare build*.
-
-*hare run* compiles and runs a Hare program. The _path_ argument is equivalent
-in usage to *hare build*. If provided, any additional _args_ are passed to the
-Hare program which is run. os::args[0] is set to the _path_ argument.
+# DESCRIPTION
-*hare test* compiles and runs tests for Hare code. All Hare modules in the
-current working directory are recursively discovered, built, and their tests
-made eligible for the test run. If the _tests_ argument is omitted, all tests
-are run. Otherwise, each argument is interpreted as a *glob*(7) pattern, giving
-the names of the tests that should be run. *hare test* adds the +test tag to the
-default build tags.
+*hare -h* prints help text.
*hare version* prints version information for the *hare* program. If *-v* is
-supplied, it also prints information about the build parameters. The output
-format is consistent for machine reading: the first line is always
-"hare $version". Subsequent lines give configuration values in the form of a
-name, value, and optional context, separated by tabs.
-
-# OPTIONS
-
-## hare build
-
-*-h*
- Prints the help text.
-
-*-q*
- Outside of errors, don't write anything to stdout while building.
-
-*-v*
- Enable verbose logging. Specify twice to increase verbosity.
-
-*-a* _arch_
- Set the desired architecture for cross-compiling. See *ARCHITECTURES*
- for supported architecture names.
-
-*-D* _ident[:type]=value_
- Passed to *harec*(1) to define a constant in the type system. _ident_ is
- parsed as a Hare identifier (e.g. "foo::bar::baz"), _type_ as a Hare
- type (e.g. "str" or "struct { x: int, y: int }"), and _value_ as a Hare
- expression (e.g. "42"). Take care to address any necessary escaping to
- avoid conflicts between your shell syntax and Hare syntax.
-
-*-j* _jobs_
- Defines the maximum number of jobs which *hare* will execute in
- parallel. The default is the number of processors available on the host.
-
-*-L libdir*
- Add directory to the linker library search path.
-
-*-l* _libname_
- Link with the named system library. The name is passed to
- *pkg-config --libs* (see *pkg-config*(1)) to obtain the appropriate
- linker flags.
-
-*-N* _namespace_
- Override the namespace for the module.
-
-*-o* _path_
- Set the output file to the given path.
-
-*-T* _tagset_
- Sets or unsets build tags. See *CUSTOMIZING BUILD TAGS*.
-
-*-t* _type_
- Set the build type. Should be one of s/o/bin, for assembly, compiled
- object, or compiled binary, respectively.
-
-## hare cache
-
-*-h*
- Prints the help text.
-
-*-c*
- Clears the cache.
-
-## hare deps
-
-*-h*
- Prints the help text.
-
-*-d*
- Print dependency graph as a dot file for use with *graphviz*(1).
-
-*-T* _tags_
- Sets or unsets build tags. See *CUSTOMIZING BUILD TAGS*.
-
-## hare run
-
-*-h*
- Prints the help text.
-
-*-q*
- Outside of errors, don't write anything to stdout while building.
-
-*-v*
- Enable verbose logging. Specify twice to increase verbosity.
-
-*-a* _arch_
- Set the desired architecture for cross-compiling. See *ARCHITECTURES*
- for supported architecture names.
+supplied, it also prints information about the build parameters, in an output
+format that's consistent for machine reading: the first line is always
+*hare $version*, and subsequent lines give configuration values in the form of a
+name on its own line unindenteed, followed by any number of values, each on its
+own line indented with a single tab.
-*-D* _ident[:type]=value_
- Passed to *harec*(1) to define a constant in the type system. _ident_ is
- parsed as a Hare identifier (e.g. "foo::bar::baz"), _type_ as a Hare
- type (e.g. "str" or "struct { x: int, y: int }"), and _value_ as a Hare
- expression (e.g. "42"). Take care to address any necessary escaping to
- avoid conflicts between your shell syntax and Hare syntax.
+*hare-build*(1) compiles a Hare program or module.
-*-j* _jobs_
- Defines the maximum number of jobs which *hare* will execute in
- parallel. The default is the number of processors available on the host.
+*hare-cache*(1) manages the build cache.
-*-l* _name_
- Link with the named system library. The name is passed to
- *pkg-config --libs* (see *pkg-config*(1)) to obtain the appropriate
- linker flags.
+*hare-deps*(1) displays the dependency tree of a Hare program or module.
-*-L libdir*
- Add directory to the linker library search path.
+*hare-run*(1) compiles and runs a Hare program or module.
-*-T* _tags_
- Sets or unsets build tags. See *CUSTOMIZING BUILD TAGS*.
+*hare-test*(1) compiles and runs tests for Hare code.
-## hare test
-
-*-h*
- Prints the help text.
-
-*-q*
- Outside of errors, don't write anything to stdout while building.
-
-*-v*
- Enable verbose logging. Specify twice to increase verbosity.
-
-*-a* _arch_
- Set the desired architecture for cross-compiling. See *ARCHITECTURES*
- for supported architecture names.
-
-*-D* _ident[:type]=value_
- Passed to *harec*(1) to define a constant in the type system. _ident_ is
- parsed as a Hare identifier (e.g. "foo::bar::baz"), _type_ as a Hare
- type (e.g. "str" or "struct { x: int, y: int }"), and _value_ as a Hare
- expression (e.g. "42"). Take care to address any necessary escaping to
- avoid conflicts between your shell syntax and Hare syntax.
-
-*-j* _jobs_
- Defines the maximum number of jobs which *hare* will execute in
- parallel. The default is the number of processors available on the host.
-
-*-l* _name_
- Link with the named system library. The name is passed to
- *pkg-config --libs* (see *pkg-config*(1)) to obtain the appropriate
- linker flags.
-
-*-L libdir*
- Add directory to the linker library search path.
-
-*-T* _tags_
- Adds additional build tags. See *CUSTOMIZING BUILD TAGS*.
-
-*-X* _tags_
- Unsets build tags. See *CUSTOMIZING BUILD TAGS*.
-
-## hare version
-
-*-h*
- Prints the help text.
-
-*-v*
- Show build parameters.
-
-# MODULES
-
-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*, *.s*, and *.o* 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. There must either be at least one
-Hare source or a file named 'README' in the module's root directory.
-
-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 combination of _name_ and _ext_ will be selected for
-the build, and among files with eligible tags, the one with the most tag
-specifiers is selected. If there are two or more such files, the build driver
-will error out.
-
-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 baz+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 -v* 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
-
-The *-a* 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:
-
-- aarch64
-- riscv64
-- x86_64
-
-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
-
-# CUSTOMIZING BUILD TAGS
-
-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. See *MODULES* for details on how build tags affect module input
-selection.
-
-To add or remove build tags, use the *-T* flag. For example, "-T +foo-bar" will
-add the 'foo' tag and remove the 'bar' tag.
-
-Some tags are enabled by default, enabling features for the host platform. You
-can view the default tagset by running *hare version -v*. To remove all default
-tags, use "-T^".
+# SEE ALSO
-# ENVIRONMENT
+*hare-module*(5), *haredoc*(1)
-The following environment variables affect *hare*'s execution:
+# NOTES
-|[ *HARECACHE*
-:< The path to the build cache. Defaults to _$XDG_CACHE_HOME/hare_, or
- _~/.cache/hare_ if that doesn't exist.
-| *HAREPATH*
-: See *DEPENDENCY RESOLUTION*.
-| *HAREFLAGS*
-: Applies additional flags to the command line arguments.
-| *HAREC*
-: Name of the *harec*(1) command to use.
-| *HARECFLAGS*
-: Additional flags to pass to *harec*(1).
-| *QBE*
-: Name of the *qbe*(1) command to use.
-| *QBEFLAGS*
-: Additional flags to pass to *QBE*(1).
-| *AR*
-: Name of the *ar*(1) command to use.
-| *ARFLAGS*
-: Additional flags to pass to *ar*(1).
-| *AS*
-: Name of the *as*(1) command to use.
-| *ASFLAGS*
-: Additional flags to pass to *as*(1).
-| *CC*
-: Name of the *cc*(1) command to use when linking external libraries.
-| *LDFLAGS*
-: Additional linker flags to pass to *cc*(1).
-| *LD*
-: Name of the *ld*(1) command to use.
-| *LDLINKFLAGS*
-: Additional flags to pass to *ld*(1).
-| *CC*
-: Name of the *cc*(1) command to use.
-| *LDFLAGS*
-: Additional flags to pass to *cc*(1).
+See _https://harelang.org/community/_ for information on where to ask questions,
+send patches, submit bug reports, and chat with others in the community.
-# SEE ALSO
+Documentation for the language itself can be found at
+_https://harelang.org/documentation/_.
-*harec*(1), *as*(1), *ld*(1), *cc*(1), *hare-doc*(5)
+The language specification is available at
+_https://harelang.org/specification/_.
diff --git a/docs/haredoc.1.scd b/docs/haredoc.1.scd
@@ -2,74 +2,95 @@ haredoc(1)
# NAME
-haredoc - create documentation from hare source code
+haredoc - read and format Hare documentation
# SYNOPSIS
-*haredoc* [-hat] [-F _format_] [-T _tagset_] [_identifiers_...]
+*haredoc* [-hat] [-F _format_] [-T _tagset_] [_identifier_|_path_]
# DESCRIPTION
-*haredoc* reads documentation for a set of identifiers from Hare source code,
-and optionally prepares it for viewing in various output formats. By default,
-*haredoc* will format documentation for your terminal. See *hare-doc*(5) for
-details on the format.
+*haredoc* reads documentation from a source file or module. If no identifier or
+path is supplied, documentation is read from the Hare module contained in the
+current working directory, or from the root of the standard library if the
+current working directory doesn't contain a Hare module (see *hare-module*(5)).
+
+If an identifier is supplied, it's first looked up as a declaration. If no
+suitable declaration exists, it's looked up as a module instead. The identifier
+may also include a trailing ::, in which case it will always be treated as a
+module. The identifier is resolved using the algorithm described in *DEPENDENCY
+RESOLUTION* in *hare-module*(5).
# OPTIONS
*-h*
- Prints the help text.
+ Print the help text.
*-a*
- Show undocumented members (only applies to -Fhare and -Ftty).
+ Show undocumented members.
*-F* _format_
- Select output format (one of "html", "hare", or "tty").
+ Select output format (one of "html" or "tty"). The default is "tty".
*-t*
- Disable HTML template.
-
-*-T* _tags_
- Sets or unsets build tags. See *CUSTOMIZING BUILD TAGS*.
+ Disable HTML template (only applies to *-Fhtml*).
-# TTY COLORS
+*-T* _tagset_
+ Set or unset build tags. See *BUILD TAGS* in *hare-module*(5).
-The TTY output format of *haredoc* renders colors in the terminal with ANSI
-SGR escape sequences, behaving similarly to this shell command:
+# CUSTOMIZING COLORS
- printf '\\033[0;%sm' '_seq_'
-
-These sequences can be customised with the *HAREDOC_COLORS* environment
-variable, which follows this whitespace-delimited format:
+Unless the *NO_COLOR* environment variable is set to a non-empty string, colors
+are rendered in the terminal with ANSI SGR escape sequences. These sequences can
+be customized with the *HAREDOC_COLORS* environment variable, which follows this
+whitespace-delimited format:
HAREDOC\_COLORS='_key_=_seq_ _key_=_seq_ _..._'
-where each _key_=_seq_ entry assigns a valid _seq_ SGR sequence to a _key_
-syntax category. A valid _seq_ must contain either a single underscore "\_"; or
-digits and/or semicolons ";". Here are the initial default entries.
-; TODO: what even is this wording
+Each _key=seq_ entry assigns a valid _seq_ SGR sequence to a _key_ syntax
+category. A valid _seq_ must consist only of digits and semicolons, or must be a
+single underscore "\_". Here are the initial default entries:
. normal "0"
-. comment "1"
. primary "0"
+. ident "0"
+. comment "1"
+. constant "0"
+. function "0"
+. global "0"
+. typedef "0"
+. import_alias "0"
. secondary "0"
. keyword "94"
. type "96"
. attribute "33"
. operator "1"
. punctuation "0"
-. constant "91"
-. string "91"
+. rune_string "91"
. number "95"
+. label "0"
-Any number of entries can be specified. If a _seq_ is an underscore "\_", the
-sequence specified for "normal" is used. Otherwise, if a _seq_ is invalid,
-blank, empty or absent, its corresponding default sequence is used.
+Any number of entries can be specified. If a _seq_ is an underscore "\_", then
+the sequence specified for "normal" is used, unless _key_ is "constant",
+"function", "global", or "typedef", in which case the sequence specified for
+"primary" is used. Otherwise, if a _seq_ is invalid, blank, empty, or absent,
+its corresponding default sequence is used.
For example:
- HAREDOC\_COLORS='comment=3 primary=1;4 attribute=41' haredoc -Ftty log
+ HAREDOC\_COLORS='comment=3 primary=1;4 attribute=41' haredoc log
+
+# ENVIRONMENT
+
+The following environment variables affect *haredoc*'s execution:
+
+|[ *HAREPATH*
+:< The list of directories to search for modules in. See *hare-module*(5).
+| *NO_COLOR*
+: Disables all color output when set to a non-empty string.
+| *HAREDOC_COLORS*
+: See *CUSTOMIZING COLORS*.
# SEE ALSO
-*hare*(1), *hare-doc*(5)
+*hare-doc*(5)
