scc

simple c99 compiler
git clone git://git.simple-cc.org/scc
Log | Files | Refs | Submodules | README | LICENSE

README (7430B)


      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/scc/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/scc/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.