scc-cc.man (10563B)
1 .TH SCC-CC 1 scc\-VERSION 2 .SH NAME 3 scc-cc \- C compiler driver 4 .SH SYNOPSIS 5 .B scc-cc 6 .RB [ \-c | \-S | \-E ] 7 .RB [ \-std= standard ] 8 .br 9 .RB " " [ \-g ] 10 .RB [ \-Olevel ] 11 .br 12 .RB " " [ \-Wwarn ...] 13 .br 14 .RB " " [ \-Idir ...] 15 .RB [ \-Ldir ...] 16 .br 17 .RB " " [ \-Dmacro [ =defn ]...] 18 .RB [ \-Umacro ] 19 .br 20 .RB " " [ \-foption ...] 21 .RB [ \-mmachine-option ...] 22 .br 23 .RB " " [ \-o 24 .IR outfile ] 25 .RB [ \-l lib ]... 26 .br 27 .RB " " [ \-Msdk ] 28 .RB [ \-q | \-Q ] 29 .br 30 .RB " " [ \-a 31 .IR arch ] 32 .RB [ \-t 33 .IR sys ] 34 .br 35 .RB " " 36 .IR infile ... 37 .SH DESCRIPTION 38 .B scc-cc 39 is the compiler driver of the scc toolchain. 40 It accepts C source files, intermediate representation files, 41 assembler source files, object files, and archive libraries, 42 and orchestrates the tools required to turn them into an 43 executable or object file. 44 .PP 45 For each C source file 46 .RB ( .c ), 47 .B scc-cc 48 runs a pipeline of sub-processes connected by pipes: 49 the frontend 50 .B cc1 51 compiles the source to scc IR, the backend 52 .B cc2 53 lowers the IR to assembly (or to QBE IR when QBE mode is active), 54 the optional 55 .B qbe 56 stage compiles QBE IR to native assembly, 57 and finally the assembler 58 .B as 59 produces an object file. 60 When linking is not suppressed, the resulting object files are 61 passed to the linker 62 .B ld 63 to produce the final executable. 64 .PP 65 Files with other extensions are handled as follows: 66 .TP 67 .B .ir 68 Passed directly to 69 .BR cc2 , 70 skipping the 71 .B cc1 72 stage. 73 .TP 74 .B .qbe 75 Passed directly to 76 .BR qbe , 77 skipping 78 .B cc1 79 and 80 .BR cc2 . 81 .TP 82 .B .s 83 Passed directly to the assembler, skipping all compiler stages. 84 .TP 85 .B .o ", " .a 86 Passed directly to the linker. 87 .SH OPTIONS 88 .SS Compilation Control 89 .TP 90 .B \-c 91 Compile and assemble, but do not link. 92 One object file is produced for each input source file. 93 If 94 .B \-o 95 is also specified, only a single input file is permitted. 96 .TP 97 .B \-E 98 Stop after preprocessing. 99 The preprocessed source is written to standard output, 100 or to 101 .I outfile 102 if 103 .B \-o 104 is given. 105 Cannot be combined with 106 .B \-M 107 or the stop flags 108 .BR \-S , 109 .BR \-k . 110 .TP 111 .B \-M 112 Emit a 113 .BR make (1) 114 dependency rule describing the 115 .B #include 116 dependencies of each source file, then exit. 117 No compilation is performed. 118 Cannot be combined with 119 .BR \-E . 120 .TP 121 .B \-S 122 Stop after compilation; do not assemble. 123 Assembly source is written to a file with the same base name as 124 the input and the suffix 125 .BR .s . 126 .SS Preprocessor 127 .TP 128 .BI \-D macro [ =value ] 129 Define the preprocessor macro 130 .I macro 131 with an optional replacement text 132 .IR value . 133 If 134 .I value 135 is omitted, the macro is defined with the value 136 .BR 1 . 137 This option may be repeated to define multiple macros. 138 .TP 139 .BI \-U macro 140 Undefine the preprocessor macro 141 .IR macro . 142 This option may be repeated. 143 .TP 144 .BI \-I dir 145 Prepend 146 .I dir 147 to the list of directories searched for header files. 148 User-specified directories are searched before system include 149 directories. 150 This option may be repeated. 151 .SS Optimisation 152 .TP 153 .BI \-O level 154 Specify the optimisation level. 155 This option is accepted for compatibility with other compiler 156 driver interfaces but is otherwise ignored; 157 .B scc-cc 158 does not perform its own optimisation passes. 159 .SS Linker 160 .TP 161 .BI \-L dir 162 Add 163 .I dir 164 to the list of directories searched for libraries. 165 .TP 166 .BI \-l lib 167 Link against the library 168 .IR lib . 169 .SS Output 170 .TP 171 .BI \-o " outfile" 172 Place the output into 173 .IR outfile . 174 When compiling and linking, the default output name is 175 .BR a.out . 176 When compiling to an object file 177 .RB ( \-c ), 178 the default output name is derived from the input file name. 179 .SS Debugging and Symbols 180 .TP 181 .B \-g 182 Generate debugging information. 183 This flag is forwarded to the assembler and linker. 184 .TP 185 .B \-s 186 Strip all symbol table and relocation information from the output 187 executable. 188 This flag is forwarded to the linker. 189 .SS Warnings 190 .TP 191 .B \-w 192 Enable warning messages for dubious constructs. 193 The flag is forwarded to 194 .BR cc1 . 195 .TP 196 .BI \-W param 197 Enable warnings. 198 The parameter 199 .I param 200 is ignored; the effect is the same as 201 .BR \-w . 202 Accepted for compatibility with other compiler driver interfaces. 203 .SS Target 204 .TP 205 .BI \-a " arch" 206 Select the target architecture. 207 Overrides the 208 .B ARCH 209 environment variable. 210 .TP 211 .BI \-t " sys" 212 Select the target operating system. 213 Overrides the 214 .B SYS 215 environment variable. 216 .SS Driver Behaviour 217 .TP 218 .B \-d 219 Enable verbose driver output. 220 The exact command line executed for each sub-process is printed 221 to standard error before that process is started. 222 .TP 223 .B \-k 224 Keep intermediate files. 225 When this flag is set, 226 .B scc-cc 227 saves the IR, QBE IR, and assembler output produced during 228 compilation alongside the object file, 229 using the base name of the input file with the suffixes 230 .BR .ir , 231 .BR .qbe , 232 and 233 .BR .s , 234 respectively. 235 The final object file is also kept even when linking. 236 .TP 237 .B \-q 238 Disable QBE mode. 239 .B cc2 240 produces native assembly directly, without invoking 241 .BR qbe (1). 242 .TP 243 .B \-Q 244 Enable QBE mode (default). 245 .B cc2 246 produces QBE IR, which is then compiled to native assembly by 247 .BR qbe (1). 248 .SS Compatibility Options 249 The following options are accepted and silently ignored for 250 compatibility with other compiler driver interfaces: 251 .BR \-static , 252 .BR \-dynamic , 253 .BR \-pedantic , 254 .BR \-pipe , 255 .BR \-ansi , 256 any option beginning with 257 .BR \-std= , 258 any 259 .BI \-f option 260 and any 261 .BI \-m option. 262 .SH COMPILATION PIPELINE 263 For each C source file, 264 .B scc-cc 265 constructs and runs the following pipeline: 266 .PP 267 .EX 268 cc1 | cc2[\-qbe_arch\-abi] | [qbe] | as 269 .EE 270 .PP 271 Each stage is a separate process. 272 The stages are connected by anonymous pipes so that no large 273 intermediate files are created on disk unless 274 .B \-k 275 is used. 276 .TP 277 .B cc1 278 The C compiler frontend. 279 It reads the C source file, preprocesses it, parses it, 280 performs type checking and semantic analysis, 281 and emits the scc intermediate representation (IR) to standard 282 output. 283 It is installed as 284 .IR $SCCPREFIX/libexec/scc/cc1 . 285 .TP 286 .B cc2 287 The C compiler backend. 288 It reads the scc IR and emits either native assembly or QBE IR. 289 The exact binary invoked depends on the target architecture, ABI, 290 and whether QBE mode is active. 291 In QBE mode (the default), the binary name has the form 292 .BI cc2\-qbe_ arch \- abi ; 293 in native mode 294 .RB ( \-q ) 295 the form is 296 .BI cc2\- arch \- abi . 297 These binaries are installed under 298 .IR $SCCPREFIX/libexec/scc/ . 299 .TP 300 .B qbe 301 The QBE compiler backend. 302 Only invoked in QBE mode. 303 It reads QBE IR and emits native assembly. 304 .B qbe 305 is looked up in the standard 306 .BR PATH . 307 .TP 308 .B as 309 The target assembler. 310 It assembles the native assembly into an object file. 311 The assembler command and its arguments are determined at 312 build time via the 313 .B ascmd 314 configuration variable in 315 .I sys.h 316 and may include 317 .B %a 318 (architecture), 319 .B %s 320 (system), 321 .B %b 322 (ABI), 323 .B %p 324 (library prefix), 325 and 326 .B %o 327 (output file) wildcards. 328 .PP 329 After all source files are compiled, the linker is invoked unless 330 .BR \-c , 331 .BR \-S , 332 .BR \-E , 333 or 334 .B \-M 335 suppresses linking: 336 .TP 337 .B ld 338 The target linker. 339 The linker command and its arguments are determined at build time 340 via the 341 .B ldcmd 342 configuration variable in 343 .IR sys.h . 344 The same wildcards as for 345 .B as 346 are supported, and 347 .B %c 348 expands to the full list of input object files. 349 .SH ENVIRONMENT VARIABLES 350 .TP 351 .B ARCH 352 Target architecture name (e.g. 353 .BR amd64 , 354 .BR arm64 , 355 .BR i386 ). 356 Overridden by 357 .BR \-a . 358 .TP 359 .B SYS 360 Target operating system name (e.g. 361 .BR linux , 362 .BR openbsd ). 363 Overridden by 364 .BR \-t . 365 .TP 366 .B ABI 367 Target ABI name (e.g. 368 .BR sysv ). 369 .TP 370 .B FORMAT 371 Target object file format (e.g. 372 .BR elf , 373 .BR coff ). 374 .TP 375 .B SCCPREFIX 376 Path prefix under which the scc suite is installed. 377 Used to locate 378 .B cc1 379 and 380 .B cc2 381 under 382 .IR $SCCPREFIX/libexec/scc/ . 383 If not set, the compile-time 384 .B PREFIX 385 value is used. 386 .TP 387 .B SCCLIBPREFIX 388 Path prefix for scc libraries. 389 Expanded from the 390 .B %p 391 wildcard in linker and assembler command templates. 392 If not set, the compile-time 393 .B LIBPREFIX 394 value is used. 395 .TP 396 .B TMPDIR 397 Directory used for temporary files created during compilation. 398 If not set or empty, the current directory is used. 399 .SH EXAMPLES 400 .PP 401 Compile a C source file and link into an executable: 402 .IP 403 .EX 404 scc-cc \-o hello hello.c 405 .EE 406 .PP 407 Compile to an object file only: 408 .IP 409 .EX 410 scc-cc \-c hello.c 411 .EE 412 .PP 413 Compile multiple source files and link: 414 .IP 415 .EX 416 scc-cc \-o prog main.c util.c \-lm 417 .EE 418 .PP 419 Preprocess only and view the output: 420 .IP 421 .EX 422 scc-cc \-E hello.c 423 .EE 424 .PP 425 Generate make dependency rules: 426 .IP 427 .EX 428 scc-cc \-M hello.c 429 .EE 430 .PP 431 Stop after compilation, keeping intermediate files: 432 .IP 433 .EX 434 scc-cc \-k \-c hello.c 435 .EE 436 .PP 437 Compile for a specific target: 438 .IP 439 .EX 440 ARCH=arm64 ABI=sysv SYS=linux scc-cc \-o hello hello.c 441 .EE 442 .PP 443 Compile in native mode (no QBE): 444 .IP 445 .EX 446 scc-cc \-q \-o hello hello.c 447 .EE 448 .PP 449 Show all sub-process command lines: 450 .IP 451 .EX 452 scc-cc \-d \-c hello.c 453 .EE 454 .PP 455 The 456 .B \-d 457 flag prints the exact command line of each sub-process to standard error. 458 For example, compiling 459 .I hello.c 460 on an amd64 Linux system in QBE mode produces: 461 .IP 462 .EX 463 /usr/local/libexec/scc/cc1 \-I /usr/local/include/scc/bits/amd64/ \e 464 \-I /usr/local/include/scc/bits/linux/ \e 465 \-I /usr/local/include/scc/bits/linux/amd64/ \e 466 \-I /usr/local/include/scc/ hello.c 467 /usr/local/libexec/scc/cc2\-qbe_amd64\-sysv 468 qbe \-t amd64_sysv 469 as \-o hello.o 470 .EE 471 .SH DIAGNOSTICS 472 When a sub-process in the compilation pipeline fails, 473 .B scc-cc 474 reports an error to standard error and exits with a non-zero status. 475 .PP 476 If 477 .B cc1 478 exits with a non-zero status, the error message comes from 479 .B cc1 480 itself (a compilation error such as a syntax or type error) and 481 .B scc-cc 482 exits silently. 483 Likewise, if the linker 484 .B ld 485 fails, its own error output is displayed and 486 .B scc-cc 487 exits without an additional message. 488 .PP 489 If any stage terminates by a signal 490 or any other stage in the pipeline 491 .RB ( cc2 , 492 .BR qbe , 493 or 494 .BR as ) 495 terminates with non-zero exit then 496 these conditions are considered an internal error. 497 In this case 498 .B scc-cc 499 prints the following message to standard error: 500 .IP 501 .EX 502 scc-cc:tool: internal error 503 .EE 504 .PP 505 where 506 .I tool 507 is the name of the failing sub-process. 508 This message indicates a bug in the toolchain rather than an error in 509 the user's source code. 510 The same message is printed if 511 .B scc-cc 512 cannot 513 .BR execvp (2) 514 the sub-process binary (for example because 515 .B SCCPREFIX 516 is set incorrectly and 517 .B cc1 518 or 519 .B cc2 520 cannot be found). 521 In this case, 522 Using the option 523 .B \-d 524 combined with 525 .B \-k 526 is very useful because 527 it provides all the information to run the tool in isolation 528 and debug the issue. 529 .SH SEE ALSO 530 .BR scc (1), 531 .BR scc\-cc1 (1), 532 .BR scc\-cc2 (1), 533 .BR scc\-cpp (1), 534 .BR scc\-ld (1), 535 .BR scc\-as (1), 536 .BR scc\-ir (7), 537 .BR qbe (1)