tools/cw/cw.1onbld

.\"
.\" CDDL HEADER START
.\"
.\" The contents of this file are subject to the terms of the
.\" Common Development and Distribution License (the "License").
.\" You may not use this file except in compliance with the License.
.\"
.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE
.\" or http://www.opensolaris.org/os/licensing.
.\" See the License for the specific language governing permissions
.\" and limitations under the License.
.\"
.\" When distributing Covered Code, include this CDDL HEADER in each
.\" file and include the License file at usr/src/OPENSOLARIS.LICENSE.
.\" If applicable, add the following below this CDDL HEADER, with the
.\" fields enclosed by brackets "[]" replaced with your own identifying
.\" information: Portions Copyright [yyyy] [name of copyright owner]
.\"
.\" CDDL HEADER END
.\"
.\" Copyright 2010 Sun Microsystems, Inc.  All rights reserved.
.\" Use is subject to license terms.
.\"
.\" Copyright 2018 Joyent, Inc.
.\"
.Dd September 4, 2018
.Dt CW 1ONBLD
.Os
.Sh NAME
.Nm cw
.Nd invoke one or more compilers with argument translation
.Sh SYNOPSIS
.Nm cw
.Op Fl C
.Op Fl -versions
.Op Fl -noecho
.Fl -primary Ar compiler
.Op Fl -shadow Ar compiler ...
.Op Fl -linker Ar linker
.Fl -
.Ar compiler args ...
.Sh DESCRIPTION
.Nm cw
is a facility for invoking one or more compilers, providing translation from
Sun style arguments as appropriate.
This allows the use of arbitrary compilers without the need to alter large
numbers of makefiles.
A mode called shadow compilation invokes multiple compilers so that warnings
and errors may be obtained from all of them.
See
.Sx SHADOW COMPILATION
for details.
This version of cw supports compilers with both Sun Studio 12 and GCC-style
command lines.
.Sh ARGUMENTS
Both the
.Fl -primary
and
.Fl -shadow
parameters take a
.Em compiler specification .
This is a comma-separated list of the form
.Ar name,executable,style
Where
.Ar name
is a name for the compiler,
.Ar executable
is the full path to the compiler executable, and
.Ar style
is the style of command-line options the compiler expects, either
.Em sun
or
.Em gnu .
.Bl -tag -width indent
.It Fl -primary Ar compiler
Specify the compiler to be used primarily (that which is used for link-editing
and pre-processing, and whos objects we deliver).
.It Fl -shadow Ar compiler
Specify a shadow compiler, which builds sources for the sake of checking code
quality and compatibility, but has its output discarded.
.It Fl -linker Ar linker
Specify a link-editor to use in place of
.Pa /usr/bin/ld .
.Xr ld 1
itself arranges for this to be executed by any subprocesses.
.It Fl -noecho
Do not echo the actual command line of any compilers invoked.
.It Fl -versions
Request from each configured primary and shadow compiler its version
information.
.It Fl C
The sources being compiled are C++.  This is necessary as it affects the
translation of compiler arguments.
.It Fl -
Arguments intended for the compilers themselves must be separated from those
of
.Nm cw
by a
.Fl - .
.It Fl _name=
.It Fl _style=
Parameters intended for the compiler be guarded with options of the form
.Fl _name=
and
.Fl _style=
Where
.Em name
and
.Em style
are those passed to
.Fl -primary
and
.Fl -shadow
this allows certain flags to be passed only to certain classes of compiler.
.Pp
For historical reasons, the
.Fl _style=
option is also translated such that a style of
.Em sun
may use the flag
.Fl _cc=
and a style of
.Em gnu
may use the flag
.Fl _gcc= ,
and when the
.Fl C
option is given and C++ is in use the style of
.Em sun
may use the flag
.Fl _CC=
and the style of
.Em gnu
may use the flag
.Fl _g++= .
.El
.Sh SHADOW COMPILATION
If
.Fl -shadow
compilers are specified
.Nm cw
will invoke each shadow compiler, with the outputs modified (as well as any
translation for compiler style) as follows:
.Bl -enum
.It
If
.Nm cw
is invoked to link-edit without compilation (the input files are all objects),
the shadow compiler is not invoked.
.It
If the
.Fl o Ar filename
option was provided, with or without a separating space, it will be replaced with
.Fl o Ar tempfile
.It
If the option
.Fl o
was not provided,
.Fl o Ar tempfile
will be added to the end of the argument list used to invoke
the shadow compilers.
.El
When shadow compilation is in effect,
.Nm cw
writes to standard error each compiler's standard error output following its
argument list.
Messages from the compilers will not be interleaved.
If
.Nm cw
is used to invoke the preprocessor and no output location is specified,
.Nm cw
will write to standard output the primary compiler's standard output.
.Pp
Because the Sun compilers write intermediate objects to fixed
filenames in the current directory when instructed to compile and
link multiple source files via a single command line, it would be
unsafe to invoke more than one compiler in this fashion.
Therefore
.Nm cw
does not accept multiple source files unless the preprocessor is to be
invoked.
An attempt to invoke
.Nm cw
in this manner will result in an error.
.Sh ARGUMENT TRANSLATION
If the compiler to be invoked is a GNU-style C or C++ compiler, a set of
default flags is added to the beginning of the argument list, and the
remaining arguments are translated to their closest appropriate
semantic equivalents and passed in the same order as their
counterparts given to
.Nm cw .
See the comments at the head of
.Pa usr/src/tools/cw/cw.c
for a detailed list of translations.
.Sh ENVIRONMENT
.Bl -tag -width indent
.It CW_SHADOW_SERIAL
If this variable is set in the environment, invoke the primary compiler, wait
for it to complete, then invoke the shadow compilers.
Normally the primary and shadow compilers are invoked in parallel.
.It CW_NO_EXEC
f this variable is set in the environment, write the usual output to
standard error but do not actually invoke any compiler.
This is useful for debugging the translation engine.
.El
.Sh EXIT STATUS
The following exit status values are returned:
.Bl -tag -width indent
.It 0
The primary compiler, and shadow compilers if invoked, all completed
successfully.
.It >0
A usage error occurred, or one or more compilers returned a nonzero
exit status.
.El
.Sh SEE ALSO
.Xr cc 1 ,
.Xr CC 1 ,
.Xr gcc 1 ,
.Xr ld 1
.Sh BUGS
The translations provided for gcc are not always exact and in some cases
reflect local policy rather than actual equivalence.
.Pp
Additional compiler types should be supported.
.Pp
The translation engine is hacky.