scc

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