1Compiling2=========34SCC is a portable toolchain that can be compiled on any UNIX system out5of the box. Compiling the project is so simple like:67 $ make89It will build scc selecting the more appropiate options for the host10system. In some situations (like for example when cross compiling),11can be desirable to select custom options for the build and use:1213 $ make config14 $ make1516and pass the required options the the config target. For example17if we want to cross compile scc for aarch64-linux-musl target18from a amd64-linux-gnu host system:1920 $ make CROSS_COMPILE=aarch64-linux-musl- CONF=arm64-linux config21 $ make2223The build system of scc supports parallel builds that will reduce24dramatically the build time.2526After a successful install the following programs are installed:2728 - gcc-scc: A wrapper shell script to use system cc and ld29 with the scc libc.3031 - scc: A wrapper shell script that allows the execution32 of any scc tool from any directory independently of the33 PREFIX used in the build. The tool can be selected as34 the first parameter (like for example `scc as` or `scc ar`)35 and by default is cc.3637 - scc-addr2line: A work in progress to implement a tool38 that is able to translate a hexadecimal address into39 a symbol.4041 - scc-ar: An archiver commonly used for static libraries.42 It is binary format agnostic, and it does not create an43 index independently of the objects stored in it. Both,44 coff and elf specify that an index should be created45 when the archive is created, but as this is not done46 by scc-ar, if you need an index you have to call47 directly to scc-ranlib.4849 - scc-cc: Driver of the compiler. It uses the compile50 time option PREFIX to locate helper programs and51 library files. This value can be overriden by the52 `SCCPREFIX` environment variable.5354 - scc-cpp: A wrapper shell script that uses scc-cc55 to preprocess a file without compiling it.5657 - scc-ld: A work in progress to implement a linker for58 the scc toolchain.5960 - scc-make: An implementation of POSIX make as defined61 in POSIX 2018. No POSIX 2024 support is planned in a62 near future.6364 - scc-nm: An implementation of POSIX nm.6566 - scc-objcopy: A work in progress of a GNU objcopy alike67 program.6869 - scc-objdump: A reduced version of the GUN objdump tool.70 It supports many of the options supported by the original71 tool, but in some cases it behaves slightly different.7273 - scc-ranlib: An implementation of a classical UNIX ranlib.74 While ranlib is not specified in current POSIX standards75 it is implemented in almost all the UNIX alike systems.76 In the case of scc, the ar implementation does not add77 index files by default, such a tool like ranlib is78 required.7980 - scc-size: An implementation of POSIX size.8182 - scc-strip: An implementation of POSIX strip.8384The toolchain has a good support for COFF files, and a basic support85for ELF files.8687config.mk88---------8990This file is generated when the config target is built. Once it is91generated it is used by any Makefile in the build system, and it is not92modified by the build system, allowing to the user doing any modifications93as required. This file incules the following options that can be overriden94in the command line of `make config`:9596 - TOOL: Specify the toolchain type to be used. Possible97 supported values are:9899 - clang100 - gcov101 - gnu102 - pcc103 - plan9104 - unix105106 - HOST: Specify the host system to be used. Possible supported107 values are:108109 - bsd110 - linux111 - obsd112 - plan9113 - posix114115 - CONF: Specify the build configuration used. It determines116 the default values for the architecture, ABI, system and117 binary format for the cross compiler. It also determines118 what versions of the libc are built (at this moment scc119 depends of external tools to build the libc and it limits120 the versions of the libc that can be built to the ones121 supported by the toolchain used to build scc itself).122123 - amd64-darwin124 - amd64-dragonfly125 - amd64-freebsd126 - amd64-linux127 - amd64-netbsd128 - amd64-openbsd129 - amd64-plan9130 - arm32-linux131 - arm64-linux132 - ppc32-linux133134 - CROSS_COMPILE: Specify a prefix name for the tools called by the135 Makefile.136137 - DESTDIR: Temporary directory prepend to PREFIX used in the138 install path. It is mainly intended to help package maintainers139 to install in a specific directory used as base for the package140 generation.141142 - PREFIX: Prefix of the path where scc toolchain is going143 to be installed. /usr/local by default.144145 - LIBPREFIX: Prefix of the path where scc searchs for146 headers and libraries when scc is executed. $PREFIX147 by default.148149 - LIBPROFILE: The profile used to configure the libc used by the150 target compiler.151152 - scc: The scc libc.153 - scc_clang: The scc libc, but using the clang assembler154 and linker.155 - musl: The linux musl libc.156157 - STD: What version of the C standard is used in the target158 compiler and libc.159160 - c89: ANSI or C90 ISO standard.161 - c99: C99 ISO standard.162163Not all the configurations have the same level of support in164the libc and in some cases the support is minimal.165166The main targets of the Makefile are:167168 - all:169 Compile the toolchain and the libc. It compiles the libc170 for all the available configurations based in the host171 architecture.172173 - dep:174 Generate inclusion dependencies, very useful while175 modifying the code. Beware that it creates files with176 the name `makefile` and changes to `Makefile` files177 are not reflected in the build proces until a `make distclean`178 or a `make dep` is executed again.179180 - 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 the184 Makefile, and they can be customized as required after being185 generated. They are removed by the `distclean` target.186187 - install:188 Installs scc in PREFIX.189190 - uninstall:191 Uninstall scc from PREFIX.192193 - clean:194 Remove all the generated files except the one supposed to be edited195 by the user.196197 - distclean198 Remove all the generated files, including the files generated by the199 config target that are not removed by the clean target.200201Toolchain configuration202=======================203At this moment scc is still using some external tools to generate204the final binaries. The toolchain execution is configured in the205file `include/bits/scc/sys.h` and it included basically 5 elements:206207 - LDBIN: macro with the name of the linker binary.208209 - ASBIN: macro with the name of the assembler binary.210211 - QBEBIN: macro with the name of the qbe binary.212213 - sysincludes: It is a list of diretories used to locate214 the system headers215216 - ldcmd: It describes how the linker command line is built.217218 - ascmd: It describes how the assembler command line is built.219220The definition of sysincludes, ldcmd and ascmd can include wildcards221represented by % followed by a single letter:222223 - %c: It expands to the full list of input object files of the linker224 - %a: It expands to the architecture name225 - %s: It expands to the system name226 - %p: It expands to the library prefix227 - %b: It expands too the ABI name228 - %o: It expands to the output file of the current tool229230Scc includes 3 configuration templates that can be used as base for the231configuration of the toolchain:232233 - 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.236237The file `include/bits/scc/sys.h` is automatically created from the scc238toolchain configuration with the default make target. The target config239can be used to only create the file based on the value of the variable240`LIBPROFILE` allowing the user to customize that file as needed. It is241important to highlight that the file is not removed by `make clean`242because it can contain local user modifications. You should use243`make distclean` to remove it.244245Runtime dependencies246====================247248Some configurations of scc require having the QBE [1] executable in the PATH,249whose version must support common storage which was incorporated in QBE 1.3.250251[1] https://c9x.me/compile/252253Musl libc support254=================255The scc libc is a C99 library and cannot be used to compile POSIX compliant256programs. Scc includes a template that can be used to use a musl libc257compiled by gcc, and to make easier to get the correct values it also258provides a specific target to configure scc for a correct support for musl:259260 $ make config-musl261 $ make262 $ make install263264then you can use:265266 $ scc-cc hello.c267268or269270 $ SCCLIBPREFIX=/usr/local/musl bin/scc hello.c271272where `LIBPREFIX` points to the prefix used by your musl libc273installation. If the helper scc shell script is used instead of scc-cc274then the environment variable SCCLIBPREFIX must be set. Using the helper275scc script makes easier to use scc without installing and running it276directly from the bin directory after compilation.277278The target config-musl uses the output of gcc -v to get a working279sys.h with the correct paths (it basically extracts the correct value280for the macro GCCLIBPATH used to locate the gcc crt object files). If281you are not able to use scc with musl after these steps, please take a282look to include/bits/scc/sys.h to see if it fits your system setup.283284Deviations from standard C285===========================286This compiler aims to be fully compatible with the C99 standard, but287it has some differences at this moment:288289- Type qualifiers are accepted but partially ignored.290 --------------------------------------------------291292The semantic behind them is not fully implemented, specially in the293case of volatile. Be aware that some programs can miswork for this294reason.295296- Function type names297 -------------------298299C99 allows you to define type names of function types and write something300like:301302int f(int (int));303304Accepting function types in type names (or abstract declarators) makes the305grammar ambiguous because it is impossible to differentiate between:306307 (int (f)) -> function returning int with one parameter of type f308 (int (f)) -> integer variable f309310If you don't believe me try this code:311312int313f(int g())314{315 return g();316}317318Function type names seem unnecessary, because they are used as319an alias of the function pointer types, but it is weird that something320like sizeof(int (int)) is not allowed (because here it should be321understood as the size of a function), but f(int (int)) is allowed322because it is understood as a parameter of function pointer type.323324- Definition of variables with incomplete type325 ---------------------------------------------326327C89 allows the definition of variables with incomplete type that328have external linkage and file scope. The type of the variable is the329composition of all the definitions found in the file. The exact rules330are a bit complex (ANSI 3.7.2, or ISO C99 6.2.5p22) so SCC ignores them331at this moment by simply not allowing any definition of variables with332incomplete type.333334If you don't believe me try this code:335336struct foo x;337338struct foo {339 int i;340};341342- Variadic function alike macros343 ------------------------------344345The standard (C99 6.10.3 c 4) forces passing more parameters than346the number of parameters present in the variadic argument list347(excluding ...). SCC accepts a parameter list with the same number348of arguments.349350#define P(a, ...) a351352P(1)353354C99 libc355========356357The C99 libc only supports the C locale using UTF-8 for multibyte358sequences. It also assumes that the wide character set includes359ASCII as a subset.