xref: /illumos-gate/usr/src/tools/cw/cw.1onbld (revision 69b1fd3f)
280ab886dSwesolows.\" CDDL HEADER START
480ab886dSwesolows.\" The contents of this file are subject to the terms of the
580ab886dSwesolows.\" Common Development and Distribution License (the "License").
680ab886dSwesolows.\" You may not use this file except in compliance with the License.
880ab886dSwesolows.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE
980ab886dSwesolows.\" or http://www.opensolaris.org/os/licensing.
1080ab886dSwesolows.\" See the License for the specific language governing permissions
1180ab886dSwesolows.\" and limitations under the License.
1380ab886dSwesolows.\" When distributing Covered Code, include this CDDL HEADER in each
1480ab886dSwesolows.\" file and include the License file at usr/src/OPENSOLARIS.LICENSE.
1580ab886dSwesolows.\" If applicable, add the following below this CDDL HEADER, with the
1680ab886dSwesolows.\" fields enclosed by brackets "[]" replaced with your own identifying
1780ab886dSwesolows.\" information: Portions Copyright [yyyy] [name of copyright owner]
1980ab886dSwesolows.\" CDDL HEADER END
217fbf8d03SScott Rotondo.\" Copyright 2010 Sun Microsystems, Inc.  All rights reserved.
2280ab886dSwesolows.\" Use is subject to license terms.
24aa9ef484SJohn Levon.\" Copyright 2018 Joyent, Inc.
25aa9ef484SJohn Levon.\"
26aa9ef484SJohn Levon.Dd September 4, 2018
27aa9ef484SJohn Levon.Dt CW 1ONBLD
28aa9ef484SJohn Levon.Os
29aa9ef484SJohn Levon.Sh NAME
30aa9ef484SJohn Levon.Nm cw
31aa9ef484SJohn Levon.Nd invoke one or more compilers with argument translation
32aa9ef484SJohn Levon.Sh SYNOPSIS
33aa9ef484SJohn Levon.Nm cw
34aa9ef484SJohn Levon.Op Fl C
35aa9ef484SJohn Levon.Op Fl -versions
36aa9ef484SJohn Levon.Op Fl -noecho
37aa9ef484SJohn Levon.Fl -primary Ar compiler
38aa9ef484SJohn Levon.Op Fl -shadow Ar compiler ...
39*69b1fd3fSRichard Lowe.Op Fl -linker Ar linker
40aa9ef484SJohn Levon.Fl -
41aa9ef484SJohn Levon.Ar compiler args ...
42aa9ef484SJohn Levon.Sh DESCRIPTION
43aa9ef484SJohn Levon.Nm cw
44aa9ef484SJohn Levonis a facility for invoking one or more compilers, providing translation from
45aa9ef484SJohn LevonSun style arguments as appropriate.
46aa9ef484SJohn LevonThis allows the use of arbitrary compilers without the need to alter large
47aa9ef484SJohn Levonnumbers of makefiles.
48aa9ef484SJohn LevonA mode called shadow compilation invokes multiple compilers so that warnings
49aa9ef484SJohn Levonand errors may be obtained from all of them.
50aa9ef484SJohn LevonSee
51aa9ef484SJohn Levon.Sx SHADOW COMPILATION
52aa9ef484SJohn Levonfor details.
53aa9ef484SJohn LevonThis version of cw supports compilers with both Sun Studio 12 and GCC-style
54aa9ef484SJohn Levoncommand lines.
55aa9ef484SJohn Levon.Sh ARGUMENTS
56aa9ef484SJohn LevonBoth the
57aa9ef484SJohn Levon.Fl -primary
58aa9ef484SJohn Levonand
59aa9ef484SJohn Levon.Fl -shadow
60aa9ef484SJohn Levonparameters take a
61aa9ef484SJohn Levon.Em compiler specification .
62aa9ef484SJohn LevonThis is a comma-separated list of the form
63aa9ef484SJohn Levon.Ar name,executable,style
64aa9ef484SJohn LevonWhere
65aa9ef484SJohn Levon.Ar name
66aa9ef484SJohn Levonis a name for the compiler,
67aa9ef484SJohn Levon.Ar executable
68aa9ef484SJohn Levonis the full path to the compiler executable, and
69aa9ef484SJohn Levon.Ar style
70aa9ef484SJohn Levonis the style of command-line options the compiler expects, either
71aa9ef484SJohn Levon.Em sun
72aa9ef484SJohn Levonor
73aa9ef484SJohn Levon.Em gnu .
74aa9ef484SJohn Levon.Bl -tag -width indent
75aa9ef484SJohn Levon.It Fl -primary Ar compiler
76aa9ef484SJohn LevonSpecify the compiler to be used primarily (that which is used for link-editing
77aa9ef484SJohn Levonand pre-processing, and whos objects we deliver).
78aa9ef484SJohn Levon.It Fl -shadow Ar compiler
79aa9ef484SJohn LevonSpecify a shadow compiler, which builds sources for the sake of checking code
80aa9ef484SJohn Levonquality and compatibility, but has its output discarded.
81*69b1fd3fSRichard Lowe.It Fl -linker Ar linker
82*69b1fd3fSRichard LoweSpecify a link-editor to use in place of
83*69b1fd3fSRichard Lowe.Pa /usr/bin/ld .
84*69b1fd3fSRichard Lowe.Xr ld 1
85*69b1fd3fSRichard Loweitself arranges for this to be executed by any subprocesses.
86aa9ef484SJohn Levon.It Fl -noecho
87aa9ef484SJohn LevonDo not echo the actual command line of any compilers invoked.
88aa9ef484SJohn Levon.It Fl -versions
89aa9ef484SJohn LevonRequest from each configured primary and shadow compiler its version
90aa9ef484SJohn Levoninformation.
91aa9ef484SJohn Levon.It Fl C
92aa9ef484SJohn LevonThe sources being compiled are C++.  This is necessary as it affects the
93aa9ef484SJohn Levontranslation of compiler arguments.
94aa9ef484SJohn Levon.It Fl -
95aa9ef484SJohn LevonArguments intended for the compilers themselves must be separated from those
96aa9ef484SJohn Levonof
97aa9ef484SJohn Levon.Nm cw
98aa9ef484SJohn Levonby a
99aa9ef484SJohn Levon.Fl - .
100aa9ef484SJohn Levon.It Fl _name=
101aa9ef484SJohn Levon.It Fl _style=
102aa9ef484SJohn LevonParameters intended for the compiler be guarded with options of the form
103aa9ef484SJohn Levon.Fl _name=
104aa9ef484SJohn Levonand
105aa9ef484SJohn Levon.Fl _style=
106aa9ef484SJohn LevonWhere
107aa9ef484SJohn Levon.Em name
108aa9ef484SJohn Levonand
109aa9ef484SJohn Levon.Em style
110aa9ef484SJohn Levonare those passed to
111aa9ef484SJohn Levon.Fl -primary
112aa9ef484SJohn Levonand
113aa9ef484SJohn Levon.Fl -shadow
114aa9ef484SJohn Levonthis allows certain flags to be passed only to certain classes of compiler.
115aa9ef484SJohn Levon.Pp
116aa9ef484SJohn LevonFor historical reasons, the
117aa9ef484SJohn Levon.Fl _style=
118aa9ef484SJohn Levonoption is also translated such that a style of
119aa9ef484SJohn Levon.Em sun
120aa9ef484SJohn Levonmay use the flag
121aa9ef484SJohn Levon.Fl _cc=
122aa9ef484SJohn Levonand a style of
123aa9ef484SJohn Levon.Em gnu
124aa9ef484SJohn Levonmay use the flag
125aa9ef484SJohn Levon.Fl _gcc= ,
126aa9ef484SJohn Levonand when the
127aa9ef484SJohn Levon.Fl C
128aa9ef484SJohn Levonoption is given and C++ is in use the style of
129aa9ef484SJohn Levon.Em sun
130aa9ef484SJohn Levonmay use the flag
131aa9ef484SJohn Levon.Fl _CC=
132aa9ef484SJohn Levonand the style of
133aa9ef484SJohn Levon.Em gnu
134aa9ef484SJohn Levonmay use the flag
135aa9ef484SJohn Levon.Fl _g++= .
136aa9ef484SJohn Levon.El
137aa9ef484SJohn Levon.Sh SHADOW COMPILATION
138aa9ef484SJohn LevonIf
139aa9ef484SJohn Levon.Fl -shadow
140aa9ef484SJohn Levoncompilers are specified
141aa9ef484SJohn Levon.Nm cw
142aa9ef484SJohn Levonwill invoke each shadow compiler, with the outputs modified (as well as any
143aa9ef484SJohn Levontranslation for compiler style) as follows:
144aa9ef484SJohn Levon.Bl -enum
145aa9ef484SJohn Levon.It
14688e61e85SRichard LoweIf
14788e61e85SRichard Lowe.Nm cw
14888e61e85SRichard Loweis invoked to link-edit without compilation (the input files are all objects),
14988e61e85SRichard Lowethe shadow compiler is not invoked.
150aa9ef484SJohn Levon.It
151aa9ef484SJohn LevonIf the
152aa9ef484SJohn Levon.Fl o Ar filename
153aa9ef484SJohn Levonoption was provided, with or without a separating space, it will be replaced with
154aa9ef484SJohn Levon.Fl o Ar tempfile
155aa9ef484SJohn Levon.It
156aa9ef484SJohn LevonIf the option
157aa9ef484SJohn Levon.Fl o
158aa9ef484SJohn Levonwas not provided,
159aa9ef484SJohn Levon.Fl o Ar tempfile
160aa9ef484SJohn Levonwill be added to the end of the argument list used to invoke
161aa9ef484SJohn Levonthe shadow compilers.
162aa9ef484SJohn Levon.El
163aa9ef484SJohn LevonWhen shadow compilation is in effect,
164aa9ef484SJohn Levon.Nm cw
165aa9ef484SJohn Levonwrites to standard error each compiler's standard error output following its
166aa9ef484SJohn Levonargument list.
167aa9ef484SJohn LevonMessages from the compilers will not be interleaved.
168aa9ef484SJohn LevonIf
169aa9ef484SJohn Levon.Nm cw
17080ab886dSwesolowsis used to invoke the preprocessor and no output location is specified,
171aa9ef484SJohn Levon.Nm cw
172aa9ef484SJohn Levonwill write to standard output the primary compiler's standard output.
173aa9ef484SJohn Levon.Pp
174aa9ef484SJohn LevonBecause the Sun compilers write intermediate objects to fixed
17580ab886dSwesolowsfilenames in the current directory when instructed to compile and
17680ab886dSwesolowslink multiple source files via a single command line, it would be
177aa9ef484SJohn Levonunsafe to invoke more than one compiler in this fashion.
178aa9ef484SJohn LevonTherefore
179aa9ef484SJohn Levon.Nm cw
180aa9ef484SJohn Levondoes not accept multiple source files unless the preprocessor is to be
181aa9ef484SJohn Levoninvoked.
182aa9ef484SJohn LevonAn attempt to invoke
183aa9ef484SJohn Levon.Nm cw
184aa9ef484SJohn Levonin this manner will result in an error.
185aa9ef484SJohn Levon.Sh ARGUMENT TRANSLATION
186aa9ef484SJohn LevonIf the compiler to be invoked is a GNU-style C or C++ compiler, a set of
18780ab886dSwesolowsdefault flags is added to the beginning of the argument list, and the
18880ab886dSwesolowsremaining arguments are translated to their closest appropriate
18980ab886dSwesolowssemantic equivalents and passed in the same order as their
190aa9ef484SJohn Levoncounterparts given to
191aa9ef484SJohn Levon.Nm cw .
192aa9ef484SJohn LevonSee the comments at the head of
193aa9ef484SJohn Levon.Pa usr/src/tools/cw/cw.c
194aa9ef484SJohn Levonfor a detailed list of translations.
195aa9ef484SJohn Levon.Sh ENVIRONMENT
196aa9ef484SJohn Levon.Bl -tag -width indent
197aa9ef484SJohn Levon.It CW_SHADOW_SERIAL
198aa9ef484SJohn LevonIf this variable is set in the environment, invoke the primary compiler, wait
199aa9ef484SJohn Levonfor it to complete, then invoke the shadow compilers.
200aa9ef484SJohn LevonNormally the primary and shadow compilers are invoked in parallel.
201aa9ef484SJohn Levon.It CW_NO_EXEC
202aa9ef484SJohn Levonf this variable is set in the environment, write the usual output to
203aa9ef484SJohn Levonstandard error but do not actually invoke any compiler.
204aa9ef484SJohn LevonThis is useful for debugging the translation engine.
205aa9ef484SJohn Levon.El
206aa9ef484SJohn Levon.Sh EXIT STATUS
20780ab886dSwesolowsThe following exit status values are returned:
208aa9ef484SJohn Levon.Bl -tag -width indent
209aa9ef484SJohn Levon.It 0
210aa9ef484SJohn LevonThe primary compiler, and shadow compilers if invoked, all completed
212aa9ef484SJohn Levon.It >0
21380ab886dSwesolowsA usage error occurred, or one or more compilers returned a nonzero
21480ab886dSwesolowsexit status.
215aa9ef484SJohn Levon.El
216aa9ef484SJohn Levon.Sh SEE ALSO
217aa9ef484SJohn Levon.Xr cc 1 ,
218aa9ef484SJohn Levon.Xr CC 1 ,
219*69b1fd3fSRichard Lowe.Xr gcc 1 ,
220*69b1fd3fSRichard Lowe.Xr ld 1
221aa9ef484SJohn Levon.Sh BUGS
222aa9ef484SJohn LevonThe translations provided for gcc are not always exact and in some cases
223aa9ef484SJohn Levonreflect local policy rather than actual equivalence.
224aa9ef484SJohn Levon.Pp
22580ab886dSwesolowsAdditional compiler types should be supported.
226aa9ef484SJohn Levon.Pp
22780ab886dSwesolowsThe translation engine is hacky.