README - scc - simple c99 compiler
HTML git clone git://git.simple-cc.org/scc
DIR Log
DIR Files
DIR Refs
DIR Submodules
DIR README
DIR LICENSE
---
README (11652B)
---
1 Compiling
2 =========
3
4 SCC is a portable toolchain that can be compiled on any UNIX system out
5 of the box. Compiling the project is so simple like:
6
7 $ make
8
9 It will build scc selecting the more appropiate options for the host
10 system. In some situations (like for example when cross compiling),
11 can be desirable to select custom options for the build and use:
12
13 $ make config
14 $ make
15
16 and pass the required options the the config target. For example
17 if we want to cross compile scc for aarch64-linux-musl target
18 from a amd64-linux-gnu host system:
19
20 $ make CROSS_COMPILE=aarch64-linux-musl- CONF=arm64-linux config
21 $ make
22
23 The build system of scc supports parallel builds that will reduce
24 dramatically the build time.
25
26 After a successful install the following programs are installed:
27
28 - gcc-scc: A wrapper shell script to use system cc and ld
29 with the scc libc.
30
31 - scc: A wrapper shell script that allows the execution
32 of any scc tool from any directory independently of the
33 PREFIX used in the build. The tool can be selected as
34 the first parameter (like for example `scc as` or `scc ar`)
35 and by default is cc.
36
37 - scc-addr2line: A work in progress to implement a tool
38 that is able to translate a hexadecimal address into
39 a symbol.
40
41 - scc-ar: An archiver commonly used for static libraries.
42 It is binary format agnostic, and it does not create an
43 index independently of the objects stored in it. Both,
44 coff and elf specify that an index should be created
45 when the archive is created, but as this is not done
46 by scc-ar, if you need an index you have to call
47 directly to scc-ranlib.
48
49 - scc-cc: Driver of the compiler. It uses the compile
50 time option PREFIX to locate helper programs and
51 library files. This value can be overriden by the
52 `SCCPREFIX` environment variable.
53
54 - scc-cpp: A wrapper shell script that uses scc-cc
55 to preprocess a file without compiling it.
56
57 - scc-ld: A work in progress to implement a linker for
58 the scc toolchain.
59
60 - scc-make: An implementation of POSIX make as defined
61 in POSIX 2018. No POSIX 2024 support is planned in a
62 near future.
63
64 - scc-nm: An implementation of POSIX nm.
65
66 - scc-objcopy: A work in progress of a GNU objcopy alike
67 program.
68
69 - scc-objdump: A reduced version of the GUN objdump tool.
70 It supports many of the options supported by the original
71 tool, but in some cases it behaves slightly different.
72
73 - scc-ranlib: An implementation of a classical UNIX ranlib.
74 While ranlib is not specified in current POSIX standards
75 it is implemented in almost all the UNIX alike systems.
76 In the case of scc, the ar implementation does not add
77 index files by default, such a tool like ranlib is
78 required.
79
80 - scc-size: An implementation of POSIX size.
81
82 - scc-strip: An implementation of POSIX strip.
83
84 The toolchain has a good support for COFF files, and a basic support
85 for ELF files.
86
87 config.mk
88 ---------
89
90 This file is generated when the config target is built. Once it is
91 generated it is used by any Makefile in the build system, and it is not
92 modified by the build system, allowing to the user doing any modifications
93 as required. This file incules the following options that can be overriden
94 in the command line of `make config`:
95
96 - TOOL: Specify the toolchain type to be used. Possible
97 supported values are:
98
99 - clang
100 - gcov
101 - gnu
102 - pcc
103 - plan9
104 - unix
105
106 - HOST: Specify the host system to be used. Possible supported
107 values are:
108
109 - bsd
110 - linux
111 - obsd
112 - plan9
113 - posix
114
115 - CONF: Specify the build configuration used. It determines
116 the default values for the architecture, ABI, system and
117 binary format for the cross compiler. It also determines
118 what versions of the libc are built (at this moment scc
119 depends of external tools to build the libc and it limits
120 the versions of the libc that can be built to the ones
121 supported by the toolchain used to build scc itself).
122
123 - amd64-darwin
124 - amd64-dragonfly
125 - amd64-freebsd
126 - amd64-linux
127 - amd64-netbsd
128 - amd64-openbsd
129 - amd64-plan9
130 - arm32-linux
131 - arm64-linux
132 - ppc32-linux
133
134 - CROSS_COMPILE: Specify a prefix name for the tools called by the
135 Makefile.
136
137 - DESTDIR: Temporary directory prepend to PREFIX used in the
138 install path. It is mainly intended to help package maintainers
139 to install in a specific directory used as base for the package
140 generation.
141
142 - PREFIX: Prefix of the path where scc toolchain is going
143 to be installed. /usr/local by default.
144
145 - LIBPREFIX: Prefix of the path where scc searchs for
146 headers and libraries when scc is executed. $PREFIX
147 by default.
148
149 - LIBPROFILE: The profile used to configure the libc used by the
150 target compiler.
151
152 - scc: The scc libc.
153 - scc_clang: The scc libc, but using the clang assembler
154 and linker.
155 - musl: The linux musl libc.
156
157 - STD: What version of the C standard is used in the target
158 compiler and libc.
159
160 - c89: ANSI or C90 ISO standard.
161 - c99: C99 ISO standard.
162
163 Not all the configurations have the same level of support in
164 the libc and in some cases the support is minimal.
165
166 The main targets of the Makefile are:
167
168 - all:
169 Compile the toolchain and the libc. It compiles the libc
170 for all the available configurations based in the host
171 architecture.
172
173 - dep:
174 Generate inclusion dependencies, very useful while
175 modifying the code. Beware that it creates files with
176 the name `makefile` and changes to `Makefile` files
177 are not reflected in the build proces until a `make distclean`
178 or a `make dep` is executed again.
179
180 - config:
181 Generate config.mk and the headers `include/bits/scc/sys.h`,
182 `include/bits/scc/std.h` and `include/bits/scc/config.h`.
183 These files are not modified by any other target of the
184 Makefile, and they can be customized as required after being
185 generated. They are removed by the `distclean` target.
186
187 - install:
188 Installs scc in PREFIX.
189
190 - uninstall:
191 Uninstall scc from PREFIX.
192
193 - clean:
194 Remove all the generated files except the one supposed to be edited
195 by the user.
196
197 - distclean
198 Remove all the generated files, including the files generated by the
199 config target that are not removed by the clean target.
200
201 Toolchain configuration
202 =======================
203 At this moment scc is still using some external tools to generate
204 the final binaries. The toolchain execution is configured in the
205 file `include/bits/scc/sys.h` and it included basically 5 elements:
206
207 - LDBIN: macro with the name of the linker binary.
208
209 - ASBIN: macro with the name of the assembler binary.
210
211 - sysincludes: It is a list of diretories used to locate
212 the system headers
213
214 - ldcmd: It describes how the linker command line is built.
215
216 - ascmd: It describes how the assembler command line is built.
217
218 The definition of sysincludes, ldcmd and ascmd can include wildcards
219 represented by % followed by a single letter:
220
221 - %c: It expands to the full list of input object files of the linker
222 - %a: It expands to the architecture name
223 - %s: It expands to the system name
224 - %p: It expands to the library prefix
225 - %b: It expands too the ABI name
226 - %o: It expands to the output file of the current tool
227
228 Scc includes 3 configuration templates that can be used as base for the
229 configuration of the toolchain:
230
231 - scc: It uses GNU assembler and linker with the scc libc.
232 - scc_clang: It uses clang assembler and linker with the scc libc.
233 - musl: It uses GNU assembler and linker with the musl libc.
234
235 The file `include/bits/scc/sys.h` is automatically created from the scc
236 toolchain configuration with the default make target. The target config
237 can be used to only create the file based on the value of the variable
238 `LIBPROFILE` allowing the user to customize that file as needed. It is
239 important to highlight that the file is not removed by `make clean`
240 because it can contain local user modifications. You should use
241 `make distclean` to remove it.
242
243 Runtime dependencies
244 ====================
245
246 Some configurations of scc require having the QBE [1] executable in the PATH,
247 whose version must support common storage which was incorporated to it after
248 the commit 8ded7a5, but it is not part of a stable release of QBE yet.
249
250 [1] https://c9x.me/compile/
251
252 Musl libc support
253 =================
254 The scc libc is a C99 library and cannot be used to compile POSIX compliant
255 programs. Scc includes a template that can be used to use a musl libc
256 compiled by gcc, and to make easier to get the correct values it also
257 provides a specific target to configure scc for a correct support for musl:
258
259 $ make LIBPREFIX=/usr/local/musl config-musl
260 $ make
261 $ make install
262
263 then you can use:
264
265 $ scc-cc hello.c
266
267 or
268
269 $ SCCLIBPREFIX=/usr/local/musl bin/scc hello.c
270
271 where `LIBPREFIX` points to the prefix used by your musl libc
272 installation. If the helper scc shell script is used instead of scc-cc
273 then the environment variable SCCLIBPREFIX must be set. Using the helper
274 scc script makes easier to use scc without installing and running it
275 directly from the bin directory after compilation.
276
277 The target config-musl uses the output of gcc -v to get a working
278 sys.h with the correct paths (it basically extracts the correct value
279 for the macro GCCLIBPATH used to locate the gcc crt object files). If
280 you are not able to use scc with musl after these steps, please take a
281 look to include/bits/scc/sys.h to see if it fits your system setup.
282
283 Deviations from standard C
284 ===========================
285 This compiler aims to be fully compatible with the C99 standard, but
286 it has some differences at this moment:
287
288 - Type qualifiers are accepted but partially ignored.
289 --------------------------------------------------
290
291 The semantic behind them is not fully implemented, specially in the
292 case of volatile. Be aware that some programs can miswork for this
293 reason.
294
295 - Function type names
296 -------------------
297
298 C99 allows you to define type names of function types and write something
299 like:
300
301 int f(int (int));
302
303 Accepting function types in type names (or abstract declarators) makes the
304 grammar ambiguous because it is impossible to differentiate between:
305
306 (int (f)) -> function returning int with one parameter of type f
307 (int (f)) -> integer variable f
308
309 If you don't believe me try this code:
310
311 int
312 f(int g())
313 {
314 return g();
315 }
316
317 Function type names seem unnecesary , because they are used as
318 an alias of the function pointer types, but it is weird that something
319 like sizeof(int (int)) is not allowed (because here it should be
320 understood as the size of a function), but f(int (int)) is allowed
321 because it is understood as a parameter of function pointer type.
322
323 - Definition of variables with incomplete type
324 ---------------------------------------------
325
326 C89 allows the definition of variables with incomplete type that
327 have external linkage and file scope. The type of the variable is the
328 composition of all the definitions found in the file. The exact rules
329 are a bit complex (ANSI 3.7.2, or ISO C99 6.2.5p22) so SCC ignores them
330 at this moment by simply not allowing any definition of variables with
331 incomplete type.
332
333 If you don't believe me try this code:
334
335 struct foo x;
336
337 struct foo {
338 int i;
339 };
340
341 - Variadic function alike macros
342 ------------------------------
343
344 The standard (C99 6.10.3 c 4) forces passing more parameters than
345 the number of parameters present in the variadic argument list
346 (excluding ...). SCC accepts a parameter list with the same number
347 of arguments.
348
349 #define P(a, ...) a
350
351 P(1)
352
353 C99 libc
354 ========
355
356 The C99 libc only supports the C locale using UTF-8 for multibyte
357 sequences. It also assumes that the wide character set includes
358 ASCII as a subset.