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