Print this page
cw: give cw(1onbld) a new interface allowing for multiple arbitrary shadows

Split Close
Expand all
Collapse all
          --- old/usr/src/tools/cw/cw.1onbld
          +++ new/usr/src/tools/cw/cw.1onbld
↓ open down ↓ 13 lines elided ↑ open up ↑
  14   14  .\" file and include the License file at usr/src/OPENSOLARIS.LICENSE.
  15   15  .\" If applicable, add the following below this CDDL HEADER, with the
  16   16  .\" fields enclosed by brackets "[]" replaced with your own identifying
  17   17  .\" information: Portions Copyright [yyyy] [name of copyright owner]
  18   18  .\"
  19   19  .\" CDDL HEADER END
  20   20  .\"
  21   21  .\" Copyright 2010 Sun Microsystems, Inc.  All rights reserved.
  22   22  .\" Use is subject to license terms.
  23   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
       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 an option of the form
      148 +.Fl o Ar filename
      149 +was provided, it will be replaced by two options of the form
      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
 116  166  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
      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
 122  172  filenames in the current directory when instructed to compile and
 123  173  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
      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
 142  184  default flags is added to the beginning of the argument list, and the
 143  185  remaining arguments are translated to their closest appropriate
 144  186  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
      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
 171  199  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
      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
 214  204  The following exit status values are returned:
 215      -.IP "\fB0\fR" 4
 216      -The primary compiler, and shadow compiler if invoked, both completed
      205 +.Bl -tag -width indent
      206 +.It 0
      207 +The primary compiler, and shadow compilers if invoked, both completed
 217  208  successfully.
 218      -.IP "\fB>0\fR" 4
      209 +.It >0
 219  210  A usage error occurred, or one or more compilers returned a nonzero
 220  211  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
      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
 226  221  Additional compiler types should be supported.
 227      -.LP
      222 +.Pp
 228  223  The translation engine is hacky.
 229      -.SH SEE ALSO
 230      -.LP
 231      -cc(1), CC(1), gcc(1)
    
XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX