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 .\" Copyright 2018 Joyent, Inc.
  25 .\"
  26 .Dd September 4, 2018
  27 .Dt CW 1ONBLD
  28 .Os
  29 .Sh NAME
  30 .Nm cw
  31 .Nd invoke one or more compilers with argument translation
  32 .Sh SYNOPSIS
  33 .Nm cw
  34 .Op Fl C
  35 .Op Fl -versions
  36 .Op Fl -noecho
  37 .Fl -primary Ar compiler
  38 .Op Fl -shadow Ar compiler ...
  39 .Fl -
  40 .Ar compiler args ...
  41 .Sh DESCRIPTION
  42 .Nm cw
  43 is a facility for invoking one or more compilers, providing translation from
  44 Sun style arguments as appropriate.
  45 This allows the use of arbitrary compilers without the need to alter large
  46 numbers of makefiles.
  47 A mode called shadow compilation invokes multiple compilers so that warnings
  48 and errors may be obtained from all of them.
  49 See
  50 .Sx SHADOW COMPILATION
  51 for details.
  52 This version of cw supports compilers with both Sun Studio 12 and GCC-style
  53 command lines.
  54 .Sh ARGUMENTS
  55 Both the
  56 .Fl -primary
  57 and
  58 .Fl -shadow
  59 parameters take a
  60 .Em compiler specification .
  61 This is a comma-separated list of the form
  62 .Ar name,executable,style
  63 Where
  64 .Ar name
  65 is a name for the compiler,
  66 .Ar executable
  67 is the full path to the compiler executable, and
  68 .Ar style
  69 is the style of command-line options the compiler expects, either
  70 .Em sun
  71 or
  72 .Em gnu .
  73 .Bl -tag -width indent
  74 .It Fl -primary Ar compiler
  75 Specify the compiler to be used primarily (that which is used for link-editing
  76 and pre-processing, and whos objects we deliver).
  77 .It Fl -shadow Ar compiler
  78 Specify a shadow compiler, which builds sources for the sake of checking code
  79 quality and compatibility, but has its output discarded.
  80 .It Fl -noecho
  81 Do not echo the actual command line of any compilers invoked.
  82 .It Fl -versions
  83 Request from each configured primary and shadow compiler its version
  84 information.
  85 .It Fl C
  86 The sources being compiled are C++.  This is necessary as it affects the
  87 translation of compiler arguments.
  88 .It Fl -
  89 Arguments intended for the compilers themselves must be separated from those
  90 of
  91 .Nm cw
  92 by a
  93 .Fl - .
  94 .It Fl _name=
  95 .It Fl _style=
  96 Parameters intended for the compiler be guarded with options of the form
  97 .Fl _name=
  98 and
  99 .Fl _style=
 100 Where
 101 .Em name
 102 and
 103 .Em style
 104 are those passed to
 105 .Fl -primary
 106 and
 107 .Fl -shadow
 108 this allows certain flags to be passed only to certain classes of compiler.
 109 .Pp
 110 For historical reasons, the
 111 .Fl _style=
 112 option is also translated such that a style of
 113 .Em sun
 114 may use the flag
 115 .Fl _cc=
 116 and a style of
 117 .Em gnu
 118 may use the flag
 119 .Fl _gcc= ,
 120 and when the
 121 .Fl C
 122 option is given and C++ is in use the style of
 123 .Em sun
 124 may use the flag
 125 .Fl _CC=
 126 and the style of
 127 .Em gnu
 128 may use the flag
 129 .Fl _g++= .
 130 .El
 131 .Sh SHADOW COMPILATION
 132 If
 133 .Fl -shadow
 134 compilers are specified
 135 .Nm cw
 136 will invoke each shadow compiler, with the outputs modified (as well as any
 137 translation for compiler style) as follows:
 138 .Bl -enum
 139 .It
 140 If neither of
 141 .Fl c ,
 142 .Fl S
 143 appears in the argument list (that is, linking is attempted or only the
 144 pre-processor is invoked), the shadow compilers will not be invoked.
 145 .It
 146 If the
 147 .Fl o Ar filename
 148 option was provided, with or without a separating space, it will be replaced with
 149 .Fl o Ar tempfile
 150 .It
 151 If the option
 152 .Fl o
 153 was not provided,
 154 .Fl o Ar tempfile
 155 will be added to the end of the argument list used to invoke
 156 the shadow compilers.
 157 .El
 158 When shadow compilation is in effect,
 159 .Nm cw
 160 writes to standard error each compiler's standard error output following its
 161 argument list.
 162 Messages from the compilers will not be interleaved.
 163 If
 164 .Nm cw
 165 is used to invoke the preprocessor and no output location is specified,
 166 .Nm cw
 167 will write to standard output the primary compiler's standard output.
 168 .Pp
 169 Because the Sun compilers write intermediate objects to fixed
 170 filenames in the current directory when instructed to compile and
 171 link multiple source files via a single command line, it would be
 172 unsafe to invoke more than one compiler in this fashion.
 173 Therefore
 174 .Nm cw
 175 does not accept multiple source files unless the preprocessor is to be
 176 invoked.
 177 An attempt to invoke
 178 .Nm cw
 179 in this manner will result in an error.
 180 .Sh ARGUMENT TRANSLATION
 181 If the compiler to be invoked is a GNU-style C or C++ compiler, a set of
 182 default flags is added to the beginning of the argument list, and the
 183 remaining arguments are translated to their closest appropriate
 184 semantic equivalents and passed in the same order as their
 185 counterparts given to
 186 .Nm cw .
 187 See the comments at the head of
 188 .Pa usr/src/tools/cw/cw.c
 189 for a detailed list of translations.
 190 .Sh ENVIRONMENT
 191 .Bl -tag -width indent
 192 .It CW_SHADOW_SERIAL
 193 If this variable is set in the environment, invoke the primary compiler, wait
 194 for it to complete, then invoke the shadow compilers.
 195 Normally the primary and shadow compilers are invoked in parallel.
 196 .It CW_NO_EXEC
 197 f this variable is set in the environment, write the usual output to
 198 standard error but do not actually invoke any compiler.
 199 This is useful for debugging the translation engine.
 200 .El
 201 .Sh EXIT STATUS
 202 The following exit status values are returned:
 203 .Bl -tag -width indent
 204 .It 0
 205 The primary compiler, and shadow compilers if invoked, all completed
 206 successfully.
 207 .It >0
 208 A usage error occurred, or one or more compilers returned a nonzero
 209 exit status.
 210 .El
 211 .Sh SEE ALSO
 212 .Xr cc 1 ,
 213 .Xr CC 1 ,
 214 .Xr gcc 1
 215 .Sh BUGS
 216 The translations provided for gcc are not always exact and in some cases
 217 reflect local policy rather than actual equivalence.
 218 .Pp
 219 Additional compiler types should be supported.
 220 .Pp
 221 The translation engine is hacky.