4 .\" The contents of this file are subject to the terms of the
   5 .\" Common Development and Distribution License (the "License").
   6 .\" You may not use this file except in compliance with the License.
   7 .\"
   8 .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE
   9 .\" or http://www.opensolaris.org/os/licensing.
  10 .\" See the License for the specific language governing permissions
  11 .\" and limitations under the License.
  12 .\"
  13 .\" When distributing Covered Code, include this CDDL HEADER in each
  14 .\" file and include the License file at usr/src/OPENSOLARIS.LICENSE.
  15 .\" If applicable, add the following below this CDDL HEADER, with the
  16 .\" fields enclosed by brackets "[]" replaced with your own identifying
  17 .\" information: Portions Copyright [yyyy] [name of copyright owner]
  18 .\"
  19 .\" CDDL HEADER END
  20 .\"
  21 .\" Copyright 2010 Sun Microsystems, Inc.  All rights reserved.
  22 .\" Use is subject to license terms.
  23 .\"
  24 .TH CW 1ONBLD "Mar 22, 2010"
  25 .SH NAME
  26 .I cw
  27 \- invoke one or more compilers with argument translation
  28 .SH SYNOPSIS
  29 \fBcw {-_cc|-_gcc|-_CC|-_g++} [options] [compiler args...]\fP
  30 .SH DESCRIPTION
  31 .LP
  32 .I cw
  33 is a facility for invoking one or more compilers, providing
  34 translation from Sun Studio arguments as appropriate.  This allows
  35 the use of arbitrary compilers without the need to alter large
  36 numbers of makefiles.  A mode called shadow compilation, the default,
  37 invokes two different compilers so that warnings and errors may be
  38 obtained from both.  See SHADOW COMPILATION for details.  This version
  39 of cw supports Sun Studio 10 and 11 and gcc 3.4.3 as shipped in
  40 Solaris.
  41 .SH ARGUMENTS
  42 .LP
  43 Exactly one of the following arguments is required, and must appear
  44 immediately following \fBcw\fP in the argument list:
  45 .TP 4
  46 .B \-_cc
  47 Select Sun Studio C (cc) as the primary compiler.
  48 .TP 4
  49 .B \-_gcc
  50 Select GNU C (gcc) as the primary compiler.
  51 .TP 4
  52 .B \-_CC
  53 Select Sun Studio C++ (CC) as the primary compiler.
  54 .TP 4
  55 .B \-_g++
  56 Select GNU C++ (g++) as the primary compiler.
  57 .SH OPTIONS
  58 .LP
  59 The following options are supported:
  60 .TP 4
  61 .B \-_compiler
  62 Do not invoke any compiler; instead, write to standard output the
  63 full path to the primary compiler that would be invoked.  If this
  64 option is given, it must appear immediately following the compiler
  65 selection argument, and all other options will be disregarded.
  66 .TP 4
  67 .B \-_versions
  68 Print the cw version, followed in turn by the path to and versions
  69 of each compiler which would be invoked.  If this option is given,
  70 it must appear immediately following the compiler selection argument,
  71 and all other options will be disregarded.
  72 .TP 4
  73 .B \-_noecho
  74 Normally, cw writes to standard error the actual compiler commands
  75 invoked, each prefixed with '+'.  This option suppresses these
  76 messages.
  77 .TP 4
  78 .B \-_cc=,\-_gcc=,\-_CC=,\-g++=
  79 Pass compiler-dependent options.  See ARGUMENT TRANSLATION.
  80 .SH SHADOW COMPILATION
  81 .LP
  82 Unless otherwise directed by environment variables (see ENVIRONMENT),
  83 \fBcw\fP will invoke both the compiler specified by its first argument
  84 (primary) and a designated alternate compiler (shadow).  The primary
  85 compiler will be invoked with the arguments given to cw, translated
  86 as described in ARGUMENT TRANSLATION.  The secondary compiler will be
  87 invoked in parallel with the primary (but see ENVIRONMENT); its
  88 arguments will likewise be translated.  However, the shadow compiler's
  89 arguments will also be modified as follows:
  90 .TP 4
  91 .B 1.
  92 If none of \fI-c\fP, \fI-E\fP, \fI-P\fP, or \fI-S\fP appears in the
  93 argument list (that is, linking is attempted), the shadow compiler
  94 will not be invoked.  This is because the objects built with that
  95 compiler which would be linked have been previously discarded.
  96 .TP 4
  97 .B 2.
  98 If an option of the form \fI-ofilename\fP was provided, it will be
  99 replaced by two options of the form \fI-o\fP \fItempfile\fP.
 100 .TP 4
 101 .B 3.
 102 If the option \fI-o\fP was provided, its following argument will be
 103 replaced by \fItempfile\fP.
 104 .TP 4
 105 .B 4.
 106 If neither of the above options was provided, two options of the
 107 form \fI-o\fP \fItempfile\fP will be added to the end of the argument
 108 list used to invoke the shadow compiler.
 109 .LP
 110 In all three cases, \fItempfile\fP is the name of a temporary file
 111 which will be removed by \fBcw\fP before it terminates.
 112 .LP
 113 When shadow compilation is in effect, \fBcw\fP writes to standard error
 114 each compiler's standard error output following its argument list.
 115 Messages from the two compilers will not be interleaved.  If \fBcw\fP















































 116 is used to invoke the preprocessor and no output location is specified,
 117 \fBcw\fP will write to standard output the primary compiler's
 118 standard output, and the secondary compiler's standard output will
 119 be discarded.
 120 .LP
 121 Because the Studio compilers write intermediate objects to fixed
 122 filenames in the current directory when instructed to compile and
 123 link multiple source files via a single command line, it would be
 124 unsafe to invoke more than one compiler in this fashion.  Therefore
 125 \fBcw\fP does not accept multiple source files unless the
 126 preprocessor is to be invoked.  An attempt to invoke \fBcw\fP in
 127 this manner will result in an error.
 128 .SH ARGUMENT TRANSLATION
 129 .LP
 130 The arguments provided to \fBcw\fP will be passed through to each
 131 compiler invoked, altered as follows:
 132 .TP 4
 133 .B 1.
 134 Options intended for \fBcw\fP itself are removed.
 135 .TP 4
 136 .B 2.
 137 The shadow compiler's arguments are modified as described in
 138 SHADOW COMPILATION so that its output is discarded.
 139 .TP 4
 140 .B 3.
 141 If the compiler to be invoked is a GNU C or C++ compiler, a set of
 142 default flags is added to the beginning of the argument list, and the
 143 remaining arguments are translated to their closest appropriate
 144 semantic equivalents and passed in the same order as their
 145 counterparts given to \fBcw\fP.  Arguments which begin with
 146 \fI-_gcc=\fP or \fI-_g++=\fP will be passed in place with the
 147 leading portion removed.  Arguments which begin with \fI-_cc=\fP or
 148 \fI-_CC=\fP will be discarded.  See the comments at the head of
 149 \fIusr/src/tools/cw/cw.c\fP for a detailed list of translations.
 150 .TP 4
 151 .B 4.
 152 If the compiler to be invoked is a Studio C or C++ compiler, the
 153 remaining arguments are passed unmodified and in the same order as
 154 given to \fBcw\fP.  Arguments which begin with \fI-_cc=\fP or
 155 \fI-_CC=\fP will be passed in place with the leading portion removed.
 156 Arguments which begin with \fI-_gcc=\fP or \fI-_g++=\fP will be
 157 discarded.
 158 .SH ENVIRONMENT
 159 .TP 4
 160 .B CW_NO_SHADOW
 161 If this variable is set in the environment, invoke only the
 162 primary compiler.
 163 .TP 4
 164 .B CW_SHADOW_SERIAL
 165 If this variable is set in the environment, invoke the primary compiler,
 166 wait for it to complete, then invoke the shadow compiler.  Normally
 167 the two compilers are invoked in parallel.  If CW_NO_SHADOW is set,
 168 this has no effect.
 169 .TP 4
 170 .B CW_NO_EXEC
 171 If this variable is set in the environment, write the usual output to
 172 standard error but do not actually invoke any compiler.  This is
 173 useful for debugging the translation engine.
 174 .TP 4
 175 .B CW_CC, CW_CPLUSPLUS
 176 If these variables are set in the environment, they specify the full
 177 pathname for the Studio C and C++ compilers, respectively.
 178 .TP 4
 179 .B CW_CC_DIR, CW_CPLUSPLUS_DIR, SPRO_VROOT, SPRO_ROOT, BUILD_TOOLS
 180 If CW_CC or CW_CPLUSPLUS are not set,
 181 these variables define the search path for Studio compilers as
 182 follows:
 183 .B
 184 If CW_CC_DIR is set, the Studio C compiler in \fI$CW_CC_DIR\fP
 185 will be used.  Likewise, if CW_CPLUSPLUS_DIR is set, the Studio C++
 186 compiler in \fI$CW_CPLUSPLUS_DIR\fP will be used.
 187 Otherwise, if SPRO_VROOT is set, the Studio C and C++ compilers
 188 in \fI$SPRO_VROOT/bin\fP will be used.
 189 Otherwise, if SPRO_ROOT is set, the Studio C and C++ compilers
 190 in \fI$SPRO_ROOT/SS12/bin\fP will be used.
 191 Otherwise, if BUILD_TOOLS is set, the Studio C and C++ compilers
 192 in \fI$BUILD_TOOLS/SUNWspro/SS12/bin\fP will be used.
 193 Otherwise, the Studio compilers in a predefined default location
 194 will be used.
 195 .TP 4
 196 .B CW_GCC, CW_GPLUSPLUS
 197 If these variables are set in the environment, they specify the full
 198 pathname for the GNU C and C++ compilers, respectively.
 199 .TP 4
 200 .B CW_GCC_DIR, CW_GPLUSPLUS_DIR, GNU_ROOT
 201 If CW_GCC or CW_GPLUSPLUS are not set,
 202 these variables alter the search path for GNU compilers in a manner
 203 similar to that described above for the Studio compilers.  Specifically:
 204 .B
 205 If CW_GCC_DIR is set, the GNU C compiler in \fI$CW_GCC_DIR\fP
 206 will be used.  Likewise, if CW_GPLUSPLUS_DIR is set, the GNU C++
 207 compiler in \fI$CW_GPLUSPLUS_DIR\fP will be used.
 208 Otherwise, if GNU_ROOT is set, the GNU C and C++ compilers
 209 in \fI$GCC_ROOT/bin\fP will be used.
 210 Otherwise, the GNU compilers in a predefined default location
 211 will be used.
 212 .SH EXIT STATUS
 213 .LP
 214 The following exit status values are returned:
 215 .IP "\fB0\fR" 4
 216 The primary compiler, and shadow compiler if invoked, both completed

 217 successfully.
 218 .IP "\fB>0\fR" 4
 219 A usage error occurred, or one or more compilers returned a nonzero
 220 exit status.
 221 .SH BUGS
 222 .LP
 223 The translations provided for gcc are not always exact and in some
 224 cases reflect local ON policy rather than actual equivalence.
 225 .LP




 226 Additional compiler types should be supported.
 227 .LP
 228 The translation engine is hacky.
 229 .SH SEE ALSO
 230 .LP
 231 cc(1), CC(1), gcc(1)

   4 .\" The contents of this file are subject to the terms of the
   5 .\" Common Development and Distribution License (the "License").
   6 .\" You may not use this file except in compliance with the License.
   7 .\"
   8 .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE
   9 .\" or http://www.opensolaris.org/os/licensing.
  10 .\" See the License for the specific language governing permissions
  11 .\" and limitations under the License.
  12 .\"
  13 .\" When distributing Covered Code, include this CDDL HEADER in each
  14 .\" file and include the License file at usr/src/OPENSOLARIS.LICENSE.
  15 .\" If applicable, add the following below this CDDL HEADER, with the
  16 .\" fields enclosed by brackets "[]" replaced with your own identifying
  17 .\" information: Portions Copyright [yyyy] [name of copyright owner]
  18 .\"
  19 .\" CDDL HEADER END
  20 .\"
  21 .\" Copyright 2010 Sun Microsystems, Inc.  All rights reserved.
  22 .\" Use is subject to license terms.
  23 .\"
  24 .Dd February 10, 2018
  25 .Dt CW 1ONBLD
  26 .Os
  27 .Sh NAME
  28 .Nm cw
  29 .Nd invoke one or more compilers with argument translation
  30 .Sh SYNOPSIS
  31 .Nm cw
  32 .Op Fl C
  33 .Op Fl -versions
  34 .Op Fl -noecho
  35 .Fl -primary Ar compiler
  36 .Op Fl -shadow Ar compiler ...
  37 .Fl -
  38 .Ar compiler args ...
  39 .Sh DESCRIPTION
  40 .Nm cw
  41 is a facility for invoking one or more compilers, providing translation from
  42 Sun style arguments as appropriate.
  43 This allows the use of arbitrary compilers without the need to alter large
  44 numbers of makefiles.
  45 A mode called shadow compilation invokes multiple compilers so that warnings
  46 and errors may be obtained from both.
  47 See
  48 .Sx SHADOW COMPILATION
  49 for details.
  50 This version of cw supports compilers with both Sun Studio 12 and GCC-style
  51 command lines.
  52 .Sh ARGUMENTS
  53 Both the
  54 .Fl -primary
  55 and
  56 .Fl -shadow
  57 parameters take a
  58 .Em compiler specification .
  59 This is a comma-separated list of the form
  60 .Ar name,executable,style
  61 Where
  62 .Ar name
  63 is a name for the compiler,
  64 .Ar executable
  65 is the full path to the compiler executable, and
  66 .Ar style
  67 is the style of command-line options the compiler expects, either
  68 .Em sun
  69 or
  70 .Em gnu .
  71 .Bl -tag -width indent
  72 .It Fl -primary Ar compiler
  73 Specify the compiler to be used primarily (that which is used for link-editing
  74 and pre-processing, and whos objects we deliver).
  75 .It Fl -shadow Ar compiler
  76 Specify a shadow compiler, which builds sources for the sake of checking code
  77 quality and compatibility, but has its output discarded.
  78 .It Fl -noecho
  79 Do not echo the actual command line of any compilers invoked.
  80 .It Fl -versions
  81 Request from each configured primary and shadow compiler its version
  82 information.
  83 .It Fl C
  84 The sources being compiled are C++.  This is necessary as it affects the
  85 translation of compiler arguments.
  86 .It Fl -
  87 Arguments intended for the compilers themselves must be separated from those
  88 of
  89 .Nm cw
  90 by a
  91 .Fl - .
  92 .It Fl _name=
  93 .It Fl _style=
  94 Parameters intended for the compiler be guarded with options of the form
  95 .Fl _name=
  96 and
  97 .Fl _style=
  98 Where
  99 .Em name
 100 and
 101 .Em style
 102 are those passed to
 103 .Fl -primary
 104 and
 105 .Fl -shadow
 106 this allows certain flags to be passed only to certain classes of compiler.
 107 .Pp
 108 For historical reasons, the
 109 .Fl _style=
 110 option is also translated such that a style of
 111 .Em sun
 112 may use the flag
 113 .Fl _cc=
 114 and a style of
 115 .Em gnu
 116 may use the flag
 117 .Fl _gcc= ,
 118 and when the
 119 .Fl C
 120 option is given and C++ is in use the style of
 121 .Em sun
 122 may use the flag
 123 .Fl _CC=
 124 and the style of
 125 .Em gnu
 126 may use the flag
 127 .Fl _g++= .
 128 .El
 129 .Sh SHADOW COMPILATION
 130 If
 131 .Fl -shadow
 132 compilers are specified
 133 .Nm cw
 134 will invoke shadow compiler, with the outputs modified (as well as any
 135 translation for compiler style) as follows:
 136 .Bl -enum
 137 .It
 138 If neither of 
 139 .Fl c ,
 140 .Fl S
 141 appears in the argument list (that is, linking is attempted or only the
 142 pre-processor is invoked), the shadow compilers will not be invoked.
 143 .It
 144 If the
 145 .Fl o Ar filename
 146 option was provided, with or without a separating space, it will be replaced with
 147 .Fl o Ar tempfile
 148 .It
 149 If the option
 150 .Fl o
 151 was not provided,
 152 .Fl o Ar tempfile
 153 will be added to the end of the argument list used to invoke
 154 the shadow compilers.
 155 .El
 156 When shadow compilation is in effect,
 157 .Nm cw
 158 writes to standard error each compiler's standard error output following its
 159 argument list.
 160 Messages from the compilers will not be interleaved.
 161 If
 162 .Nm cw
 163 is used to invoke the preprocessor and no output location is specified,
 164 .Nm cw
 165 will write to standard output the primary compiler's standard output.
 166 .Pp
 167 Because the Sun compilers write intermediate objects to fixed

 168 filenames in the current directory when instructed to compile and
 169 link multiple source files via a single command line, it would be
 170 unsafe to invoke more than one compiler in this fashion.
 171 Therefore
 172 .Nm cw
 173 does not accept multiple source files unless the preprocessor is to be
 174 invoked.
 175 An attempt to invoke
 176 .Nm cw
 177 in this manner will result in an error.
 178 .Sh ARGUMENT TRANSLATION
 179 If the compiler to be invoked is a GNU-style C or C++ compiler, a set of








 180 default flags is added to the beginning of the argument list, and the
 181 remaining arguments are translated to their closest appropriate
 182 semantic equivalents and passed in the same order as their
 183 counterparts given to
 184 .Nm cw .
 185 See the comments at the head of
 186 .Pa usr/src/tools/cw/cw.c
 187 for a detailed list of translations.
 188 .Sh ENVIRONMENT
 189 .Bl -tag -width indent
 190 .It CW_SHADOW_SERIAL
 191 If this variable is set in the environment, invoke the primary compiler, wait
 192 for it to complete, then invoke the shadow compilers.
 193 Normally the primary and shadow compilers are invoked in parallel.
 194 .It CW_NO_EXEC














 195 If this variable is set in the environment, write the usual output to
 196 standard error but do not actually invoke any compiler.
 197 This is useful for debugging the translation engine.
 198 .El
 199 .Sh EXIT STATUS






































 200 The following exit status values are returned:
 201 .Bl -tag -width indent
 202 .It 0
 203 The primary compiler, and shadow compilers if invoked, both completed
 204 successfully.
 205 .It >0
 206 A usage error occurred, or one or more compilers returned a nonzero
 207 exit status.
 208 .El
 209 .Sh SEE ALSO
 210 .Xr cc 1 ,
 211 .Xr CC 1 ,
 212 .Xr gcc 1
 213 .Sh BUGS
 214 The translations provided for gcc are not always exact and in some cases
 215 reflect local policy rather than actual equivalence.
 216 .Pp
 217 Additional compiler types should be supported.
 218 .Pp
 219 The translation engine is hacky.