summaryrefslogtreecommitdiff
path: root/doc
diff options
context:
space:
mode:
authorOri Bernstein <ori@eigenstate.org>2019-01-07 22:47:42 -0800
committerOri Bernstein <ori@eigenstate.org>2019-01-12 00:03:23 -0800
commite24656bb54b092b936c28ba5c5147d2e91fd0169 (patch)
tree3dc366beffe45947d9f41a303b213ac3463789ff /doc
parente2253ed191455e8e7d1a97583a8eb13cbde8e129 (diff)
downloadmc-e24656bb54b092b936c28ba5c5147d2e91fd0169.tar.gz
Improve manpages (thanks BurnZeZ)
Diffstat (limited to 'doc')
-rw-r--r--doc/6m.161
-rw-r--r--doc/muse.179
2 files changed, 74 insertions, 66 deletions
diff --git a/doc/6m.1 b/doc/6m.1
index 5605d84..49f6cec 100644
--- 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,91 +15,78 @@ for the corresponding architecture. Each architecture gets its own
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
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.
.PP
diff --git a/doc/muse.1 b/doc/muse.1
index d405b9c..8f68c28 100644
--- a/doc/muse.1
+++ b/doc/muse.1
@@ -3,76 +3,95 @@
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.
.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.