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