scc-cc.man (10550B)
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 \-ansi , 255 any option beginning with 256 .BR \-std= , 257 any 258 .BI \-f option 259 and any 260 .BI \-m option. 261 .SH COMPILATION PIPELINE 262 For each C source file, 263 .B scc-cc 264 constructs and runs the following pipeline: 265 .PP 266 .EX 267 cc1 | cc2[\-qbe_arch\-abi] | [qbe] | as 268 .EE 269 .PP 270 Each stage is a separate process. 271 The stages are connected by anonymous pipes so that no large 272 intermediate files are created on disk unless 273 .B \-k 274 is used. 275 .TP 276 .B cc1 277 The C compiler frontend. 278 It reads the C source file, preprocesses it, parses it, 279 performs type checking and semantic analysis, 280 and emits the scc intermediate representation (IR) to standard 281 output. 282 It is installed as 283 .IR $SCCPREFIX/libexec/scc/cc1 . 284 .TP 285 .B cc2 286 The C compiler backend. 287 It reads the scc IR and emits either native assembly or QBE IR. 288 The exact binary invoked depends on the target architecture, ABI, 289 and whether QBE mode is active. 290 In QBE mode (the default), the binary name has the form 291 .BI cc2\-qbe_ arch \- abi ; 292 in native mode 293 .RB ( \-q ) 294 the form is 295 .BI cc2\- arch \- abi . 296 These binaries are installed under 297 .IR $SCCPREFIX/libexec/scc/ . 298 .TP 299 .B qbe 300 The QBE compiler backend. 301 Only invoked in QBE mode. 302 It reads QBE IR and emits native assembly. 303 .B qbe 304 is looked up in the standard 305 .BR PATH . 306 .TP 307 .B as 308 The target assembler. 309 It assembles the native assembly into an object file. 310 The assembler command and its arguments are determined at 311 build time via the 312 .B ascmd 313 configuration variable in 314 .I sys.h 315 and may include 316 .B %a 317 (architecture), 318 .B %s 319 (system), 320 .B %b 321 (ABI), 322 .B %p 323 (library prefix), 324 and 325 .B %o 326 (output file) wildcards. 327 .PP 328 After all source files are compiled, the linker is invoked unless 329 .BR \-c , 330 .BR \-S , 331 .BR \-E , 332 or 333 .B \-M 334 suppresses linking: 335 .TP 336 .B ld 337 The target linker. 338 The linker command and its arguments are determined at build time 339 via the 340 .B ldcmd 341 configuration variable in 342 .IR sys.h . 343 The same wildcards as for 344 .B as 345 are supported, and 346 .B %c 347 expands to the full list of input object files. 348 .SH ENVIRONMENT VARIABLES 349 .TP 350 .B ARCH 351 Target architecture name (e.g. 352 .BR amd64 , 353 .BR arm64 , 354 .BR i386 ). 355 Overridden by 356 .BR \-a . 357 .TP 358 .B SYS 359 Target operating system name (e.g. 360 .BR linux , 361 .BR openbsd ). 362 Overridden by 363 .BR \-t . 364 .TP 365 .B ABI 366 Target ABI name (e.g. 367 .BR sysv ). 368 .TP 369 .B FORMAT 370 Target object file format (e.g. 371 .BR elf , 372 .BR coff ). 373 .TP 374 .B SCCPREFIX 375 Path prefix under which the scc suite is installed. 376 Used to locate 377 .B cc1 378 and 379 .B cc2 380 under 381 .IR $SCCPREFIX/libexec/scc/ . 382 If not set, the compile-time 383 .B PREFIX 384 value is used. 385 .TP 386 .B SCCLIBPREFIX 387 Path prefix for scc libraries. 388 Expanded from the 389 .B %p 390 wildcard in linker and assembler command templates. 391 If not set, the compile-time 392 .B LIBPREFIX 393 value is used. 394 .TP 395 .B TMPDIR 396 Directory used for temporary files created during compilation. 397 If not set or empty, the current directory is used. 398 .SH EXAMPLES 399 .PP 400 Compile a C source file and link into an executable: 401 .IP 402 .EX 403 scc-cc \-o hello hello.c 404 .EE 405 .PP 406 Compile to an object file only: 407 .IP 408 .EX 409 scc-cc \-c hello.c 410 .EE 411 .PP 412 Compile multiple source files and link: 413 .IP 414 .EX 415 scc-cc \-o prog main.c util.c \-lm 416 .EE 417 .PP 418 Preprocess only and view the output: 419 .IP 420 .EX 421 scc-cc \-E hello.c 422 .EE 423 .PP 424 Generate make dependency rules: 425 .IP 426 .EX 427 scc-cc \-M hello.c 428 .EE 429 .PP 430 Stop after compilation, keeping intermediate files: 431 .IP 432 .EX 433 scc-cc \-k \-c hello.c 434 .EE 435 .PP 436 Compile for a specific target: 437 .IP 438 .EX 439 ARCH=arm64 ABI=sysv SYS=linux scc-cc \-o hello hello.c 440 .EE 441 .PP 442 Compile in native mode (no QBE): 443 .IP 444 .EX 445 scc-cc \-q \-o hello hello.c 446 .EE 447 .PP 448 Show all sub-process command lines: 449 .IP 450 .EX 451 scc-cc \-d \-c hello.c 452 .EE 453 .PP 454 The 455 .B \-d 456 flag prints the exact command line of each sub-process to standard error. 457 For example, compiling 458 .I hello.c 459 on an amd64 Linux system in QBE mode produces: 460 .IP 461 .EX 462 /usr/local/libexec/scc/cc1 \-I /usr/local/include/scc/bits/amd64/ \e 463 \-I /usr/local/include/scc/bits/linux/ \e 464 \-I /usr/local/include/scc/bits/linux/amd64/ \e 465 \-I /usr/local/include/scc/ hello.c 466 /usr/local/libexec/scc/cc2\-qbe_amd64\-sysv 467 qbe \-t amd64_sysv 468 as \-o hello.o 469 .EE 470 .SH DIAGNOSTICS 471 When a sub-process in the compilation pipeline fails, 472 .B scc-cc 473 reports an error to standard error and exits with a non-zero status. 474 .PP 475 If 476 .B cc1 477 exits with a non-zero status, the error message comes from 478 .B cc1 479 itself (a compilation error such as a syntax or type error) and 480 .B scc-cc 481 exits silently. 482 Likewise, if the linker 483 .B ld 484 fails, its own error output is displayed and 485 .B scc-cc 486 exits without an additional message. 487 .PP 488 If any stage terminates by a signal 489 or any other stage in the pipeline 490 .RB ( cc2 , 491 .BR qbe , 492 or 493 .BR as ) 494 terminates with non-zero exit then 495 these conditions are considered an internal error. 496 In this case 497 .B scc-cc 498 prints the following message to standard error: 499 .IP 500 .EX 501 scc-cc:tool: internal error 502 .EE 503 .PP 504 where 505 .I tool 506 is the name of the failing sub-process. 507 This message indicates a bug in the toolchain rather than an error in 508 the user's source code. 509 The same message is printed if 510 .B scc-cc 511 cannot 512 .BR execvp (2) 513 the sub-process binary (for example because 514 .B SCCPREFIX 515 is set incorrectly and 516 .B cc1 517 or 518 .B cc2 519 cannot be found). 520 In this case, 521 Using the option 522 .B \-d 523 combined with 524 .B \-k 525 is very useful because 526 it provides all the information to run the tool in isolation 527 and debug the issue. 528 .SH SEE ALSO 529 .BR scc (1), 530 .BR scc\-cc1 (1), 531 .BR scc\-cc2 (1), 532 .BR scc\-cpp (1), 533 .BR scc\-ld (1), 534 .BR scc\-as (1), 535 .BR scc\-ir (7), 536 .BR qbe (1)