1 .\"
   2 .\" CDDL HEADER START
   3 .\"
   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.