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.man.txt
+++ new/usr/src/tools/cw/cw.1onbld.man.txt
1 1 CW(1ONBLD) illumos Build Tools CW(1ONBLD)
2 2
3 -
4 -
5 3 NAME
6 - cw - invoke one or more compilers with argument translation
4 + cw - invoke one or more compilers with argument translation
7 5
8 6 SYNOPSIS
9 - cw {-_cc|-_gcc|-_CC|-_g++} [options] [compiler args...]
7 + cw [-C] [--versions] [--noecho] --primary compiler
8 + [--shadow compiler ...] -- compiler args ...
10 9
11 10 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.
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.
19 18
20 19 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.
20 + Both the --primary and --secondary parameters take a compiler
21 + specification. This is a comma-separated list of the form
22 + name,executable,style Where name is a name for the compiler, executable
23 + is the full path to the compiler executable, and style is the style of
24 + command-line options the 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++=.
58 61
59 62 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.
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 none of -c, -E, -P, or -S appears in the argument list (that is,
68 + linking is attempted), the shadow compilers will not be invoked.
69 + This is because the objects built with that compiler which would be
70 + linked have been previously discarded.
71 +
72 + 2. If an option of the form -o filename was provided, it will be
73 + replaced by two options of the form -o tempfile
74 +
75 + 3. If the option -o was not provided, -o tempfile will be added to the
76 + end of the argument list used to invoke the shadow compilers.
77 + When shadow compilation is in effect, cw writes to standard error each
78 + compiler's standard error output following its argument list. Messages
79 + from the compilers will not be interleaved. If cw is used to invoke the
80 + preprocessor and no output location is specified, cw will write to
81 + standard output the primary compiler's standard output, and the secondary
82 + compiler's standard output will be discarded.
83 +
84 + Because the Sun compilers write intermediate objects to fixed filenames
85 + in the current directory when instructed to compile and link multiple
86 + source files via a single command line, it would be unsafe to invoke more
87 + than one compiler in this fashion. Therefore cw does not accept multiple
88 + source files unless the preprocessor is to be invoked. An attempt to
89 + invoke cw in this manner will result in an error.
100 90
101 91 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.
92 + If the compiler to be invoked is a GNU-style C or C++ compiler, a set of
93 + default flags is added to the beginning of the argument list, and the
94 + remaining arguments are translated to their closest appropriate semantic
95 + equivalents and passed in the same order as their counterparts given to
96 + cw. See the comments at the head of usr/src/tools/cw/cw.c for a detailed
97 + list of translations.
125 98
126 99 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.
100 + CW_SHADOW_SERIAL
101 + If this variable is set in the environment, invoke the primary
102 + compiler, wait for it to complete, then invoke the shadow
103 + compilers. Normally the primary and shadow compilers are invoked
104 + in parallel.
105 +
106 + CW_NO_EXEC
107 + If this variable is set in the environment, write the usual
108 + output to standard error but do not actually invoke any compiler.
109 + This is useful for debugging the translation engine.
172 110
173 111 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.
112 + The following exit status values are returned:
178 113
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.
114 + 0 The primary compiler, and shadow compilers if invoked, both
115 + completed successfully.
185 116
186 - Additional compiler types should be supported.
187 -
188 - The translation engine is hacky.
117 + >0 A usage error occurred, or one or more compilers returned a
118 + nonzero exit status.
189 119
190 120 SEE ALSO
191 - cc(1), CC(1), gcc(1)
121 + cc(1), CC(1), gcc(1)
122 +
123 +BUGS
124 + The translations provided for gcc are not always exact and in some cases
125 + reflect local policy rather than actual equivalence.
192 126
127 + Additional compiler types should be supported.
193 128
129 + The translation engine is hacky.
194 130
195 - March 22, 2010 CW(1ONBLD)
131 +illumos February 10, 2018 illumos
XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX