4 .\" The contents of this file are subject to the terms of the
5 .\" Common Development and Distribution License (the "License").
6 .\" You may not use this file except in compliance with the License.
7 .\"
8 .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE
9 .\" or http://www.opensolaris.org/os/licensing.
10 .\" See the License for the specific language governing permissions
11 .\" and limitations under the License.
12 .\"
13 .\" When distributing Covered Code, include this CDDL HEADER in each
14 .\" file and include the License file at usr/src/OPENSOLARIS.LICENSE.
15 .\" If applicable, add the following below this CDDL HEADER, with the
16 .\" fields enclosed by brackets "[]" replaced with your own identifying
17 .\" information: Portions Copyright [yyyy] [name of copyright owner]
18 .\"
19 .\" CDDL HEADER END
20 .\"
21 .\" Copyright 2010 Sun Microsystems, Inc. All rights reserved.
22 .\" Use is subject to license terms.
23 .\"
24 .TH CW 1ONBLD "August 16, 2018"
25 .SH NAME
26 .I cw
27 \- invoke one or more compilers with argument translation
28 .SH SYNOPSIS
29 \fBcw {-_cc|-_gcc|-_CC|-_g++} [options] [compiler args...]\fP
30 .SH DESCRIPTION
31 .LP
32 .I cw
33 is a facility for invoking one or more compilers, providing
34 translation from Sun Studio arguments as appropriate. This allows
35 the use of arbitrary compilers without the need to alter large
36 numbers of makefiles. A mode called shadow compilation, the default,
37 invokes two different compilers so that warnings and errors may be
38 obtained from both. See SHADOW COMPILATION for details. This version
39 of cw supports Sun Studio 10 and 11 and gcc 3.4.3 as shipped in
40 Solaris.
41 .SH ARGUMENTS
42 .LP
43 Exactly one of the following arguments is required, and must appear
44 immediately following \fBcw\fP in the argument list:
45 .TP 4
46 .B \-_cc
47 Select Sun Studio C (cc) as the primary compiler.
48 .TP 4
49 .B \-_gcc
50 Select GNU C (gcc) as the primary compiler.
51 .TP 4
52 .B \-_CC
53 Select Sun Studio C++ (CC) as the primary compiler.
54 .TP 4
55 .B \-_g++
56 Select GNU C++ (g++) as the primary compiler.
57 .SH OPTIONS
58 .LP
59 The following options are supported:
60 .TP 4
61 .B \-_compiler
62 Do not invoke any compiler; instead, write to standard output the
63 full path to the primary compiler that would be invoked. If this
64 option is given, it must appear immediately following the compiler
65 selection argument, and all other options will be disregarded.
66 .TP 4
67 .B \-_versions
68 Print the cw version, followed in turn by the path to and versions
69 of each compiler which would be invoked. If this option is given,
70 it must appear immediately following the compiler selection argument,
71 and all other options will be disregarded.
72 .TP 4
73 .B \-_noecho
74 Normally, cw writes to standard error the actual compiler commands
75 invoked, each prefixed with '+'. This option suppresses these
76 messages.
77 .TP 4
78 .B \-_cc=,\-_gcc=,\-_CC=,\-g++=
79 Pass compiler-dependent options. See ARGUMENT TRANSLATION.
80 .SH SHADOW COMPILATION
81 .LP
82 Unless otherwise directed by environment variables (see ENVIRONMENT),
83 \fBcw\fP will invoke both the compiler specified by its first argument
84 (primary) and a designated alternate compiler (shadow). The primary
85 compiler will be invoked with the arguments given to cw, translated
86 as described in ARGUMENT TRANSLATION. The secondary compiler will be
87 invoked in parallel with the primary (but see ENVIRONMENT); its
88 arguments will likewise be translated. However, the shadow compiler's
89 arguments will also be modified as follows:
90 .TP 4
91 .B 1.
92 If none of \fI-c\fP, \fI-E\fP, \fI-P\fP, or \fI-S\fP appears in the
93 argument list (that is, linking is attempted), the shadow compiler
94 will not be invoked. This is because the objects built with that
95 compiler which would be linked have been previously discarded.
96 .TP 4
97 .B 2.
98 If an option of the form \fI-ofilename\fP was provided, it will be
99 replaced by two options of the form \fI-o\fP \fItempfile\fP.
100 .TP 4
101 .B 3.
102 If the option \fI-o\fP was provided, its following argument will be
103 replaced by \fItempfile\fP.
104 .TP 4
105 .B 4.
106 If neither of the above options was provided, two options of the
107 form \fI-o\fP \fItempfile\fP will be added to the end of the argument
108 list used to invoke the shadow compiler.
109 .LP
110 In all three cases, \fItempfile\fP is the name of a temporary file
111 which will be removed by \fBcw\fP before it terminates.
112 .LP
113 When shadow compilation is in effect, \fBcw\fP writes to standard error
114 each compiler's standard error output following its argument list.
115 Messages from the two compilers will not be interleaved. If \fBcw\fP
116 is used to invoke the preprocessor and no output location is specified,
117 \fBcw\fP will write to standard output the primary compiler's
118 standard output, and the secondary compiler's standard output will
119 be discarded.
120 .LP
121 Because the Studio compilers write intermediate objects to fixed
122 filenames in the current directory when instructed to compile and
123 link multiple source files via a single command line, it would be
124 unsafe to invoke more than one compiler in this fashion. Therefore
125 \fBcw\fP does not accept multiple source files unless the
126 preprocessor is to be invoked. An attempt to invoke \fBcw\fP in
127 this manner will result in an error.
128 .SH ARGUMENT TRANSLATION
129 .LP
130 The arguments provided to \fBcw\fP will be passed through to each
131 compiler invoked, altered as follows:
132 .TP 4
133 .B 1.
134 Options intended for \fBcw\fP itself are removed.
135 .TP 4
136 .B 2.
137 The shadow compiler's arguments are modified as described in
138 SHADOW COMPILATION so that its output is discarded.
139 .TP 4
140 .B 3.
141 If the compiler to be invoked is a GNU C or C++ compiler, a set of
142 default flags is added to the beginning of the argument list, and the
143 remaining arguments are translated to their closest appropriate
144 semantic equivalents and passed in the same order as their
145 counterparts given to \fBcw\fP. Arguments which begin with
146 \fI-_gcc=\fP or \fI-_g++=\fP will be passed in place with the
147 leading portion removed. Arguments which begin with \fI-_cc=\fP or
148 \fI-_CC=\fP will be discarded. See the comments at the head of
149 \fIusr/src/tools/cw/cw.c\fP for a detailed list of translations.
150 .TP 4
151 .B 4.
152 If the compiler to be invoked is a Studio C or C++ compiler, the
153 remaining arguments are passed unmodified and in the same order as
154 given to \fBcw\fP. Arguments which begin with \fI-_cc=\fP or
155 \fI-_CC=\fP will be passed in place with the leading portion removed.
156 Arguments which begin with \fI-_gcc=\fP or \fI-_g++=\fP will be
157 discarded.
158 .SH ENVIRONMENT
159 .TP 4
160 .B CW_NO_SHADOW
161 If this variable is set in the environment, invoke only the
162 primary compiler.
163 .TP 4
164 .B CW_SHADOW_SERIAL
165 If this variable is set in the environment, invoke the primary compiler,
166 wait for it to complete, then invoke the shadow compiler. Normally
167 the two compilers are invoked in parallel. If CW_NO_SHADOW is set,
168 this has no effect.
169 .TP 4
170 .B CW_NO_EXEC
171 If this variable is set in the environment, write the usual output to
172 standard error but do not actually invoke any compiler. This is
173 useful for debugging the translation engine.
174 .TP 4
175 .B CW_CC, CW_CPLUSPLUS
176 If these variables are set in the environment, they specify the full
177 pathname for the Studio C and C++ compilers, respectively.
178 .TP 4
179 .B CW_CC_DIR, CW_CPLUSPLUS_DIR, SPRO_VROOT, SPRO_ROOT, BUILD_TOOLS
180 If CW_CC or CW_CPLUSPLUS are not set,
181 these variables define the search path for Studio compilers as
182 follows:
183 .B
184 If CW_CC_DIR is set, the Studio C compiler in \fI$CW_CC_DIR\fP
185 will be used. Likewise, if CW_CPLUSPLUS_DIR is set, the Studio C++
186 compiler in \fI$CW_CPLUSPLUS_DIR\fP will be used.
187 Otherwise, if SPRO_VROOT is set, the Studio C and C++ compilers
188 in \fI$SPRO_VROOT/bin\fP will be used.
189 Otherwise, if SPRO_ROOT is set, the Studio C and C++ compilers
190 in \fI$SPRO_ROOT/SS12/bin\fP will be used.
191 Otherwise, if BUILD_TOOLS is set, the Studio C and C++ compilers
192 in \fI$BUILD_TOOLS/SUNWspro/SS12/bin\fP will be used.
193 Otherwise, the Studio compilers in a predefined default location
194 will be used.
195 .TP 4
196 .B CW_GCC, CW_GPLUSPLUS
197 If these variables are set in the environment, they specify the full
198 pathname for the GNU C and C++ compilers, respectively.
199 .TP 4
200 .B CW_GCC_DIR, CW_GPLUSPLUS_DIR, GNUC_ROOT
201 If CW_GCC or CW_GPLUSPLUS are not set,
202 these variables alter the search path for GNU compilers in a manner
203 similar to that described above for the Studio compilers. Specifically:
204 .LP
205 If CW_GCC_DIR is set, the GNU C compiler in \fI$CW_GCC_DIR\fP
206 will be used. Likewise, if CW_GPLUSPLUS_DIR is set, the GNU C++
207 compiler in \fI$CW_GPLUSPLUS_DIR\fP will be used.
208 Otherwise, if GNUC_ROOT is set, the GNU C and C++ compilers
209 in \fI$GNUC_ROOT/bin\fP will be used. Previously \fI$GCC_ROOT\fP was
210 used to in place of \fI$GNUC_ROOT\fP; however, because that environment
211 variable has special meaning to gcc, if it is encountered in bldenv or
212 nightly(1ONBLD), it will be translated to \fI$GNUC_ROOT\fP.
213 .LP
214 If none of the aforementioned environment variables are set, the GNU
215 compilers in a predefined default location will be used.
216 .SH EXIT STATUS
217 .LP
218 The following exit status values are returned:
219 .IP "\fB0\fR" 4
220 The primary compiler, and shadow compiler if invoked, both completed
221 successfully.
222 .IP "\fB>0\fR" 4
223 A usage error occurred, or one or more compilers returned a nonzero
224 exit status.
225 .SH BUGS
226 .LP
227 The translations provided for gcc are not always exact and in some
228 cases reflect local ON policy rather than actual equivalence.
229 .LP
230 Additional compiler types should be supported.
231 .LP
232 The translation engine is hacky.
233 .SH SEE ALSO
234 .LP
235 cc(1), CC(1), gcc(1)
|
4 .\" The contents of this file are subject to the terms of the
5 .\" Common Development and Distribution License (the "License").
6 .\" You may not use this file except in compliance with the License.
7 .\"
8 .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE
9 .\" or http://www.opensolaris.org/os/licensing.
10 .\" See the License for the specific language governing permissions
11 .\" and limitations under the License.
12 .\"
13 .\" When distributing Covered Code, include this CDDL HEADER in each
14 .\" file and include the License file at usr/src/OPENSOLARIS.LICENSE.
15 .\" If applicable, add the following below this CDDL HEADER, with the
16 .\" fields enclosed by brackets "[]" replaced with your own identifying
17 .\" information: Portions Copyright [yyyy] [name of copyright owner]
18 .\"
19 .\" CDDL HEADER END
20 .\"
21 .\" Copyright 2010 Sun Microsystems, Inc. All rights reserved.
22 .\" Use is subject to license terms.
23 .\"
24 .\" Copyright 2018 Joyent, Inc.
25 .\"
26 .Dd September 4, 2018
27 .Dt CW 1ONBLD
28 .Os
29 .Sh NAME
30 .Nm cw
31 .Nd invoke one or more compilers with argument translation
32 .Sh SYNOPSIS
33 .Nm cw
34 .Op Fl C
35 .Op Fl -versions
36 .Op Fl -noecho
37 .Fl -primary Ar compiler
38 .Op Fl -shadow Ar compiler ...
39 .Fl -
40 .Ar compiler args ...
41 .Sh DESCRIPTION
42 .Nm cw
43 is a facility for invoking one or more compilers, providing translation from
44 Sun style arguments as appropriate.
45 This allows the use of arbitrary compilers without the need to alter large
46 numbers of makefiles.
47 A mode called shadow compilation invokes multiple compilers so that warnings
48 and errors may be obtained from all of them.
49 See
50 .Sx SHADOW COMPILATION
51 for details.
52 This version of cw supports compilers with both Sun Studio 12 and GCC-style
53 command lines.
54 .Sh ARGUMENTS
55 Both the
56 .Fl -primary
57 and
58 .Fl -shadow
59 parameters take a
60 .Em compiler specification .
61 This is a comma-separated list of the form
62 .Ar name,executable,style
63 Where
64 .Ar name
65 is a name for the compiler,
66 .Ar executable
67 is the full path to the compiler executable, and
68 .Ar style
69 is the style of command-line options the compiler expects, either
70 .Em sun
71 or
72 .Em gnu .
73 .Bl -tag -width indent
74 .It Fl -primary Ar compiler
75 Specify the compiler to be used primarily (that which is used for link-editing
76 and pre-processing, and whos objects we deliver).
77 .It Fl -shadow Ar compiler
78 Specify a shadow compiler, which builds sources for the sake of checking code
79 quality and compatibility, but has its output discarded.
80 .It Fl -noecho
81 Do not echo the actual command line of any compilers invoked.
82 .It Fl -versions
83 Request from each configured primary and shadow compiler its version
84 information.
85 .It Fl C
86 The sources being compiled are C++. This is necessary as it affects the
87 translation of compiler arguments.
88 .It Fl -
89 Arguments intended for the compilers themselves must be separated from those
90 of
91 .Nm cw
92 by a
93 .Fl - .
94 .It Fl _name=
95 .It Fl _style=
96 Parameters intended for the compiler be guarded with options of the form
97 .Fl _name=
98 and
99 .Fl _style=
100 Where
101 .Em name
102 and
103 .Em style
104 are those passed to
105 .Fl -primary
106 and
107 .Fl -shadow
108 this allows certain flags to be passed only to certain classes of compiler.
109 .Pp
110 For historical reasons, the
111 .Fl _style=
112 option is also translated such that a style of
113 .Em sun
114 may use the flag
115 .Fl _cc=
116 and a style of
117 .Em gnu
118 may use the flag
119 .Fl _gcc= ,
120 and when the
121 .Fl C
122 option is given and C++ is in use the style of
123 .Em sun
124 may use the flag
125 .Fl _CC=
126 and the style of
127 .Em gnu
128 may use the flag
129 .Fl _g++= .
130 .El
131 .Sh SHADOW COMPILATION
132 If
133 .Fl -shadow
134 compilers are specified
135 .Nm cw
136 will invoke each shadow compiler, with the outputs modified (as well as any
137 translation for compiler style) as follows:
138 .Bl -enum
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.
145 .It
146 If the
147 .Fl o Ar filename
148 option was provided, with or without a separating space, it will be replaced with
149 .Fl o Ar tempfile
150 .It
151 If the option
152 .Fl o
153 was not provided,
154 .Fl o Ar tempfile
155 will be added to the end of the argument list used to invoke
156 the shadow compilers.
157 .El
158 When shadow compilation is in effect,
159 .Nm cw
160 writes to standard error each compiler's standard error output following its
161 argument list.
162 Messages from the compilers will not be interleaved.
163 If
164 .Nm cw
165 is used to invoke the preprocessor and no output location is specified,
166 .Nm cw
167 will write to standard output the primary compiler's standard output.
168 .Pp
169 Because the Sun compilers write intermediate objects to fixed
170 filenames in the current directory when instructed to compile and
171 link multiple source files via a single command line, it would be
172 unsafe to invoke more than one compiler in this fashion.
173 Therefore
174 .Nm cw
175 does not accept multiple source files unless the preprocessor is to be
176 invoked.
177 An attempt to invoke
178 .Nm cw
179 in this manner will result in an error.
180 .Sh ARGUMENT TRANSLATION
181 If the compiler to be invoked is a GNU-style C or C++ compiler, a set of
182 default flags is added to the beginning of the argument list, and the
183 remaining arguments are translated to their closest appropriate
184 semantic equivalents and passed in the same order as their
185 counterparts given to
186 .Nm cw .
187 See the comments at the head of
188 .Pa usr/src/tools/cw/cw.c
189 for a detailed list of translations.
190 .Sh ENVIRONMENT
191 .Bl -tag -width indent
192 .It CW_SHADOW_SERIAL
193 If this variable is set in the environment, invoke the primary compiler, wait
194 for it to complete, then invoke the shadow compilers.
195 Normally the primary and shadow compilers are invoked in parallel.
196 .It CW_NO_EXEC
197 f this variable is set in the environment, write the usual output to
198 standard error but do not actually invoke any compiler.
199 This is useful for debugging the translation engine.
200 .El
201 .Sh EXIT STATUS
202 The following exit status values are returned:
203 .Bl -tag -width indent
204 .It 0
205 The primary compiler, and shadow compilers if invoked, all completed
206 successfully.
207 .It >0
208 A usage error occurred, or one or more compilers returned a nonzero
209 exit status.
210 .El
211 .Sh SEE ALSO
212 .Xr cc 1 ,
213 .Xr CC 1 ,
214 .Xr gcc 1
215 .Sh BUGS
216 The translations provided for gcc are not always exact and in some cases
217 reflect local policy rather than actual equivalence.
218 .Pp
219 Additional compiler types should be supported.
220 .Pp
221 The translation engine is hacky.
|