README - scc - simple c99 compiler
(HTM) git clone git://git.simple-cc.org/scc
(DIR) Log
(DIR) Files
(DIR) Refs
(DIR) Submodules
(DIR) README
(DIR) LICENSE
---
README (7432B)
---
1 Compiling
2 =========
3
4 SCC is a portable toolchain that can be compiled on any UNIX system
5 out of the box. It supports several configuration options that
6 can be passed to the command line:
7
8 - PREFIX: Prefix of the path where scc toolchain is going
9 to be installed. /usr/local by default.
10
11 - LIBPREFIX: Prefix of the path where scc searchs for
12 headers and libraries when scc is executed. $PREFIX
13 by default.
14
15 - DESTDIR: Temporary directory prepend to PREFIX used in the
16 install path. It is mainly intended to help package maintainers
17 to install in a specific directory used as base for the package
18 generation.
19
20 - CROSS_COMPILE:
21 Specify a prefix name for the tools called by the Makefile.
22
23 - HOST:
24 Specify the host system to be used. Possible supported
25 values are:
26
27 - unix (by default)
28 - bsd
29 - plan9
30
31 - CONF: Specify which version of libc to build.
32 Once the build process completes only the target specified in
33 CONF will be built. Supported values are:
34
35 - amd64-linux (default)
36 - amd64-darwin
37 - amd64-openbsd
38 - arm64-linux
39 - amd64-dragonfly
40 - amd64-freebsd
41 - amd64-netbsd
42 - arm32-linux
43 - i386-linux
44
45 Not all the configurations have the same level of support in
46 the libc and in some cases the support is minimal.
47
48 - TOOL: Specify the toolchain type to be used. Possible
49 supported values are:
50
51 - unix (by default)
52 - gnu
53 - gnu-darwin
54 - clang
55 - pcc
56 - plan9
57
58 Beware that the default target selects the appropiate value for HOST,
59 CONF and TOOL. In case of being needed, TOOL can be still overloaded
60 in the command line.
61
62 The main targets of the Makefile are:
63
64 - all:
65 Compile the toolchain and the libc. It automatically
66 determines what is the best value for HOST. It sets the
67 value of CONF for the toolchain that is used by the
68 toolchain as the default target. It also compiles the libc
69 for all the available configurations based in the host
70 architecture.
71
72 - config
73 Generate headers supposed to be customized by the user.
74
75 - toolchain
76 Compile the toolchain with the default configuration
77 specified in CONF. Beware that this target is executed without
78 the automatic detection of the host parameters. It makes
79 easier to cross compile.
80
81 - libc:
82 Compile the libc for the target specified in CONF. Beware
83 that this target is executed without the automatic detection
84 of the host parameters. It makes easier to cross compile.
85
86 - install:
87 Installs scc in PREFIX.
88
89 - clean:
90 Remove all the generated files except the one supposed to be edited
91 by the user.
92
93 - distclean
94 Remove all the generated files.
95
96 Toolchain configuration
97 =======================
98 At this moment scc is still using some external tools to generate
99 the final binaries. The toolchain execution is configured in the
100 file `include/bits/scc/sys.h` and it included basically 5 elements:
101
102 - LDBIN: macro with the name of the linker binary.
103
104 - ASBIN: macro with the name of the assembler binary.
105
106 - sysincludes: It is a list of diretories used to locate
107 the system headers
108
109 - ldcmd: It describes how the linker command line is built.
110
111 - ascmd: It describes how the assembler command line is built.
112
113 The definition of sysincludes, ldcmd and ascmd can include wildcards
114 represented by % followed by a single letter:
115
116 - %c: It expands to the full list of input object files of the linker
117 - %a: It expands to the architecture name
118 - %s: It expands to the system name
119 - %p: It expands to the library prefix
120 - %b: It expands too the ABI name
121 - %o: It expands to the output file of the current tool
122
123 Scc includes 3 configuration templates that can be used as base for the
124 configuration of the toolchain:
125
126 - scc: It uses GNU assembler and linker with the scc libc.
127 - scc_clang: It uses clang assembler and linker with the scc libc.
128 - musl: It uses GNU assembler and linker with the musl libc.
129
130 The file `include/bits/scc/sys.h` is automatically created from the scc
131 toolchain configuration with the default make target. The target config
132 can be used to only create the file based on the value of the variable
133 `LIBPROFILE` allowing the user to customize that file as needed. It is
134 important to highlight that the file is not removed by `make clean`
135 because it can contain local user modifications. You should use
136 `make distclean` to remove it.
137
138
139 Musl libc support
140 =================
141 The scc libc is a C99 library and cannot be used to compile POSIX compliant
142 programs. Scc includes a template that can be used to use a musl libc
143 compiled by gcc:
144
145 $ make LIBPROFILE=musl config
146
147 It will generate the files sys.h configured to be used with a musl
148 libc. Beware that it is likely that those files have to be customized to
149 fit your system because the macro GCCLIBPATH used by the musl template
150 depends heavily of the toolchain used to compile musl. As the musl libc
151 is likely installed in a different prefix the scc compilation must be
152 modified to:
153
154 $ make LIBPREFIX=/usr/local/musl # point to the prefix used by your musl
155
156 If the helper scc shell script is used instead of scc-cc then the
157 environment variable SCCLIBPREFIX must be set:
158
159 $ SCCLIBPREFIX=/usr/local/musl scc hello.c
160
161 Deviations from standard C
162 ===========================
163 This compiler aims to be fully compatible with the C99 standard, but
164 it has some differences at this moment:
165
166 - Type qualifiers are accepted but partially ignored.
167 --------------------------------------------------
168
169 The semantic behind them is not fully implemented, specially in the
170 case of volatile. Be aware that some programs can miswork for this
171 reason.
172
173 - Function type names
174 -------------------
175
176 C99 allows you to define type names of function types and write something
177 like:
178
179 int f(int (int));
180
181 Accepting function types in type names (or abstract declarators) makes the
182 grammar ambiguous because it is impossible to differentiate between:
183
184 (int (f)) -> function returning int with one parameter of type f
185 (int (f)) -> integer variable f
186
187 If you don't believe me try this code:
188
189 int
190 f(int g())
191 {
192 return g();
193 }
194
195 Function type names seem unnecesary , because they are used as
196 an alias of the function pointer types, but it is weird that something
197 like sizeof(int (int)) is not allowed (because here it should be
198 understood as the size of a function), but f(int (int)) is allowed
199 because it is understood as a parameter of function pointer type.
200
201 - Definition of variables with incomplete type
202 ---------------------------------------------
203
204 C89 allows the definition of variables with incomplete type that
205 have external linkage and file scope. The type of the variable is the
206 composition of all the definitions found in the file. The exact rules
207 are a bit complex (ANSI 3.7.2, or ISO C99 6.2.5p22) so SCC ignores them
208 at this moment by simply not allowing any definition of variables with
209 incomplete type.
210
211 If you don't believe me try this code:
212
213 struct foo x;
214
215 struct foo {
216 int i;
217 };
218
219 - Variadic function alike macros
220 ------------------------------
221
222 The standard (C99 6.10.3 c 4) forces passing more parameters than
223 the number of parameters present in the variadic argument list
224 (excluding ...). SCC accepts a parameter list with the same number
225 of arguments.
226
227 #define P(a, ...) a
228
229 P(1)
230
231 C99 libc
232 ========
233
234 The C99 libc only supports the C locale using UTF-8 for multibyte
235 sequences. It also assumes that the wide character set includes
236 ASCII as a subset.