9899 cw(1onbld) should shadow more compilation

          --- old/usr/src/tools/cw/cw.1onbld.man.txt
          +++ new/usr/src/tools/cw/cw.1onbld.man.txt

   1    1  CW(1ONBLD)                    illumos Build Tools                   CW(1ONBLD)
   2    2  
   3    3  NAME
   4    4       cw - invoke one or more compilers with argument translation
   5    5  
   6    6  SYNOPSIS
   7    7       cw [-C] [--versions] [--noecho] --primary compiler
   8    8          [--shadow compiler ...] -- compiler args ...
   9    9  
  10   10  DESCRIPTION
  11   11       cw is a facility for invoking one or more compilers, providing
  12   12       translation from Sun style arguments as appropriate.  This allows the use
  13   13       of arbitrary compilers without the need to alter large numbers of
  14   14       makefiles.  A mode called shadow compilation invokes multiple compilers
  15   15       so that warnings and errors may be obtained from all of them.  See SHADOW
  16   16       COMPILATION for details.  This version of cw supports compilers with both
  17   17       Sun Studio 12 and GCC-style command lines.
  18   18  
  19   19  ARGUMENTS
  20   20       Both the --primary and --shadow parameters take a compiler specification.
  21   21       This is a comma-separated list of the form name,executable,style Where
  22   22       name is a name for the compiler, executable is the full path to the
  23   23       compiler executable, and style is the style of command-line options the
  24   24       compiler expects, either sun or gnu.
  25   25  
  26   26       --primary compiler
  27   27               Specify the compiler to be used primarily (that which is used for
  28   28               link-editing and pre-processing, and whos objects we deliver).
  29   29  
  30   30       --shadow compiler
  31   31               Specify a shadow compiler, which builds sources for the sake of
  32   32               checking code quality and compatibility, but has its output
  33   33               discarded.
  34   34  
  35   35       --noecho
  36   36               Do not echo the actual command line of any compilers invoked.
  37   37  
  38   38       --versions
  39   39               Request from each configured primary and shadow compiler its
  40   40               version information.
  41   41  
  42   42       -C      The sources being compiled are C++.  This is necessary as it
  43   43               affects the translation of compiler arguments.
  44   44  
  45   45       --      Arguments intended for the compilers themselves must be separated
  46   46               from those of cw by a --.
  47   47  
  48   48       -_name=
  49   49  
  50   50       -_style=
  51   51               Parameters intended for the compiler be guarded with options of
  52   52               the form -_name= and -_style= Where name and style are those
  53   53               passed to --primary and --shadow this allows certain flags to be
  54   54               passed only to certain classes of compiler.
  55   55  
  56   56               For historical reasons, the -_style= option is also translated

  57   57               such that a style of sun may use the flag -_cc= and a style of
  58   58               gnu may use the flag -_gcc=, and when the -C option is given and
  59   59               C++ is in use the style of sun may use the flag -_CC= and the
  60   60               style of gnu may use the flag -_g++=.
  61   61  
  62   62  SHADOW COMPILATION
  63   63       If --shadow compilers are specified cw will invoke each shadow compiler,
  64   64       with the outputs modified (as well as any translation for compiler style)
  65   65       as follows:
  66   66  
  67      -     1.   If neither of -c, -S appears in the argument list (that is, linking
  68      -          is attempted or only the pre-processor is invoked), the shadow
  69      -          compilers will not be invoked.
       67 +     1.   If cw is invoked to link-edit without compilation (the input files
       68 +          are all objects), the shadow compiler is not invoked.
  70   69  
  71   70       2.   If the -o filename option was provided, with or without a separating
  72   71            space, it will be replaced with -o tempfile
  73   72  
  74   73       3.   If the option -o was not provided, -o tempfile will be added to the
  75   74            end of the argument list used to invoke the shadow compilers.
  76   75       When shadow compilation is in effect, cw writes to standard error each
  77   76       compiler's standard error output following its argument list.  Messages
  78   77       from the compilers will not be interleaved.  If cw is used to invoke the
  79   78       preprocessor and no output location is specified, cw will write to

  80   79       standard output the primary compiler's standard output.
  81   80  
  82   81       Because the Sun compilers write intermediate objects to fixed filenames
  83   82       in the current directory when instructed to compile and link multiple
  84   83       source files via a single command line, it would be unsafe to invoke more
  85   84       than one compiler in this fashion.  Therefore cw does not accept multiple
  86   85       source files unless the preprocessor is to be invoked.  An attempt to
  87   86       invoke cw in this manner will result in an error.
  88   87  
  89   88  ARGUMENT TRANSLATION
  90   89       If the compiler to be invoked is a GNU-style C or C++ compiler, a set of
  91   90       default flags is added to the beginning of the argument list, and the
  92   91       remaining arguments are translated to their closest appropriate semantic
  93   92       equivalents and passed in the same order as their counterparts given to
  94   93       cw.  See the comments at the head of usr/src/tools/cw/cw.c for a detailed
  95   94       list of translations.
  96   95  
  97   96  ENVIRONMENT
  98   97       CW_SHADOW_SERIAL
  99   98               If this variable is set in the environment, invoke the primary
 100   99               compiler, wait for it to complete, then invoke the shadow
 101  100               compilers.  Normally the primary and shadow compilers are invoked
 102  101               in parallel.
 103  102  
 104  103       CW_NO_EXEC
 105  104               f this variable is set in the environment, write the usual output
 106  105               to standard error but do not actually invoke any compiler.  This
 107  106               is useful for debugging the translation engine.
 108  107  
 109  108  EXIT STATUS
 110  109       The following exit status values are returned:
 111  110  
 112  111       0       The primary compiler, and shadow compilers if invoked, all
 113  112               completed successfully.
 114  113  
 115  114       >0      A usage error occurred, or one or more compilers returned a
 116  115               nonzero exit status.
 117  116  
 118  117  SEE ALSO
 119  118       cc(1), CC(1), gcc(1)
 120  119  
 121  120  BUGS
 122  121       The translations provided for gcc are not always exact and in some cases
 123  122       reflect local policy rather than actual equivalence.
 124  123  
 125  124       Additional compiler types should be supported.
 126  125  
 127  126       The translation engine is hacky.
 128  127  
 129  128  illumos                        September 4, 2018                       illumos

XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX