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: Andy Fiddaman <omnios@citrus-it.net>
| 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 all of them. 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:
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.
23 25
24 - -_cc
25 - Select Sun Studio C (cc) as the primary compiler.
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).
26 29
27 - -_gcc
28 - Select GNU C (gcc) as the primary compiler.
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.
29 34
30 - -_CC
31 - Select Sun Studio C++ (CC) as the primary compiler.
35 + --noecho
36 + Do not echo the actual command line of any compilers invoked.
32 37
33 - -_g++
34 - Select GNU C++ (g++) as the primary compiler.
38 + --versions
39 + Request from each configured primary and shadow compiler its
40 + version information.
35 41
36 -OPTIONS
37 - The following options are supported:
42 + -C The sources being compiled are C++. This is necessary as it
43 + affects the translation of compiler arguments.
38 44
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.
45 + -- Arguments intended for the compilers themselves must be separated
46 + from those of cw by a --.
44 47
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.
48 + -_name=
50 49
51 - -_noecho
52 - Normally, cw writes to standard error the actual compiler commands
53 - invoked, each prefixed with '+'. This option suppresses these
54 - messages.
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 55
56 - -_cc=,-_gcc=,-_CC=,-g++=
57 - Pass compiler-dependent options. See ARGUMENT TRANSLATION.
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:
63 + If --shadow compilers are specified cw will invoke each shadow compiler,
64 + with the outputs modified (as well as any translation for compiler style)
65 + as follows:
68 66
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.
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.
73 70
74 - 2. If an option of the form -ofilename was provided, it will be
75 - replaced by two options of the form -o tempfile.
71 + 2. If the -o filename option was provided, with or without a separating
72 + space, it will be replaced with -o tempfile
76 73
77 - 3. If the option -o was provided, its following argument will be
78 - replaced by tempfile.
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.
79 81
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.
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.
83 88
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 89 ARGUMENT TRANSLATION
102 - The arguments provided to cw will be passed through to each compiler
103 - invoked, altered as follows:
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.
104 96
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 97 ENVIRONMENT
127 - CW_NO_SHADOW
128 - If this variable is set in the environment, invoke only the primary
129 - compiler.
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.
130 103
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.
104 + CW_NO_EXEC
105 + f this variable is set in the environment, write the usual output
106 + to standard error but do not actually invoke any compiler. This
107 + is useful for debugging the translation engine.
136 108
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, GNUC_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:
167 -
168 - If CW_GCC_DIR is set, the GNU C compiler in $CW_GCC_DIR will be used.
169 - Likewise, if CW_GPLUSPLUS_DIR is set, the GNU C++ compiler in
170 - $CW_GPLUSPLUS_DIR will be used. Otherwise, if GNUC_ROOT is set, the
171 - GNU C and C++ compilers in $GNUC_ROOT/bin will be used. Previously
172 - $GCC_ROOT was used to in place of $GNUC_ROOT; however, because that
173 - environment variable has special meaning to gcc, if it is encountered
174 - in bldenv or nightly(1ONBLD), it will be translated to $GNUC_ROOT.
175 -
176 - If none of the aforementioned environment variables are set, the GNU
177 - compilers in a predefined default location will be used.
178 -
179 109 EXIT STATUS
180 - The following exit status values are returned:
110 + The following exit status values are returned:
181 111
182 - 0 The primary compiler, and shadow compiler if invoked, both
183 - completed successfully.
112 + 0 The primary compiler, and shadow compilers if invoked, all
113 + completed successfully.
184 114
185 - >0 A usage error occurred, or one or more compilers returned a nonzero
186 - exit status.
115 + >0 A usage error occurred, or one or more compilers returned a
116 + nonzero exit status.
187 117
188 -BUGS
189 - The translations provided for gcc are not always exact and in some
190 - cases reflect local ON policy rather than actual equivalence.
191 -
192 - Additional compiler types should be supported.
193 -
194 - The translation engine is hacky.
195 -
196 118 SEE ALSO
197 - cc(1), CC(1), gcc(1)
119 + cc(1), CC(1), gcc(1)
198 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.
199 124
125 + Additional compiler types should be supported.
200 126
201 - August 16, 2018 CW(1ONBLD)
127 + The translation engine is hacky.
128 +
129 +illumos September 4, 2018 illumos
XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX