README (11606B)
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 - QBEBIN: macro with the name of the qbe binary. 212 213 - sysincludes: It is a list of diretories used to locate 214 the system headers 215 216 - ldcmd: It describes how the linker command line is built. 217 218 - ascmd: It describes how the assembler command line is built. 219 220 The definition of sysincludes, ldcmd and ascmd can include wildcards 221 represented by % followed by a single letter: 222 223 - %c: It expands to the full list of input object files of the linker 224 - %a: It expands to the architecture name 225 - %s: It expands to the system name 226 - %p: It expands to the library prefix 227 - %b: It expands too the ABI name 228 - %o: It expands to the output file of the current tool 229 230 Scc includes 3 configuration templates that can be used as base for the 231 configuration of the toolchain: 232 233 - scc: It uses GNU assembler and linker with the scc libc. 234 - scc_clang: It uses clang assembler and linker with the scc libc. 235 - musl: It uses GNU assembler and linker with the musl libc. 236 237 The file `include/bits/scc/sys.h` is automatically created from the scc 238 toolchain configuration with the default make target. The target config 239 can be used to only create the file based on the value of the variable 240 `LIBPROFILE` allowing the user to customize that file as needed. It is 241 important to highlight that the file is not removed by `make clean` 242 because it can contain local user modifications. You should use 243 `make distclean` to remove it. 244 245 Runtime dependencies 246 ==================== 247 248 Some configurations of scc require having the QBE [1] executable in the PATH, 249 whose version must support common storage which was incorporated in QBE 1.3. 250 251 [1] https://c9x.me/compile/ 252 253 Musl libc support 254 ================= 255 The scc libc is a C99 library and cannot be used to compile POSIX compliant 256 programs. Scc includes a template that can be used to use a musl libc 257 compiled by gcc, and to make easier to get the correct values it also 258 provides a specific target to configure scc for a correct support for musl: 259 260 $ make config-musl 261 $ make 262 $ make install 263 264 then you can use: 265 266 $ scc-cc hello.c 267 268 or 269 270 $ SCCLIBPREFIX=/usr/local/musl bin/scc hello.c 271 272 where `LIBPREFIX` points to the prefix used by your musl libc 273 installation. If the helper scc shell script is used instead of scc-cc 274 then the environment variable SCCLIBPREFIX must be set. Using the helper 275 scc script makes easier to use scc without installing and running it 276 directly from the bin directory after compilation. 277 278 The target config-musl uses the output of gcc -v to get a working 279 sys.h with the correct paths (it basically extracts the correct value 280 for the macro GCCLIBPATH used to locate the gcc crt object files). If 281 you are not able to use scc with musl after these steps, please take a 282 look to include/bits/scc/sys.h to see if it fits your system setup. 283 284 Deviations from standard C 285 =========================== 286 This compiler aims to be fully compatible with the C99 standard, but 287 it has some differences at this moment: 288 289 - Type qualifiers are accepted but partially ignored. 290 -------------------------------------------------- 291 292 The semantic behind them is not fully implemented, specially in the 293 case of volatile. Be aware that some programs can miswork for this 294 reason. 295 296 - Function type names 297 ------------------- 298 299 C99 allows you to define type names of function types and write something 300 like: 301 302 int f(int (int)); 303 304 Accepting function types in type names (or abstract declarators) makes the 305 grammar ambiguous because it is impossible to differentiate between: 306 307 (int (f)) -> function returning int with one parameter of type f 308 (int (f)) -> integer variable f 309 310 If you don't believe me try this code: 311 312 int 313 f(int g()) 314 { 315 return g(); 316 } 317 318 Function type names seem unnecessary, because they are used as 319 an alias of the function pointer types, but it is weird that something 320 like sizeof(int (int)) is not allowed (because here it should be 321 understood as the size of a function), but f(int (int)) is allowed 322 because it is understood as a parameter of function pointer type. 323 324 - Definition of variables with incomplete type 325 --------------------------------------------- 326 327 C89 allows the definition of variables with incomplete type that 328 have external linkage and file scope. The type of the variable is the 329 composition of all the definitions found in the file. The exact rules 330 are a bit complex (ANSI 3.7.2, or ISO C99 6.2.5p22) so SCC ignores them 331 at this moment by simply not allowing any definition of variables with 332 incomplete type. 333 334 If you don't believe me try this code: 335 336 struct foo x; 337 338 struct foo { 339 int i; 340 }; 341 342 - Variadic function alike macros 343 ------------------------------ 344 345 The standard (C99 6.10.3 c 4) forces passing more parameters than 346 the number of parameters present in the variadic argument list 347 (excluding ...). SCC accepts a parameter list with the same number 348 of arguments. 349 350 #define P(a, ...) a 351 352 P(1) 353 354 C99 libc 355 ======== 356 357 The C99 libc only supports the C locale using UTF-8 for multibyte 358 sequences. It also assumes that the wide character set includes 359 ASCII as a subset.