plan9port/man/man1/9c.1

.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