Changes between Version 4 and Version 5 of Soclib Cc/Design Guide


Ignore:
Timestamp:
Mar 25, 2010, 2:50:26 PM (14 years ago)
Author:
Nicolas Pouillon
Comment:

--

Legend:

Unmodified
Added
Removed
Modified

  • Soclib Cc/Design Guide

    v4 v5  
    44== Why ? ==
    55
    6 === We use a lot of tricky things things ===
     6We use a lot of tricky things things:
    77
    88 * Different SystemC backends (SystemC-OSCI, SystemCASS, SoCView)
    99   each of them is a different implementation of the same LRM, and
    1010   yields incompatible objects
    11 
     11 * Metadata-based component definition, including used source files.
     12   Components are not necessarily implemented in an unique file, but
     13   may be scattered through different files, metadata does the glue.
    1214 * Templated classes. The usual way of using templated code is to
    1315   put all code in .h, having template code emitted at use in main C++
    14    file.
    15 
     16   file. [[BR]]
    1617   This is good for small utilities, but SystemC modules may
    1718   be more than 1000 lines-long, and more that 40 of them may be used
    1819   in a topcell. This may yield a single translation unit with more than
    1920   50000 lines of code, heavily templated. This implies some usage issues
    20    (compiler getting out of memory, unreasonnable compile times)
    21 
     21   (compiler getting out of memory, unreasonnable compile times). [[BR]]
    2222   Therefore we need two features:
    2323   * Separate implementation: Put template class definition and implementation
    2424     in two separate files. Compile them separately.
    25 
     25     [[BR]]
    2626     This implies template code must be explicitely instanciated with some
    2727     `template class Foo<parameters>;` code. It has to be done automatically.
    2828   * Object reuse: Once modules built separately, we can put objects
    2929     in a global repository and use the in a cached way.
    30 
    3130 * Different build modes (debugging, profiling release, others ??)
    3231
    33 === Reuse of current tools ?? ===
     32== Why not reuse existing tools ? ==
    3433
    3534This could be seen as reimplementing make, or even SCons, and this is
    36 not totally false. This is all about flexibility, and user-input
    37 readibility.
     35not totally false. But we added other features:
     36 * Template instantiation
     37 * Separate source enumeration
     38 * Object caching
    3839
    3940There is no build tool known out the which does object caching and
    4041template instantiation at the same time. Even if current build tools
    4142may be enhanced to do the job, this is not an easy task.
     43Moreover, resulting code would be a kludge.
     44This is all about flexibility, and user-input readability.
    4245
    43 This very tool has been implemented as a `make` wrapper before,
    44 generated Makefiles were unreadable (all templates parameters in the
    45 middle, ...), and it did not work so well.
     46Soclib-cc has been implemented as a `make` wrapper before,
     47it was not usable:
     48 * generated Makefiles were unreadable (all templates parameters in the middle, …)
     49 * it did not work so well (make interprets `:` a special way, and escaping is nearly unusable)
     50 * the code generator was a big ugly piece of software
     51 * we still had to do `.sd` file indexation.
    4652
     53= Design =
    4754
    48 = Configuration =
     55[[Image(soclib-cc.png,nolink)]]
    4956
    50 In order to compile SoCLib objects, we need:
    51  * a working SystemC installation
    52  * a working GNU-C++ compiler
     57= Usage =
    5358
    54 Soclib-cc processes three files in order:
    55  1. ''soclib-dir]''`/etc/soclib.conf`
    56  1. `~/.soclib/global.conf`
    57  1. `./soclib.conf`
    58 
    59 These files contain multiple concurrent configurations for building
    60 SoCLib. One of them will be chosen (explicitely) as the default
    61 one. Others may be used on demand (through command-line or local
    62 configuration file)
    63  * File ![1] is installation-global. It should be modified by the
    64    administrator for a network-wide configuration.
    65  * File ![2] is useful for a developper's own configuration. This
    66    allows to use a local development branch of a local SystemC, ...
    67  * File ![3] is directory-local, this allows to choose different
    68    flavours of previously declared configurations
    69 
    70 See SoclibConf for a usage guide to these files.
    71 
    72 == Usage ==
    73 
    74 Soclib-cc may be used two ways:
     59Soclib-cc may be used three ways:
    7560 * As a compiler wrapper. It will just be a CXX wrapper, handling
    7661   compilation or linkage on demand. This can be useful for external
    77    Makefile integration.
     62   Makefile integration. (the `-c` option)
     63 * As a component compiler (the `-1` option)
    7864 * As a complete platform compiler. From an ad-hoc platform definition
    7965   (wrappers can be written to accept other formats), the complete
    80    simulator will be compiled.
     66   simulator will be compiled. (the `-p` option)
    8167
    8268Try running `soclib-cc -h`.
    83 
    84 === As a compiler ===
    85 
    86 The usual way:
    87 
    88 {{{
    89 $ soclib-cc -c -o obj.o file.cc
    90 $ soclib-cc -o sim obj.o ...
    91 }}}
    92 
    93 === As a platform compiler ===
    94 
    95 {{{
    96 $ soclib-cc -p platform_def
    97 }}}
    98 
    99 == Global flags ==
    100 
    101  -v::
    102   Print command lines
    103  -q::
    104   Dont say anything
    105  -m MODE::
    106   Change compilation mode (release, debug, prof)
    107   This changes in an homogenous way the building
    108 
    109 
    110 == Object repository ==
    111 
    112 As objects can be reused between builds, or even between platforms, we
    113 may want to place objects in a global repository.
    114 
    115 Default repository is in current directory, in '$(SOCLIB)/repos/'. If you want,
    116 you can specify another absolute path in configuration.