1 files changed, 220 insertions, 0 deletions
diff --git a/usr/src/tools/cw/cw.1onbld b/usr/src/tools/cw/cw.1onbld
new file mode 100644
index 0000000..62800bb
--- /dev/null
+++ b/usr/src/tools/cw/cw.1onbld
@@ -0,0 +1,220 @@
+.\"
+.\" 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 ...
+.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 -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
+.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.