10564b1175
groff 1.23.0 added .MR to its -man macro package. The NEWS file states
that the inclusion of the macro "was prompted by its introduction to
Plan 9 from User Space's troff in August 2020." From d32deab it seems
that the name for Plan 9 from User Space's implementation was suggested
by groff maintainer G. Brandon Robinson.
Not sure if the intention was to make these definitions compatible, but
it would be nice if they were.
Currently, Plan 9 from User Space's .MR expects its second argument to
be parenthesized. groff's .MR does not. This results in extra
parentheses appearing in manual references when viewing Plan 9 from User
Space's manual pages on a system using groff.
205 lines
3.4 KiB
Groff
205 lines
3.4 KiB
Groff
.TH 9C 1
|
|
.SH NAME
|
|
9c, 9l, 9ar \- C compiler, assembler, linker, archiver
|
|
.SH SYNOPSIS
|
|
.B 9c
|
|
[
|
|
.B -I
|
|
.I path
|
|
]
|
|
[
|
|
.B -D
|
|
.I name
|
|
]
|
|
.I file
|
|
\&...
|
|
.PP
|
|
.B 9l
|
|
[
|
|
.I -o
|
|
.I target
|
|
]
|
|
.I object
|
|
\&...
|
|
[
|
|
.I library
|
|
\&...
|
|
]
|
|
[
|
|
.BI -L path
|
|
\&...
|
|
]
|
|
[
|
|
.BI -l name
|
|
\&...
|
|
]
|
|
.PP
|
|
.B 9ar
|
|
.I key
|
|
[
|
|
.I posname
|
|
]
|
|
.I afile
|
|
[
|
|
.I file
|
|
\&...
|
|
]
|
|
.SH DESCRIPTION
|
|
These programs are shell scripts that invoke the appropriate standard tools
|
|
for the current operating system and architecture.
|
|
One can use them to write portable recipes for mkfiles.
|
|
.PP
|
|
.I 9c
|
|
compiles the named C
|
|
.I files
|
|
into object files for the current system.
|
|
The system C compiler is invoked with warnings enabled.
|
|
The
|
|
.B -I
|
|
option adds
|
|
.I path
|
|
to the include path,
|
|
and the
|
|
.B -D
|
|
option defines
|
|
.I name
|
|
in the C preprocessor.
|
|
.I 9c
|
|
always
|
|
defines the symbol
|
|
.B PLAN9PORT
|
|
defined in the C preprocessor and adds
|
|
.B $PLAN9/include
|
|
to the include path.
|
|
.PP
|
|
.I 9c
|
|
also defines
|
|
.B __sun__
|
|
on SunOS systems.
|
|
.PP
|
|
.I 9l
|
|
links the named object files and libraries to create the target executable.
|
|
Each
|
|
.B -l
|
|
option specifies that a library named
|
|
.BI lib name .a
|
|
be found and linked.
|
|
The
|
|
.B -L
|
|
option adds directories to the library search path.
|
|
.I 9l
|
|
invokes the system linker with
|
|
.B $PLAN9/lib
|
|
already on the library search path.
|
|
.PP
|
|
.I 9l
|
|
searches the named objects and libraries for symbols of the form
|
|
.BI __p9l_autolib_ name \fR,
|
|
which it takes as indication that it should link
|
|
.BI $PLAN9/lib/lib name .a
|
|
as well.
|
|
It also examines such libraries to find their own dependencies.
|
|
A single
|
|
.B -l
|
|
option at the beginning of the command line disables this behavior.
|
|
The symbol
|
|
.BI __p9l_autolib_ name
|
|
is added to an object file by the macro
|
|
.B AUTOLIB( name )\fR,
|
|
defined in
|
|
.B <u.h>.
|
|
Header files associated with libraries contain
|
|
.B AUTOLIB
|
|
annotations; ordinary programs need not use them.
|
|
Due to shortcomings in the implementation, a source file may not
|
|
contain the same
|
|
.B AUTOLIB
|
|
statement multiple times.
|
|
.PP
|
|
.I 9ar
|
|
maintains object file archives called libraries.
|
|
The exact set of valid command keys varies from system to system,
|
|
but
|
|
.I 9ar
|
|
always provides the following key characters:
|
|
.TP
|
|
.B d
|
|
Delete
|
|
.I files
|
|
from the archive file.
|
|
.TP
|
|
.B r
|
|
Replace
|
|
.I files
|
|
in the archive file, or add them if missing.
|
|
.TP
|
|
.B t
|
|
List a table of contents of the archive.
|
|
If names are given, only those files are listed.
|
|
.TP
|
|
.B x
|
|
Extract the named files.
|
|
If no names are given, all files in the archive are
|
|
extracted.
|
|
In neither case does
|
|
.B x
|
|
alter the archive file.
|
|
.TP
|
|
.B v
|
|
Verbose.
|
|
Give a file-by-file
|
|
description of the making of a
|
|
new archive file from the old archive and the constituent files.
|
|
With
|
|
.BR t ,
|
|
give a long listing of all information about the files,
|
|
somewhat like a listing by
|
|
.MR ls 1 ,
|
|
showing
|
|
.br
|
|
.ns
|
|
.IP
|
|
.B
|
|
mode uid/gid size date name
|
|
.TP
|
|
.B c
|
|
Create.
|
|
Normally
|
|
.I 9ar
|
|
will create a new archive when
|
|
.I afile
|
|
does not exist, and give a warning.
|
|
Option
|
|
.B c
|
|
discards any old contents and suppresses the warning.
|
|
.PD
|
|
.PP
|
|
When a
|
|
.BR d ,
|
|
.BR r ,
|
|
or
|
|
.BR m
|
|
.I key
|
|
is specified,
|
|
.I 9ar
|
|
inserts a table of contents, required by the linker, at
|
|
the front of the library.
|
|
The table of contents is
|
|
rebuilt whenever the archive is modified.
|
|
.SH EXAMPLES
|
|
.TP
|
|
.L
|
|
9c file1.c file2.c file3.c
|
|
Compile three C source files.
|
|
.TP
|
|
.L
|
|
9ar rvc lib.a file[12].o
|
|
Archive the first two object files into a library.
|
|
.TP
|
|
.L
|
|
9l -o prog file3.o file4.o lib.a
|
|
Link the final two object files and any necessary objects from the library
|
|
into an executable.
|
|
.SH SOURCE
|
|
.B \*9/bin
|