usr/src/tools/cw/cw.1onbld - illumos-gate - Gitiles

 .\"
 .\" 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.
	.\"
	.\" 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.