.\"	$Id: ccom.1,v 1.31 2014/06/06 14:59:46 plunky Exp $
.\"
.\" Copyright (c) 2007 Jeremy C. Reed <reed@reedmedia.net>
.\"
.\" Permission to use, copy, modify, and/or distribute this software for any
.\" purpose with or without fee is hereby granted, provided that the above
.\" copyright notice and this permission notice appear in all copies.
.\"
.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR AND CONTRIBUTORS DISCLAIM
.\" ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED
.\" WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL AUTHOR AND
.\" CONTRIBUTORS BE LIABLE FOR ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL
.\" DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR
.\" PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS
.\" ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF
.\" THIS SOFTWARE.
.\"
.Dd March 22, 2012
.Dt CCOM 1
.Os
.Sh NAME
.Nm ccom
.Nd C compiler
.Sh SYNOPSIS
.Nm
.Op Fl gkpsv
.Op Fl f Ar features
.Op Fl m Ar options
.Op Fl W Ar warnings
.Op Fl X Ar flags
.Op Fl x Ar settings
.Op Fl Z Ar flags
.Op infile
.Op outfile
.Sh DESCRIPTION
The
.Nm
utility provides a C compiler.
The frontend is usually
.Xr pcc 1 .
It is
.Em not
intended to be run directly.
.Nm
reads the C source from
.Ar infile
or standard input and writes the assembler source
to
.Ar outfile
or to standard output.
.Pp
The options are as follows:
.Bl -tag -width Ds
.It Fl f Ar feature
Enable language features.
Multiple
.Fl f
options can be given, the following features are supported:
.Bl -tag -width Ds
.It Sy stack-protector
Enable stack smashing protection.
Currently the same as
.Sy stack-protector-all .
.It Sy stack-protector-all
Enable stack smashing protection for all functions.
.It Sy pack-struct Ns Oo = Ns Ar n Oc
Specify maximum alignment for structure members, similar to a #pragma pack
statement at the start of the file.
If no value is given, the default is 1.
.It Sy freestanding
Emit code for a freestanding environment.
Currently not implemented.
.El
.It Fl g
Include debugging information in the output code for use by
symbolic and source-level debuggers.
Currently this uses the
.Sy stabs
format, encoding information in
.Em s Ns ymbol Em tab Ns le entrie Ns Em s.
.It Fl k
Generate PIC code.
.It Fl m Ar option
Target-specific options, used in machine-dependent code.
Multiple
.Fl m
options can be given, the following options are supported:
.Bl -tag -width PowerPC
.It AMD64
.It ARM
.Sy little-endian ,
.Sy big-endian ,
.Sy fpe=fpa ,
.Sy fpe=vpf ,
.Sy soft-float ,
.Sy arch=armv1 ,
.Sy arch=armv2 ,
.Sy arch=armv2a ,
.Sy arch=armv3 ,
.Sy arch=armv4 ,
.Sy arch=armv4t ,
.Sy arch=armv4tej ,
.Sy arch=armv5 ,
.Sy arch=armv5te ,
.Sy arch=armv5tej ,
.Sy arch=armv6 ,
.Sy arch=armv6t2 ,
.Sy arch=armv6kz ,
.Sy arch=armv6k No \*(Am
.Sy arch=armv7 .
.It HPPA
.It i386
.It M16C
.It MIPS
.Sy little-endian No \*(Am
.Sy big-endian .
.It NOVA
.It PDP-10
.It PDP-11
.It PowerPC
.Sy little-endian ,
.Sy big-endian ,
.Sy soft-float No \*(Am
.Sy hard-float .
.It Sparc64
.It VAX
.El
.It Fl p
Generate profiling code.
.It Fl s
Print statistics to standard error when complete.
This includes:
name table entries, name string size, permanent allocated memory,
temporary allocated memory, lost memory, argument list unions,
dimension/function unions, struct/union/enum blocks, inline node count,
inline control blocks, and permanent symtab entries.
.\" TODO: explain units for above?
.It Fl v
Display version.
.It Fl W Ar warning
Do some basic checks and emit warnings about possible coding problems.
Multiple
.Fl W
options can be given, the following warnings are supported:
.Bl -tag -width Ds
.It Sy error Ns Oo = Ns Ar warning Oc
Enable
.Ar warning ,
and treat it as an error condition.
If a specific warning is not given, producing any warning will cause an error.
.It Sy deprecated-declarations
Report whenever a symbol marked with the
.Sq deprecated
attribute is used.
This warning is enabled by default.
.It Sy implicit-function-declaration
(TODO) Require explicit prototypes for all called functions.
.It Sy implicit-int
(TODO) Warn when a function declaration lacks a type.
.It Sy missing-prototypes
Require explicit prototypes for all global function definitions.
.It Sy pointer-sign
Warn when pointer operations are done with mismatched signed and unsigned values.
.It Sy sign-compare
(TODO) Warn about comparisons between signed and unsigned values.
.It Sy strict-prototypes
(TODO) Require that function prototypes are strictly C99.
.It Sy shadow
Report when a local variable shadows something from a higher scope.
.It Sy truncate
Report when integer values may be implicitly truncated to fit a smaller type.
.It Sy unknown-pragmas
Report unhandled pragma statements.
.It Sy unreachable-code
Report statements that cannot be executed.
.El
.Pp
Any of the above may be prefixed with
.Dq no-
in order to disable the effect.
.\"
.It Fl X Ar flags
C specific debugging where
.Ar flags
is one or more of the following:
.Pp
.Bl -tag -compact -width Ds
.It Sy b
Building of parse trees
.It Sy d
Declarations (using multiple
.Sy d
flags gives more output)
.It Sy e
Pass1 trees at exit
.It Sy i
Initializations
.It Sy n
Memory allocations
.It Sy o
Turn off optimisations
.It Sy p
Prototypes
.It Sy s
Inlining
.It Sy t
Type conversions
.It Sy x
Target-specific flag, used in machine-dependent code
.El
.\"
.It Fl x Ar setting
Enable
.Ar setting
in the compiler.
Multiple
.Fl x
options can be given, the following settings are supported:
.Bl -tag -width Ds
.It Sy ccp
Apply sparse conditional constant propagation techniques for optimization.
Currently not implemented.
.It Sy dce
Do dead code elimination.
.It Sy deljumps
Delete redundant jumps and dead code.
.It Sy gnu89
.It Sy gnu99
Use GNU C semantics rather than C99 for some things.
Currently only inline.
.It Sy inline
Replace calls to functions marked with an inline specifier with a copy
of the actual function.
.It Sy ssa
Convert statements into static single assignment form for optimization.
Not yet finished.
.It Sy tailcall
Enable optimization of tail-recursion functions.
Currently not implemented.
.It Sy temps
Locate automatic variables into registers where possible, for further
optimization by the register allocator.
.It Sy uchar
Treat character constants as unsigned values.
.El
.\"
.It Fl Z Ar flags
Code generator (pass2) specific debugging where
.Ar flags
is one or more of the following:
.Pp
.Bl -tag -compact -width Ds
.It Sy b
Basic block and SSA building
.It Sy c
Code printout
.It Sy e
Trees when entering pass2
.It Sy f
Instruction matcher, may provide much output
.It Sy g
Print flow graphs
.It Sy n
Memory allocation
.It Sy o
Instruction generator
.It Sy r
Register allocator
.It Sy s
Shape matching in instruction generator
.It Sy t
Type matching in instruction generator
.It Sy u
Sethi-Ullman computations
.It Sy x
Target-specific flag, used in machine-dependent code
.El
.El
.Sh PRAGMAS
Input lines starting with a
.Dq #pragma
directive can be used to modify behaviour of
.Nm
during compilation.
All tokens up to the first unescaped newline are considered part
of the pragma command, with the following operations being recognized:
.Bl -tag -width Ds
.It Sy STDC
Standard C99 operator follows.
Currently no C99 operations are implemented, and any directives starting
with this token will be silently ignored.
.It Sy GCC diagnostic Ar effect Qq Ar option
GNU C compatibility.
Alter the effects of compiler diagnostics.
The required
.Ar effect
should be stated as
.Sy warning ,
.Sy error
or
.Sy ignored ,
followed by the compiler diagnostic
.Ar option
in double quotes.
For example, to force unknown pragmas to always generate an error,
a standard header might include
.Bd -literal -offset 2n
#pragma GCC diagnostic error "-Wunknown-pragmas"
.Ed
.It Sy GCC poison Ar identifier ...
GNU C compatibility.
Cause an error if any of the following
.Ar identifier Ns s
subsequently appear in the code
.Pq but not in any macro expansions .
Currently not implemented.
.It Sy GCC system_header
GNU C compatibility.
Currently not implemented.
.It Sy GCC visibility
GNU C compatibility.
Currently not implemented.
.It Sy pack Ns Pq Op Ar n
Set the default maximum alignment for structures and unions, such that
members will have their natural alignment requirements clamped at this
value and may be stored misaligned.
If
.Ar n
is not given, the alignment is reset to the target default.
.It Sy pack Ns Pq Sy push Ns Op , Ar n
Push the current pack setting onto an internal stack then, if
.Ar n
is given, change the default alignment for structures and unions.
Currently not implemented.
.It Sy pack Ns Pq Sy pop
Change the pack setting to the most recently pushed value, and remove
that setting from the stack.
Currently not implemented.
.It Sy packed Op Ar n
Set the maximum alignment for the structure or union defined
in the current statement.
If
.Ar n
is not given, the default value of 1 is used.
.Pq Currently this works except Ar n is not used
.It Sy aligned Op Ar n
Set the minimum alignment for the structure or union defined
in the current statement.
.It Sy rename Ar name
Provide an alternative
.Ar name
which will be used to reference the object declared in the current statement.
.It Sy weak Ar name Ns Op = Ns Ar alias
Mark
.Ar name
as a weak rather than a global symbol, to allow its definition to be
overridden at link time.
If an
.Ar alias
is given, this will be used as the default value of
.Ar name .
.It Sy ident
Currently not implemented.
.El
.Lp
and the following target-specific operations are handled by
machine-dependent code:
.Bl -tag -width Ds
.It Sy tls
For AMD64 and i386 targets, the variable declared in the current statement
will be referenced via the
.Dq thread-local storage
mechanism.
.It Sy init
For AMD64, ARM, HPPA, i386, MIPS and PowerPC targets, when the current statement is a
function declaration, generate a reference in the
.Sy .ctors
section, enabling library code to call the function prior to entering
.Fn main .
.It Sy fini
For AMD64, ARM, HPPA, i386, MIPS and PowerPC targets, when the current statement is a
function declaration, generate a reference in the
.Sy .dtors
section, enabling library code to call the function when
.Fn main
returns or the
.Fn exit
function is called.
.It Sy section Ar name
For AMD64, ARM, HPPA and i386 targets, place the subsequent code in the named
section.
.Pq This is currently broken .
.It Sy alias Ar name
For AMD64, HPPA and i386 targets, emit assembler instructions providing an
alias for the symbol defined by the current statement.
.It Sy stdcall
For i386 targets, enable
.Dq stdcall
semantics during code generation, where function arguments are passed on
the stack in right-to-left order, and the callee is responsible for adjusting
the stack pointer before returning.
Any function result is passed in the EAX register.
On win32, the function name is postfixed with an
.Dq @
and the size of the stack adjustment.
.It Sy cdecl
For i386 targets, enable
.Dq cdecl
semantics during code generation, where function arguments are passed on
the stack in right-to-left order, and the caller is responsible for cleaning
up the stack after the function returns.
Any function result is passed in the EAX register.
This is the default.
.It Sy fastcall
For i386-win32 targets, enable
.Dq fastcall
semantics during code generation.
.Po
Currently this is equivalent to
.Sy stdcall ,
which is likely wrong
.Pc .
.It Sy dllimport
For i386-win32 targets, references to the external symbol defined by
the current statement will be made via indirect access through a
location identified by the symbol name prefixed with
.Dq __imp_ .
.It Sy dllexport
For i386-win32 targets, the external symbol declared by the current
statement will be exported as an indirect reference to be
accessed with
.Sy dllimport .
The global locator will be the symbol name prefixed with
.Dq __imp_ .
Currently this is not completely implemented.
.El
.Pp
Any unknown
.Dq #pragma
directives will be ignored unless the
.Fl Wunknown-pragmas
diagnostic is in effect.
.Sh SEE ALSO
.Xr as 1 ,
.Xr cpp 1 ,
.Xr pcc 1
.Sh HISTORY
The
.Nm
compiler is based on the original Portable C Compiler by
.An "S. C. Johnson" ,
written in the late 70's.
Even though much of the compiler has been rewritten
.Pq about 50% of the frontend code and 80% of the backend ,
some of the basics still remain.
Most is written by
.An "Anders Magnusson" ,
with the exception of the data-flow analysis part and
the SSA conversion code which is written by
.An "Peter A Jonsson" ,
and the Mips port that were written as part of a project
by undergraduate students at Lulea University of Technology.
.Pp
This product includes software developed or owned by Caldera
International, Inc.