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