README - scc - simple c99 compiler
git clone git://git.simple-cc.org/sccLogFilesRefsSubmodulesREADMELICENSE---
README (7255B)
---
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 four main 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
56 The main targets of the Makefile are:
57
58 - all:
59 Compile the toolchain and the libc. It automatically
60 determines what is the best value for HOST. It sets the
61 value of CONF for the toolchain that is used by the
62 toolchain as the default target. It also compiles the libc
63 for all the available configurations based in the host
64 architecture.
65
66 - config
67 Generate headers supposed to be customized by the user.
68
69 - toolchain
70 Compile the toolchain with the default configuration
71 specified in CONF. Beware that this target is executed without
72 the automatic detection of the host parameters. It makes
73 easier to cross compile.
74
75 - libc:
76 Compile the libc for the target specified in CONF. Beware
77 that this target is executed without the automatic detection
78 of the host parameters. It makes easier to cross compile.
79
80 - install:
81 Installs scc in PREFIX.
82
83 - clean:
84 Remove all the generated files except the one supposed to be edited
85 by the user.
86
87 - distclean
88 Remove all the generated files.
89
90 Toolchain configuration
91 =======================
92 At this moment scc is still using some external tools to generate
93 the final binaries. The toolchain execution is configured in the
94 file `include/scc/scc/sys.h` and it included basically 5 elements:
95
96 - LDBIN: macro with the name of the linker binary.
97
98 - ASBIN: macro with the name of the assembler binary.
99
100 - sysincludes: It is a list of diretories used to locate
101 the system headers
102
103 - ldcmd: It describes how the linker command line is built.
104
105 - ascmd: It describes how the assembler command line is built.
106
107 The definition of sysincludes, ldcmd and ascmd can include wildcards
108 represented by % followed by a single letter:
109
110 - %c: It expands to the full list of input object files of the linker
111 - %a: It expands to the architecture name
112 - %s: It expands to the system name
113 - %p: It expands to the library prefix
114 - %b: It expands too the ABI name
115 - %o: It expands to the output file of the current tool
116
117 Scc includes 3 configuration templates that can be used as base for the
118 configuration of the toolchain:
119
120 - scc: It uses GNU assembler and linker with the scc libc.
121 - scc_clang: It uses clang assembler and linker with the scc libc.
122 - musl: It uses GNU assembler and linker with the musl libc.
123
124 The file `include/scc/scc/sys.h` is automatically created from the scc
125 toolchain configuration with the default make target. The target config
126 can be used to only create the file based on the value of the variable
127 `LIBPROFILE` allowing the user to customize that file as needed. It is
128 important to highlight that the file is not removed by `make clean`
129 because it can contain local user modifications. You should use
130 `make distclean` to remove it.
131
132
133 Musl libc support
134 =================
135 The scc libc is a C99 library and cannot be used to compile POSIX compliant
136 programs. Scc includes a template that can be used to use a musl libc
137 compiled by gcc:
138
139 $ make LIBPROFILE=musl config
140
141 It will generate the files sys.h configured to be used with a musl
142 libc. Beware that it is likely that those files have to be customized to
143 fit your system because the macro GCCLIBPATH used by the musl template
144 depends heavily of the toolchain used to compile musl. As the musl libc
145 is likely installed in a different prefix the scc compilation must be
146 modified to:
147
148 $ make LIBPREFIX=/usr/local/musl # point to the prefix used by your musl
149
150 If the helper scc shell script is used instead of scc-cc then the
151 environment variable SCCLIBPREFIX must be set:
152
153 $ SCCLIBPREFIX=/usr/local/musl scc hello.c
154
155 Deviations from standard C
156 ===========================
157 This compiler aims to be fully compatible with the C99 standard, but
158 it has some differences at this moment:
159
160 - Type qualifiers are accepted but partially ignored.
161 --------------------------------------------------
162
163 The semantic behind them is not fully implemented, specially in the
164 case of volatile. Be aware that some programs can miswork for this
165 reason.
166
167 - Function type names
168 -------------------
169
170 C99 allows you to define type names of function types and write something
171 like:
172
173 int f(int (int));
174
175 Accepting function types in type names (or abstract declarators) makes the
176 grammar ambiguous because it is impossible to differentiate between:
177
178 (int (f)) -> function returning int with one parameter of type f
179 (int (f)) -> integer variable f
180
181 If you don't believe me try this code:
182
183 int
184 f(int g())
185 {
186 return g();
187 }
188
189 Function type names seem unnecesary , because they are used as
190 an alias of the function pointer types, but it is weird that something
191 like sizeof(int (int)) is not allowed (because here it should be
192 understood as the size of a function), but f(int (int)) is allowed
193 because it is understood as a parameter of function pointer type.
194
195 - Definition of variables with incomplete type
196 ---------------------------------------------
197
198 C89 allows the definition of variables with incomplete type that
199 have external linkage and file scope. The type of the variable is the
200 composition of all the definitions found in the file. The exact rules
201 are a bit complex (ANSI 3.7.2, or ISO C99 6.2.5p22) so SCC ignores them
202 at this moment by simply not allowing any definition of variables with
203 incomplete type.
204
205 If you don't believe me try this code:
206
207 struct foo x;
208
209 struct foo {
210 int i;
211 };
212
213 - Variadic function alike macros
214 ------------------------------
215
216 The standard (C99 6.10.3 c 4) forces passing more parameters than
217 the number of parameters present in the variadic argument list
218 (excluding ...). SCC accepts a parameter list with the same number
219 of arguments.
220
221 #define P(a, ...) a
222
223 P(1)
224
225 C99 libc
226 ========
227
228 The C99 libc only supports the C locale using UTF-8 for multibyte
229 sequences. It also assume that the wide character set includes as
230 ASCII as a subset.