GOPHERSPACE.DE - P H O X Y
gophering on gopher.simple-cc.org
README - scc - simple c99 compiler
git clone git://git.simple-cc.org/scc
Log
Files
Refs
Submodules
README
LICENSE
---
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.