ref: e24656bb54b092b936c28ba5c5147d2e91fd0169
parent: e2253ed191455e8e7d1a97583a8eb13cbde8e129
author: Ori Bernstein <ori@eigenstate.org>
date: Mon Jan 7 17:47:42 EST 2019
Improve manpages (thanks BurnZeZ)
--- a/doc/6m.1
+++ b/doc/6m.1
@@ -1,11 +1,13 @@
-.TH MC 1
+.TH 6m 1
.SH NAME
6m
.SH SYNOPSIS
.B 6m
-.I -[?hioSG9d]
-.I [file...]
-.br
+[
+.B -?hioSG9d
+] [
+.I file ...
+]
.SH DESCRIPTION
.PP
The ?m compiler family compiles Myrddin source into object files
@@ -13,11 +15,12 @@
compler. Unless otherwise specified, if the input file is named
.I filename.myr
then the the object file that is generated will be named
-.I filename.o.
+.IR filename.o .
.PP
Any text between the first '+' in the file name and the suffix are
stripped. This functionality is used to specify system tags for
-tools like 'mbld'.
+tools like
+.IR mbld .
.PP
If the filename does not end with the suffix
.I .myr
@@ -24,79 +27,65 @@
then the object suffix
.I .o
will simply be appended to it.
-
.PP
The following architectures are currently supported:
.TP
6m
x86-64
-
.PP
The compiler options are:
-
.TP
+.BR -h\ |\ -?
+Print a summary of the available options.
+.TP
.B -d [flTriu]
Print debugging dumps. Additional options may be given to give more
debugging information for specific intermediate states of the compilation.
-
.TP
-.B -h, -?
-Print a summary of the available options.
-
-.TP
-.B -I path
+.BI -I\ path
Add 'path' to the search path for unquoted use statments. This option
does not affect the search path for local usefiles, which are always
searched relative to the directory containing the output file. Without
any options, the search path defaults to /usr/include/myr.
-
.TP
-.B -o output-file
+.BI -o\ output-file
Specify that the generated code should be placed in
.I output-file
instead of the default location.
-
.TP
.B -S
Generate assembly code along with the object file.
-
.TP
.B -G
Generate assembly in the Gnu As syntax.
-
.TP
-.B -O out
+.BI -O\ out
Output code to output path 'out'
-
.TP
.B -T
Compile in test mode. This implies that pkglocal functions are
available.
-
.TP
.B -9
Generate assembly in the Plan 9 syntax.
-
.SH EXAMPLE
+.IP
.EX
- 6m foo.myr
- 6m bar.myr
- ld -o foobar foo.o bar.o
+6m foo.myr
+6m bar.myr
+ld -o foobar foo.o bar.o
.EE
-
+.LP
.SH FILES
The source code for this compiler is available from
.B git://git.eigenstate.org/git/ori/mc.git
-
.SH SEE ALSO
-.IR muse(1)
-.IR ld(1)
-.IR as(1)
-
+.IR muse (1),
+.IR 2l (1),
+.IR 2a (1),
+.IR ld (1),
+.IR as (1)
.SH BUGS
-.PP
-The language is not yet complete, and the compilers often omit useful
-constructs in spite of their desirability.
.PP
There are virtually no optimizations done, and the generated source is
often very poorly performing.
--- a/doc/muse.1
+++ b/doc/muse.1
@@ -3,72 +3,86 @@
muse
.SH SYNOPSIS
.B muse
-.I -o out -p pkg [-h] [-d dbg] [-l libs]
-.I [file...]
-.br
+.B -o
+.I out
+.B -p
+.I pkg
+[
+.B -h
+] [
+.B -d
+.I dbg
+] [
+.B -l
+.I libs
+] [
+.I file ...
+]
.SH DESCRIPTION
.PP
-The muse tool acts as a linker for
+The
+.I muse
+tool acts as a linker for
.I .use
files. It reads all of the usefiles provided to it on the
command line, filters them by package, and outputs a new
usefile with the merged set of symbols. Both the
-.I -o out.use
+.B -o
+.I out.use
and the
-.I -p pkg
+.B -p
+.I pkg
options are mandatory.
-
.PP
-The output of muse is architecture-independent. However, the format of the
+The output of
+.I muse
+is architecture-independent. However, the format of the
generated file is not stable, and is not guaranteed to work across
different compiler versions.
-
.PP
-The muse options are:
-
+The
+.I muse
+options are:
.TP
+.B -h
+Print a summary of the available options.
+.TP
.B -d [flTri]
Print debugging dumps. Additional options may be given to give more
debugging information for specific intermediate states of the compilation.
-
.TP
-.B -h
-Print a summary of the available options.
-
-.TP
-.B -p package
+.BI -p\ package
Take the symbols that match
.I package
and their dependencies, and merge them into a single package. Only symbols
matching the package name will be reexported.
-
.TP
-.B -o output-file
+.BI -o\ output-file
Specify that the generated usefile should be named
.I output-file.
By convention,
.I output-file
should match up with the package name given to the
-.I -p
+.B -p
option.
-
.SH EXAMPLE
+.IP
.EX
muse -o library.use -p library foo.use bar.use
.EE
-
+.LP
.SH FILES
-The source for muse is available from
+The source for
+.I muse
+is available from
.B git://git.eigenstate.org/git/ori/mc.git
and lives in the
-.I muse/
+.I muse
directory within the source tree.
-
.SH SEE ALSO
-.IR 6m(1)
-.IR ld(1)
-.IR as(1)
-
+.IR 6m (1),
+.IR 2l (1),
+.IR 2a (1)
.SH BUGS
.PP
There is insufficient checking and validation done on usefiles.
@@ -75,4 +89,9 @@
.PP
The file format is in flux, and in current iterations, it is not at all compact.
.PP
-The file format is not closed under concatentation.
+There is no versioning on the usefiles as it stands. If you use the wrong
+version with the wrong compiler, a mysterious error or even segfault is
+likely.
+.PP
+This utility should not exist. Instead, the compiler should put the
+exported symbol information into the object file or library directly.
--- a/lib/crypto/x25519.myr
+++ b/lib/crypto/x25519.myr
@@ -50,7 +50,7 @@
use std
pkg crypto =
- const fdiff : (out : felem[:], in : felem[:] -> void)
+ const x25519 : (out : byte[:], inu : byte[:], inpt : byte[:] -> void)
;;
type felem = uint64
@@ -639,4 +639,7 @@
crecip(zmone[:], z[:])
fmul(z[:], x[:], zmone[:])
fcontract(pub[:], z[:])
+}
+
+const x25519 = {out, inu, inscalar}
--- a/mbld/mbld.1
+++ b/mbld/mbld.1
@@ -3,101 +3,135 @@
mbld
.SH SYNOPSIS
.B mbld
-.RB [-?hcfrSs]
-.RB [-b\ bin]
-.RB [-l\ lib]
-.RB [-R\ src]
-.RB [-I\ inc]
-.RB [-B\ base]
-.RB [-r\ runtime]
-.RB [all\ |\ clean\ |\ install\ |\ uninstall\ |\ test\ |\ file...\ |\ target...]
+[
+.B -?hcfrSs
+]
+[
+.B -b
+.I bin
+]
+[
+.B -l
+.I lib
+]
+[
+.B -R
+.I src
+]
+[
+.B -I
+.I inc
+]
+[
+.B -B
+.I base
+]
+[
+.B -r
+.I runtime
+]
+[
+.I all
+|
+.I clean
+|
+.I install
+|
+.I uninstall
+|
+.I test
+|
+.I file ...
+|
+.I target ...
+]
.br
.SH DESCRIPTION
.PP
-The 'mbld' tool takes as input a list of Myrddin or assembly sources,
-and compiles them in the correct dependency order into either a library or
-an executable.
-
+The
+.I mbld
+tool takes as input a list of Myrddin or assembly sources,
+and compiles them in the correct dependency order into either a library,
+or an executable.
.PP
-By default, it reads from an input file called 'bld.proj', but if given the
-option
-.I -b
-or
-.IR -l ,
+By default, it reads from an input file called
+.IR bld.proj ,
+but if given the option
+.B -b
+or
+.BR -l ,
it will build a binary or library, respectively, from
the arguments specified on the command lines.
-
.PP
-Mbld will default to building for the current architecture and operating
+.I Mbld
+will default to building for the current architecture and operating
system.
-
.SH OPTIONS
-
.TP
-.B -h | -?
+.BR -h\ |\ -?
Print a summary of the available options.
-
.TP
-.B -b \fIbinname\fP
-Compile source into a binary named 'name'. If neither this option nor
-the
-.I -l
-option are given, mbld will create a binary called
+.BI -b\ binname
+Compile source into a binary named
+.IR name .
+If neither this option nor the
+.B -l
+option are given, mbld will create a binary called
.IR a.out .
-
.TP
-.B -I \fIpath\fP
-Add 'path' to the search path for unquoted use statments. This option
+.BI -I\ path
+Add
+.I path
+to the search path for unquoted use statments. This option
does not affect the search path for local usefiles, which are always
searched relative to the compiler's current working directory. Without
-any options, the search path defaults to
+any options, the search path defaults to
.IR /usr/include/myr .
-
.TP
-.B -l \fIlibname\fP
-Compile source given into a library called 'lib\fIname\fP.a' (or the equivalent
-for the target platform), and a matching usefile called 'name'. Only static
-libraries are currently supported. Ignores the contents of \fIbld.proj\fP
-and \fIbld.sub\fP if they exist.
-
+.BI -l\ libname
+Compile source given into a library called
+.I libname.a
+(or the equivalent
+for the target platform), and a matching usefile called
+.IR name .
+Only static
+libraries are currently supported. Ignores the contents of
+.I bld.proj
+and
+.I bld.sub
+if they exist.
.TP
-.B -R \fIsrc\fP
+.BI -R\ src
Compile source given into a binary in temporary storage, and then execute it
with the command line arguments passed in.
-
.TP
.B -S
Tell the toolchain to generate assembly for the code being compiled as well
as the .o files, as though
-.I -S
-was passed to 6m.
-
+.B -S
+was passed to
+.IR 6m .
.TP
-.B -r \fIruntime\fP
-Compile a binary using the runtime
-.IR rt .
-If the runtime name given
-is
+.BI -r\ runtime
+Compile a binary using the given runtime.
+If the runtime name given is
.IR none ,
then no runtime will be linked. If this option is not provided,
-then the default runtime in
-.I $INSTALL_ROOT/myr/lib/_myrrt.o
+then the default runtime in
+.B $INSTALL_ROOT/myr/lib/_myrrt.o
will be used.
-
.SH ACTIONS
-
-Mbld already knows how to do most of the common commands. Given a file
+.I Mbld
+already knows how to do most of the common commands. Given a file
describing your project, it can build, test, clean, install, uninstall,
and benchmark your code.
-
.TP
.B all
-The
+The
.I all
action will build all the non-test targets specified in the build file.
If there are generated files included in the build, then their generation
commands will be run.
-
.TP
.B clean
The
@@ -104,7 +138,6 @@
.I clean
action will remove all compiled files and non-durable generated inputs
from the build directories.
-
.TP
.B install
The
@@ -112,10 +145,9 @@
action will copy the generated sources, manpages, data files, and anything
else installable into the appropriate directories for the current system.
If the
-.I DESTDIR
+.B $DESTDIR
environment variable is set, then its contexts will be prepended to the
install path.
-
.TP
.B uninstall
The
@@ -123,7 +155,6 @@
action will remove the files installed by the
.I install
action.
-
.TP
.B test
The
@@ -132,7 +163,6 @@
exits with a non-zero status, that is counted as a failure. If a
test outputs subtest data, then this target will show the output
in a pretty format.
-
.TP
.B bench
The
@@ -140,19 +170,15 @@
action will build the benchmarks and run them. At the end of the
run, the run statistics are shown. Benchmarks must generate output
in the subtest format.
-
.TP
.B list
The
.I list
action lists all available targets for the build.
-
.SH BUILD FILES
-
Build files contain lists of targets. Targets generally
consist of a target type. This is usually followed by
target name, an attribute list, and the list of inputs.
-
Each Myrddin source file may have a corresponding implicit
test. If a source file
.I foo.myr
@@ -161,79 +187,87 @@
is used as the testcase for
.I foo.myr
if it exists.
-
+.PP
A typical build file may look something like:
-
+.IP
.EX
- bin foo = main.myr gen-foo.myr ;;
- man = foo.1 ;;
- gen gen-foo.myr = sh -c "echo $FOO > gen-foo.myr" ;;
- lib foothing = lib.myr ;;
+bin foo = main.myr gen-foo.myr ;;
+man = foo.1 ;;
+gen gen-foo.myr = sh -c "echo $FOO > gen-foo.myr" ;;
+lib foothing = lib.myr ;;
.EE
-
+.LP
The full grammar is listed below:
-
+.IP
.EX
- bldfile : bldent+
- bldent
- : "bin" target
- | "lib" target
- | "test" target
- | "bench" target
- | "gen" target
- | "cmd" target
- | "data" flist
- | "man" flist
- | "sub" flist
- | option
- option
- : "incpath" "=" list
- | "libdeps" "=" list
- | "testdeps" "=" list
- | "runtime" word
- | "noinst"
- target : name [attrs] "=" list
- flist : [attrs] "=" list
- list : name+ ";;"
- attrs : "{" (key [ "=" value])* "}"- name : <nonspace> | <quoted word>
+bldfile : bldent+
+bldent : "bin" target
+ | "lib" target
+ | "test" target
+ | "bench" target
+ | "gen" target
+ | "cmd" target
+ | "data" flist
+ | "man" flist
+ | "sub" flist
+ | option
+option : "incpath" "=" list
+ | "libdeps" "=" list
+ | "testdeps" "=" list
+ | "runtime" word
+ | "noinst"
+target : name [attrs] "=" list
+flist : [attrs] "=" list
+list : name+ ";;"
+attrs : "{" (key [ "=" value])* "}"+name : <nonspace> | <quoted word>
.EE
-
+.LP
.PP
-Bin, test, and bench targets all behave in a
+.IR Bin ,
+.IR test ,
+and
+.I bench
+targets all behave in a
very similar way. They all produce a single binary
from a list of Myrddin sources, scraping the appropriate
library dependencies and building any libraries from
-the local source directories. Bin targets are installed
-to
-.I ${BASEDIR}/bin+the local source directories.
+.I Bin
+targets are installed to
+.B $BASEDIR/bin
when invoking
.IR mbld\ install .
-Test and bench targets built and run
+.I Test
+and
+.I bench
+targets built and run
when invoking
-.IR mbld bench .
-Tests are run with the
-.I cwd
-set to the directory that contains
-the test source
-
+.I mbld
+.IR bench .
+Tests are run with the working directory set to the directory
+that contains the test source
.PP
-Lib targets also resemble bin targets, but instead of
-producing a binary, they produce a
+.I Lib
+targets also resemble
+.I bin
+targets, but instead of producing a binary, they produce a
.I .use
and
.I .a
file pair. These files are installed to
-.I ${BASEDIR}/lib/myr+.B $BASEDIR/lib/myr
when invoking
-.IR mbld install .
-
+.IR mbld\ install .
.PP
-Gen and cmd targets are also similar to each other,
+.I Gen
+and
+.I cmd
+targets are also similar to each other,
varying largely in when and how they are invoked.
-Gen targets specify an output file, and are run in
+.I Gen
+targets specify an output file, and are run in
response to a target requiring their output.
-
.PP
On the other targets are not invoked implicitly at all,
unless they have an attribute such as
@@ -243,7 +277,6 @@
Instead, they are invoked explicitly by the user, bundling
up some useful command or another, possibly providing system
specific variants.
-
.PP
Data targets allow the specification of bundled static data.
This data may be generated from a
@@ -251,8 +284,7 @@
target, or may simply be shipped as a file. The data is
installed to the system specific share directory. For example,
on Unix, this may be
-.IR ${BASEDIR}/share .-
+.BR $BASEDIR/share .
.PP
Man targets are installed to the system-appropriate manual
directory. The section is determined by the manpage suffix.
@@ -259,9 +291,9 @@
For example
.I foo.1
would be installed into section 1 of the manual.
-
.PP
-Sub targets include a
+.I Sub
+targets include a
.I bld.sub
or
.I bld.proj
@@ -268,61 +300,49 @@
from a subdirectory. If the file in the subdirectory is
.I bld.proj
then the root of the project is changed for that subbuild.
-
.SH ATTRIBUTES
-
Many targets support attributes. These are the valid
attributes allowed in the targets.
-
.TP
.B ldscript
Link the target using an ldscript. This is a system
dependent option, and should be avoided. Valid on binary
targets.
-
.TP
.B runtime
Link the target using a custom runtime. Valid on binary
targets
-
.TP
.B inc=path
Add a path to the include
.IR path .
Valid on binary targets.
-
.TP
.B tag=tagname
Build this target only when the build tag
-.I tag
+.I tagname
is specified.
-
.TP
.B inst
Install this target. This is the default for all non-test
targets.
-
.TP
.B noinst
Do not install this target when running
.IR mbld\ install .
-
.TP
.B test
This target should run as a test. This is how command targets
are turned into test runners.
-
.TP
.B bench
This target is run as a benchmark. This is how command targets
are turned into benchmark runners.
-
.TP
.B notest
This target is not to be run as a benchmark. It's particularly
fun to use in conjunction with test targets, in spite of being
spectacularly useless.
-
.TP
.B durable
The file generated by this
@@ -333,7 +353,6 @@
.IR mbld\ clean .
This is useful for keeping around files where the user may not
have or want to run the generation code.
-
.TP
.B dep=path
Specifies that a
@@ -341,87 +360,75 @@
or
.I cmd
target should be re-run when the argument changes.
-
.TP
.B path=path
When specified on a data target, provides the desired
installation directory. Defaults to
-.IR ${BASEDIR}/share \.-
+.BR $BASEDIR/share .
.SH FILES
-
.TP
.I bld.proj
The root project file. All paths in bldfiles are relative
to the most recent one in the directory heirarchy.
-
.TP
.I bld.sub
A sub build. This contains targets, and may specify dependencies
on other targets within the same project.
-
.SH EXAMPLE
.EX
- mbld
+mbld
.EE
-
.PP
The command above will load bld.proj and all associated sub builds,
and run the commands to incrementally rebuild the code.
-
.EX
- mbld -l foo bar.myr baz.myr
+mbld -l foo bar.myr baz.myr
.EE
-
.PP
-The command above will ignore bld.proj and produce a library
-named \fIlibfoo.a\fP, consisting of the files \fIbar.myr\fP
-and \fIbaz.myr\fP
-
-
+The command above will ignore bld.proj and produce a library named
+.IR libfoo.a ,
+consisting of the files
+.I bar.myr
+and
+.IR baz.myr .
.SH ENVIRONMENT VARIABLES
-
.TP
.B DESTDIR
-prepends $DESTDIR to the path to install to. For example, if the installgg
-prefix is /usr, the binary path is bin/, then binaries will get copied
-to
-.I $DESTDIR/usr/bin
-on
-.B mbld install
-
+Prepends
+.B $DESTDIR
+to the installation path. For example, if the installation prefix is
+/amd64 and the binary path is /bin, the resulting binaries will be
+copied to
+.B $DESTDIR/amd64/bin
+on
+.IR mbld\ install .
.TP
.B MYR_MC
-Compiles the binaries with
-.I $MYR_MC
+Compiles the binaries with
+.B $MYR_MC
instead of the default value,
.IR 6m .
-
.TP
.B MYR_MUSE
-Merges usefiles with
-.I $MYR_MUSE
-instead of hte default value
+Merges usefiles with
+.B $MYR_MUSE
+instead of the default value
.IR muse .
-
.TP
.B MYR_RT
Links with the runtime $MYR_RT instead of the default
-.IR ${BASEDIR}/lib/myr/_myrrt.o . -
+.BR $BASEDIR/lib/myr/_myrrt.o .
.SH SOURCES
The source for mbld is available from
.B git://git.eigenstate.org/git/ori/mc.git
and lives in the
-.I mbld/
+.I mbld
directory within the source tree.
-
.SH SEE ALSO
-.IR 6m(1)
-.IR muse(1)
-.IR ld(1)
-.IR as(1)
-
+.IR 6m (1),
+.IR muse (1),
+.IR make (1),
+.IR mk (1)
.SH BUGS
.PP
None known.