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