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