Print this page
9128 cw(1onbld) should be able to run multiple shadows
9129 file-locking tests shouldn't build multiple source files in one compiler invocation
9130 DTrace tst.gcc.d isn't useful
9132 cw(1onbld) shouldn't shadow pure preprocessing
Reviewed by: Toomas Soome <tsoome@me.com>
Reviewed? by: Yuri Pankov <yuripv@yuripv.net>
Reviewed? by: Robert Mustacchi <rm@joyent.com>
Reviewed? by: Jason King <jason.king@joyent.com>
   1 CW(1ONBLD)                    illumos Build Tools                   CW(1ONBLD)
   2 
   3 
   4 
   5 NAME
   6        cw - invoke one or more compilers with argument translation
   7 
   8 SYNOPSIS
   9        cw {-_cc|-_gcc|-_CC|-_g++} [options] [compiler args...]

  10 
  11 DESCRIPTION
  12        cw is a facility for invoking one or more compilers, providing
  13        translation from Sun Studio arguments as appropriate.  This allows the
  14        use of arbitrary compilers without the need to alter large numbers of
  15        makefiles.  A mode called shadow compilation, the default, invokes two
  16        different compilers so that warnings and errors may be obtained from
  17        both.  See SHADOW COMPILATION for details.  This version of cw supports
  18        Sun Studio 10 and 11 and gcc 3.4.3 as shipped in Solaris.
  19 
  20 ARGUMENTS
  21        Exactly one of the following arguments is required, and must appear
  22        immediately following cw in the argument list:
  23 
  24        -_cc
  25            Select Sun Studio C (cc) as the primary compiler.
  26 
  27        -_gcc
  28            Select GNU C (gcc) as the primary compiler.
  29 
  30        -_CC
  31            Select Sun Studio C++ (CC) as the primary compiler.
  32 
  33        -_g++
  34            Select GNU C++ (g++) as the primary compiler.
  35 
  36 OPTIONS
  37        The following options are supported:
  38 
  39        -_compiler
  40            Do not invoke any compiler; instead, write to standard output the
  41            full path to the primary compiler that would be invoked.  If this
  42            option is given, it must appear immediately following the compiler
  43            selection argument, and all other options will be disregarded.
  44 
  45        -_versions
  46            Print the cw version, followed in turn by the path to and versions
  47            of each compiler which would be invoked.  If this option is given,
  48            it must appear immediately following the compiler selection
  49            argument, and all other options will be disregarded.
  50 
  51        -_noecho
  52            Normally, cw writes to standard error the actual compiler commands
  53            invoked, each prefixed with '+'.  This option suppresses these
  54            messages.
  55 
  56        -_cc=,-_gcc=,-_CC=,-g++=
  57            Pass compiler-dependent options.  See ARGUMENT TRANSLATION.




  58 
  59 SHADOW COMPILATION
  60        Unless otherwise directed by environment variables (see ENVIRONMENT),
  61        cw will invoke both the compiler specified by its first argument
  62        (primary) and a designated alternate compiler (shadow).  The primary
  63        compiler will be invoked with the arguments given to cw, translated as
  64        described in ARGUMENT TRANSLATION.  The secondary compiler will be
  65        invoked in parallel with the primary (but see ENVIRONMENT); its
  66        arguments will likewise be translated.  However, the shadow compiler's
  67        arguments will also be modified as follows:
  68 
  69        1.  If none of -c, -E, -P, or -S appears in the argument list (that is,
  70            linking is attempted), the shadow compiler will not be invoked.
  71            This is because the objects built with that compiler which would be
  72            linked have been previously discarded.
  73 
  74        2.  If an option of the form -ofilename was provided, it will be
  75            replaced by two options of the form -o tempfile.
  76 
  77        3.  If the option -o was provided, its following argument will be
  78            replaced by tempfile.
  79 
  80        4.  If neither of the above options was provided, two options of the
  81            form -o tempfile will be added to the end of the argument list used
  82            to invoke the shadow compiler.
  83 
  84        In all three cases, tempfile is the name of a temporary file which will
  85        be removed by cw before it terminates.
  86 


  87        When shadow compilation is in effect, cw writes to standard error each
  88        compiler's standard error output following its argument list.  Messages
  89        from the two compilers will not be interleaved.  If cw is used to
  90        invoke the preprocessor and no output location is specified, cw will
  91        write to standard output the primary compiler's standard output, and
  92        the secondary compiler's standard output will be discarded.
  93 
  94        Because the Studio compilers write intermediate objects to fixed
  95        filenames in the current directory when instructed to compile and link
  96        multiple source files via a single command line, it would be unsafe to
  97        invoke more than one compiler in this fashion.  Therefore cw does not
  98        accept multiple source files unless the preprocessor is to be invoked.
  99        An attempt to invoke cw in this manner will result in an error.
 100 
 101 ARGUMENT TRANSLATION
 102        The arguments provided to cw will be passed through to each compiler
 103        invoked, altered as follows:
 104 
 105        1.  Options intended for cw itself are removed.
 106 
 107        2.  The shadow compiler's arguments are modified as described in SHADOW
 108            COMPILATION so that its output is discarded.
 109 
 110        3.  If the compiler to be invoked is a GNU C or C++ compiler, a set of
 111            default flags is added to the beginning of the argument list, and
 112            the remaining arguments are translated to their closest appropriate
 113            semantic equivalents and passed in the same order as their
 114            counterparts given to cw.  Arguments which begin with -_gcc= or
 115            -_g++= will be passed in place with the leading portion removed.
 116            Arguments which begin with -_cc= or -_CC= will be discarded.  See
 117            the comments at the head of usr/src/tools/cw/cw.c for a detailed
 118            list of translations.
 119 
 120        4.  If the compiler to be invoked is a Studio C or C++ compiler, the
 121            remaining arguments are passed unmodified and in the same order as
 122            given to cw.  Arguments which begin with -_cc= or -_CC= will be
 123            passed in place with the leading portion removed.  Arguments which
 124            begin with -_gcc= or -_g++= will be discarded.
 125 
 126 ENVIRONMENT
 127        CW_NO_SHADOW
 128            If this variable is set in the environment, invoke only the primary
 129            compiler.
 130 
 131        CW_SHADOW_SERIAL
 132            If this variable is set in the environment, invoke the primary
 133            compiler, wait for it to complete, then invoke the shadow compiler.
 134            Normally the two compilers are invoked in parallel.  If
 135            CW_NO_SHADOW is set, this has no effect.
 136 
 137        CW_NO_EXEC
 138            If this variable is set in the environment, write the usual output
 139            to standard error but do not actually invoke any compiler.  This is
 140            useful for debugging the translation engine.
 141 
 142        CW_CC, CW_CPLUSPLUS
 143            If these variables are set in the environment, they specify the
 144            full pathname for the Studio C and C++ compilers, respectively.
 145 
 146        CW_CC_DIR, CW_CPLUSPLUS_DIR, SPRO_VROOT, SPRO_ROOT, BUILD_TOOLS
 147            If CW_CC or CW_CPLUSPLUS are not set, these variables define the
 148            search path for Studio compilers as follows: If CW_CC_DIR is set,
 149            the Studio C compiler in $CW_CC_DIR will be used.  Likewise, if
 150            CW_CPLUSPLUS_DIR is set, the Studio C++ compiler in
 151            $CW_CPLUSPLUS_DIR will be used.  Otherwise, if SPRO_VROOT is set,
 152            the Studio C and C++ compilers in $SPRO_VROOT/bin will be used.
 153            Otherwise, if SPRO_ROOT is set, the Studio C and C++ compilers in
 154            $SPRO_ROOT/SS12/bin will be used.  Otherwise, if BUILD_TOOLS is
 155            set, the Studio C and C++ compilers in
 156            $BUILD_TOOLS/SUNWspro/SS12/bin will be used.  Otherwise, the Studio
 157            compilers in a predefined default location will be used.
 158 
 159        CW_GCC, CW_GPLUSPLUS
 160            If these variables are set in the environment, they specify the
 161            full pathname for the GNU C and C++ compilers, respectively.
 162 
 163        CW_GCC_DIR, CW_GPLUSPLUS_DIR, GNU_ROOT
 164            If CW_GCC or CW_GPLUSPLUS are not set, these variables alter the
 165            search path for GNU compilers in a manner similar to that described
 166            above for the Studio compilers.  Specifically: If CW_GCC_DIR is
 167            set, the GNU C compiler in $CW_GCC_DIR will be used.  Likewise, if
 168            CW_GPLUSPLUS_DIR is set, the GNU C++ compiler in $CW_GPLUSPLUS_DIR
 169            will be used.  Otherwise, if GNU_ROOT is set, the GNU C and C++
 170            compilers in $GCC_ROOT/bin will be used.  Otherwise, the GNU
 171            compilers in a predefined default location will be used.
 172 
 173 EXIT STATUS
 174        The following exit status values are returned:
 175 
 176        0   The primary compiler, and shadow compiler if invoked, both
 177            completed successfully.
 178 
 179        >0  A usage error occurred, or one or more compilers returned a nonzero
 180            exit status.



 181 
 182 BUGS
 183        The translations provided for gcc are not always exact and in some
 184        cases reflect local ON policy rather than actual equivalence.
 185 
 186        Additional compiler types should be supported.
 187 
 188        The translation engine is hacky.
 189 
 190 SEE ALSO
 191        cc(1), CC(1), gcc(1)
 192 
 193 
 194 
 195                                 March 22, 2010                      CW(1ONBLD)
   1 CW(1ONBLD)                    illumos Build Tools                   CW(1ONBLD)
   2 


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
















  70 
  71      2.   If the -o filename option was provided, with or without a separating
  72           space, it will be replaced with -o tempfile
  73 
  74      3.   If the option -o was not provided, -o tempfile will be added to the
  75           end of the argument list used to invoke the shadow compilers.
  76      When shadow compilation is in effect, cw writes to standard error each
  77      compiler's standard error output following its argument list.  Messages
  78      from the compilers will not be interleaved.  If cw is used to invoke the
  79      preprocessor and no output location is specified, cw will write to
  80      standard output the primary compiler's standard output.
  81 
  82      Because the Sun compilers write intermediate objects to fixed filenames
  83      in the current directory when instructed to compile and link multiple
  84      source files via a single command line, it would be unsafe to invoke more
  85      than one compiler in this fashion.  Therefore cw does not accept multiple
  86      source files unless the preprocessor is to be invoked.  An attempt to
  87      invoke cw in this manner will result in an error.

  88 
  89 ARGUMENT TRANSLATION
  90      If the compiler to be invoked is a GNU-style C or C++ compiler, a set of
  91      default flags is added to the beginning of the argument list, and the
  92      remaining arguments are translated to their closest appropriate semantic
  93      equivalents and passed in the same order as their counterparts given to
  94      cw.  See the comments at the head of usr/src/tools/cw/cw.c for a detailed











  95      list of translations.
  96 






  97 ENVIRONMENT




  98      CW_SHADOW_SERIAL
  99              If this variable is set in the environment, invoke the primary
 100              compiler, wait for it to complete, then invoke the shadow
 101              compilers.  Normally the primary and shadow compilers are invoked
 102              in parallel.
 103 
 104      CW_NO_EXEC
 105              If this variable is set in the environment, write the usual
 106              output to standard error but do not actually invoke any compiler.
 107              This is useful for debugging the translation engine.































 108 
 109 EXIT STATUS
 110      The following exit status values are returned:
 111 
 112      0       The primary compiler, and shadow compilers if invoked, both
 113              completed successfully.
 114 
 115      >0           A usage error occurred, or one or more compilers returned a
 116              nonzero exit status.
 117 
 118 SEE ALSO
 119      cc(1), CC(1), gcc(1)
 120 
 121 BUGS
 122      The translations provided for gcc are not always exact and in some cases
 123      reflect local policy rather than actual equivalence.
 124 
 125      Additional compiler types should be supported.
 126 
 127      The translation engine is hacky.
 128 
 129 illumos                        February 10, 2018                       illumos