Print this page
Revert "Revert most of "9899 cw(1onbld) should shadow more compilation""
This reverts commit 67deef8cbc83060db238a0f4ee252d1ba74641ef.
| Split |
Close |
| Expand all |
| Collapse all |
--- old/usr/src/tools/cw/cw.1onbld
+++ new/usr/src/tools/cw/cw.1onbld
1 1 .\"
2 2 .\" CDDL HEADER START
3 3 .\"
4 4 .\" The contents of this file are subject to the terms of the
5 5 .\" Common Development and Distribution License (the "License").
6 6 .\" You may not use this file except in compliance with the License.
7 7 .\"
8 8 .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE
9 9 .\" or http://www.opensolaris.org/os/licensing.
10 10 .\" See the License for the specific language governing permissions
11 11 .\" and limitations under the License.
12 12 .\"
13 13 .\" When distributing Covered Code, include this CDDL HEADER in each
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 24 .\" Copyright 2018 Joyent, Inc.
25 25 .\"
26 26 .Dd September 4, 2018
27 27 .Dt CW 1ONBLD
28 28 .Os
29 29 .Sh NAME
30 30 .Nm cw
31 31 .Nd invoke one or more compilers with argument translation
32 32 .Sh SYNOPSIS
33 33 .Nm cw
34 34 .Op Fl C
35 35 .Op Fl -versions
36 36 .Op Fl -noecho
37 37 .Fl -primary Ar compiler
38 38 .Op Fl -shadow Ar compiler ...
39 39 .Fl -
40 40 .Ar compiler args ...
41 41 .Sh DESCRIPTION
42 42 .Nm cw
43 43 is a facility for invoking one or more compilers, providing translation from
44 44 Sun style arguments as appropriate.
45 45 This allows the use of arbitrary compilers without the need to alter large
46 46 numbers of makefiles.
47 47 A mode called shadow compilation invokes multiple compilers so that warnings
48 48 and errors may be obtained from all of them.
49 49 See
50 50 .Sx SHADOW COMPILATION
51 51 for details.
52 52 This version of cw supports compilers with both Sun Studio 12 and GCC-style
53 53 command lines.
54 54 .Sh ARGUMENTS
55 55 Both the
56 56 .Fl -primary
57 57 and
58 58 .Fl -shadow
59 59 parameters take a
60 60 .Em compiler specification .
61 61 This is a comma-separated list of the form
62 62 .Ar name,executable,style
63 63 Where
64 64 .Ar name
65 65 is a name for the compiler,
66 66 .Ar executable
67 67 is the full path to the compiler executable, and
68 68 .Ar style
69 69 is the style of command-line options the compiler expects, either
70 70 .Em sun
71 71 or
72 72 .Em gnu .
73 73 .Bl -tag -width indent
74 74 .It Fl -primary Ar compiler
75 75 Specify the compiler to be used primarily (that which is used for link-editing
76 76 and pre-processing, and whos objects we deliver).
77 77 .It Fl -shadow Ar compiler
78 78 Specify a shadow compiler, which builds sources for the sake of checking code
79 79 quality and compatibility, but has its output discarded.
80 80 .It Fl -noecho
81 81 Do not echo the actual command line of any compilers invoked.
82 82 .It Fl -versions
83 83 Request from each configured primary and shadow compiler its version
84 84 information.
85 85 .It Fl C
86 86 The sources being compiled are C++. This is necessary as it affects the
87 87 translation of compiler arguments.
88 88 .It Fl -
89 89 Arguments intended for the compilers themselves must be separated from those
90 90 of
91 91 .Nm cw
92 92 by a
93 93 .Fl - .
94 94 .It Fl _name=
95 95 .It Fl _style=
96 96 Parameters intended for the compiler be guarded with options of the form
97 97 .Fl _name=
98 98 and
99 99 .Fl _style=
100 100 Where
101 101 .Em name
102 102 and
103 103 .Em style
104 104 are those passed to
105 105 .Fl -primary
106 106 and
107 107 .Fl -shadow
108 108 this allows certain flags to be passed only to certain classes of compiler.
109 109 .Pp
110 110 For historical reasons, the
111 111 .Fl _style=
112 112 option is also translated such that a style of
113 113 .Em sun
114 114 may use the flag
115 115 .Fl _cc=
116 116 and a style of
117 117 .Em gnu
118 118 may use the flag
119 119 .Fl _gcc= ,
120 120 and when the
121 121 .Fl C
122 122 option is given and C++ is in use the style of
123 123 .Em sun
124 124 may use the flag
125 125 .Fl _CC=
126 126 and the style of
127 127 .Em gnu
128 128 may use the flag
129 129 .Fl _g++= .
|
↓ open down ↓ |
129 lines elided |
↑ open up ↑ |
130 130 .El
131 131 .Sh SHADOW COMPILATION
132 132 If
133 133 .Fl -shadow
134 134 compilers are specified
135 135 .Nm cw
136 136 will invoke each shadow compiler, with the outputs modified (as well as any
137 137 translation for compiler style) as follows:
138 138 .Bl -enum
139 139 .It
140 -If neither of
141 -.Fl c ,
142 -.Fl S
143 -appears in the argument list (that is, linking is attempted or only the
144 -pre-processor is invoked), the shadow compilers will not be invoked.
140 +If
141 +.Nm cw
142 +is invoked to link-edit without compilation (the input files are all objects),
143 +the shadow compiler is not invoked.
145 144 .It
146 145 If the
147 146 .Fl o Ar filename
148 147 option was provided, with or without a separating space, it will be replaced with
149 148 .Fl o Ar tempfile
150 149 .It
151 150 If the option
152 151 .Fl o
153 152 was not provided,
154 153 .Fl o Ar tempfile
155 154 will be added to the end of the argument list used to invoke
156 155 the shadow compilers.
157 156 .El
158 157 When shadow compilation is in effect,
159 158 .Nm cw
160 159 writes to standard error each compiler's standard error output following its
161 160 argument list.
162 161 Messages from the compilers will not be interleaved.
163 162 If
164 163 .Nm cw
165 164 is used to invoke the preprocessor and no output location is specified,
166 165 .Nm cw
167 166 will write to standard output the primary compiler's standard output.
168 167 .Pp
169 168 Because the Sun compilers write intermediate objects to fixed
170 169 filenames in the current directory when instructed to compile and
171 170 link multiple source files via a single command line, it would be
172 171 unsafe to invoke more than one compiler in this fashion.
173 172 Therefore
174 173 .Nm cw
175 174 does not accept multiple source files unless the preprocessor is to be
176 175 invoked.
177 176 An attempt to invoke
178 177 .Nm cw
179 178 in this manner will result in an error.
180 179 .Sh ARGUMENT TRANSLATION
181 180 If the compiler to be invoked is a GNU-style C or C++ compiler, a set of
182 181 default flags is added to the beginning of the argument list, and the
183 182 remaining arguments are translated to their closest appropriate
184 183 semantic equivalents and passed in the same order as their
185 184 counterparts given to
186 185 .Nm cw .
187 186 See the comments at the head of
188 187 .Pa usr/src/tools/cw/cw.c
189 188 for a detailed list of translations.
190 189 .Sh ENVIRONMENT
191 190 .Bl -tag -width indent
192 191 .It CW_SHADOW_SERIAL
193 192 If this variable is set in the environment, invoke the primary compiler, wait
194 193 for it to complete, then invoke the shadow compilers.
195 194 Normally the primary and shadow compilers are invoked in parallel.
196 195 .It CW_NO_EXEC
197 196 f this variable is set in the environment, write the usual output to
198 197 standard error but do not actually invoke any compiler.
199 198 This is useful for debugging the translation engine.
200 199 .El
201 200 .Sh EXIT STATUS
202 201 The following exit status values are returned:
203 202 .Bl -tag -width indent
204 203 .It 0
205 204 The primary compiler, and shadow compilers if invoked, all completed
206 205 successfully.
207 206 .It >0
208 207 A usage error occurred, or one or more compilers returned a nonzero
209 208 exit status.
210 209 .El
211 210 .Sh SEE ALSO
212 211 .Xr cc 1 ,
213 212 .Xr CC 1 ,
214 213 .Xr gcc 1
215 214 .Sh BUGS
216 215 The translations provided for gcc are not always exact and in some cases
217 216 reflect local policy rather than actual equivalence.
218 217 .Pp
219 218 Additional compiler types should be supported.
220 219 .Pp
221 220 The translation engine is hacky.
|
↓ open down ↓ |
67 lines elided |
↑ open up ↑ |
XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX