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