commit 7d892561ea68f3494a8c5beaa89c1709eba19be2
parent 5731b48ba15a8fc0f9306b4f26e541e42c08a00b
Author: Drew DeVault <sir@cmpwn.com>
Date: Fri, 19 Mar 2021 09:50:36 -0400
docs: initial draft of hare.scd
Diffstat:
4 files changed, 202 insertions(+), 1 deletion(-)
diff --git a/.gitignore b/.gitignore
@@ -1,3 +1,4 @@
config.mk
.cache
.bin
+*.1
diff --git a/Makefile b/Makefile
@@ -7,7 +7,7 @@ STDLIB=.
.bin/hare:
-.SUFFIXES: .ha .ssa .s .o
+.SUFFIXES: .ha .ssa .s .o .scd .1
.ssa.s:
@printf 'QBE\t$@\n'
@$(QBE) -o $@ $<
@@ -16,6 +16,10 @@ STDLIB=.
@printf 'AS\t$@\n'
@$(AS) -g -o $@ $<
+.scd.1:
+ @printf 'SCDOC\t$@\n'
+ @$(SCDOC) < $< > $@
+
include stdlib.mk
hare_srcs=\
@@ -44,6 +48,10 @@ $(TESTCACHE)/hare.ssa: $(hare_srcs) $(hare_testlib_deps)
@$(LD) -T $(rtscript) -o $@ \
$(TESTCACHE)/hare.o $(hare_testlib_deps)
+docs/hare.1: docs/hare.scd
+
+docs: docs/hare.1
+
clean:
@rm -rf .cache .bin
diff --git a/config.example.mk b/config.example.mk
@@ -8,3 +8,4 @@ QBE=qbe
AS=as
LD=ld
AR=ar
+SCDOC=scdoc
diff --git a/docs/hare.scd b/docs/hare.scd
@@ -0,0 +1,191 @@
+hare(1)
+
+# NAME
+
+hare - compiles, runs, and tests Hare programs
+
+# SYNOPSIS
+
+*hare* build [-cv]++
+ [-D _ident:type=value_]++
+ [-j _jobs_]++
+ [-l _name_]++
+ [-o _path_]++
+ [-t _arch_]++
+ [-T _tags_] [-X _tags_ ]++
+ [_path_]
+
+*hare* deps [-Mm] [-T _tags_] [-X _tags_ ] _path_
+
+*hare* run [-v]++
+ [-D _ident:type=value_]++
+ [-l _name_]++
+ [-j _jobs_]++
+ [-T _tags_] [-X _tags_ ]++
+ [_path_] [_args_...]
+
+*hare* test [-v]++
+ [-D _ident:type=value_]++
+ [-l _name_]++
+ [-j _jobs_]++
+ [-T _tags_] [-X _tags_ ]++
+ _tests_
+
+*hare* version
+
+# DESCRIPTION
+
+; TODO: Decide on and document driver exit statuses
+*hare build* compiles a Hare program into an executable. The _path_ argument
+shall be either the path to a Hare source file, or to a directory which contains
+a Hare module (see *MODULES* below), or may be omitted, in which case the
+working directory shall contain the Hare module to build.
+
+*hare deps* queries the dependencies 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.
+
+*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 _test_ argument is omitted, all tests are
+run. Otherwise, the list of named tests are run.
+
+*hare version* prints version information for the *hare* program, as well as
+some information about the build parameters.
+
+# OPTIONS
+
+## hare build
+
+*-c*
+ Compile only, do not link. The output is an object file (for Hare-only
+ modules) or archive (for mixed source modules).
+
+*-v*
+ Enable verbose logging. Prints every command to stderr before executing
+ it.
+
+*-D* _ident:type=value_
+ Passed to *harec*(1) to define an object in the type system. _ident_
+ shall be the identifier of this object (e.g. foo::bar::baz), _type_
+ shall be its type (in Hare syntax, e.g. "str" or
+ "struct { x: int, y: int }"), and _value_ shall be the desired 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.
+
+*-o* _path_
+ Set the output file to the given path.
+
+*-t* _arch_
+ Set the desired architecture for cross-compiling. See *ARCHITECTURES*
+ for supported architecture names.
+
+*-T* _tags_
+ Adds additional build tags, separated by commas.
+
+*-X* _tags_
+ Unsets build tags, separated by commas. See *hare version* for the list
+ of tags available by default.
+
+## hare deps
+
+*-d*
+ Print depenency graph as a dot file for use with *graphviz*(1).
+
+*-M*
+ Print rules compatible with POSIX *make*(1).
+
+*-T* _tags_
+ Adds additional build tags, separated by commas.
+
+*-X* _tags_
+ Unsets build tags, separated by commas. See *hare version* for the list
+ of tags available by default.
+
+## hare run
+
+*-v*
+ Enable verbose logging. Prints every command to stderr before executing
+ it.
+
+*-D* _ident:type=value_
+ Passed to *harec*(1) to define an object in the type system. _ident_
+ shall be the identifier of this object (e.g. foo::bar::baz), _type_
+ shall be its type (in Hare syntax, e.g. "str" or
+ "struct { x: int, y: int }"), and _value_ shall be the desired 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.
+
+*-T* _tags_
+ Adds additional build tags, separated by commas.
+
+*-X* _tags_
+ Unsets build tags, separated by commas. See *hare version* for the list
+ of tags available by default.
+
+## hare test
+
+*-v*
+ Enable verbose logging. Prints every command to stderr before executing
+ it.
+
+*-D* _ident:type=value_
+ Passed to *harec*(1) to define an object in the type system. _ident_
+ shall be the identifier of this object (e.g. foo::bar::baz), _type_
+ shall be its type (in Hare syntax, e.g. "str" or
+ "struct { x: int, y: int }"), and _value_ shall be the desired 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.
+
+*-T* _tags_
+ Adds additional build tags, separated by commas.
+
+*-X* _tags_
+ Unsets build tags, separated by commas. See *hare version* for the list
+ of tags available by default.
+
+# MODULES
+
+todo
+
+# ARCHITECTURES
+
+todo
+
+# ENVIRONMENT
+
+todo
+
+# SEE ALSO
+
+*harec*(1), *as*(1), *ld*(1), *ar*(1), *make*(1)
