| 1 | |
| 2 | [[PageOutline()]] |
| 3 | |
| 4 | = Quick start = |
| 5 | |
| 6 | SoCLib's configuration file is used by [SoclibCc soclib-cc] to find |
| 7 | your tools paths. You may override: |
| 8 | * SystemC implementation to use (its paths, ...) |
| 9 | * Compiler and compiler flags |
| 10 | * Where objects reside |
| 11 | |
| 12 | Let's suppose we want to override SystemC's path, we can write the following `~/.soclib/global.conf`: |
| 13 | {{{ |
| 14 | config.systemc_22 = Config( |
| 15 | base = config.systemc, |
| 16 | dir = "/home/me/tools/systemc/2.2" |
| 17 | ) |
| 18 | |
| 19 | config.default = Config( |
| 20 | base = config.default, |
| 21 | systemc = config.systemc_22 |
| 22 | ) |
| 23 | }}} |
| 24 | |
| 25 | Now let's suppose we would like to add another configuration where we use SystemCass. |
| 26 | We don't want compiled objects to mix-up, so we'll set another built files repository. |
| 27 | |
| 28 | {{{ |
| 29 | config.systemc_cass = Config( |
| 30 | base = config.systemc, |
| 31 | dir = "/home/me/tools/systemc/cass", |
| 32 | libs = config.systemc.libs + ["-Wl,-rpath,%(libdir)s", "-ldl", "-fopenmp"], |
| 33 | ) |
| 34 | |
| 35 | config.use_systemcass = Config( |
| 36 | base = config.default, |
| 37 | repos = "repos/systemcass_objs", |
| 38 | systemc = config.systemc_cass |
| 39 | ) |
| 40 | }}} |
| 41 | |
| 42 | Now if we want to compile a platform with SystemCass, the only thing to is to tell it to `soclib-cc`: |
| 43 | {{{ |
| 44 | $ soclib-cc -t use_systemcass |
| 45 | }}} |
| 46 | |
| 47 | The argument after `-t` is the configuration name, attribute set to `config` in this line: |
| 48 | {{{ |
| 49 | config.use_systemcass = Config( .... |
| 50 | }}} |
| 51 | |
| 52 | = The long theory = |
| 53 | |
| 54 | == Default configuration == |
| 55 | |
| 56 | SoCLib's configuration file is using inherence in order to be able to share |
| 57 | parameters among different similar instances. |
| 58 | |
| 59 | There are 3 base configurations to inherit from: |
| 60 | * `config.toolchain` to define a compiler suite |
| 61 | * `config.systemc` to define a SystemC implementation |
| 62 | * `config.build_env` to define a build environment. This one must reference one instance of each of the above. |
| 63 | |
| 64 | There are 2 default configuration classes: |
| 65 | * `config.systemc`. |
| 66 | * It inherits from `config.systemc`, you may inherit from either of them |
| 67 | * It expects the environment variable `$SYSTEMC` to point to your actual SystemC installation directory |
| 68 | * `config.default`. |
| 69 | * It inherits from `config.build_env`, you may inherit from either of them |
| 70 | * It uses the default compiler (`gcc` & `g++`) and `config.systemc` |
| 71 | |
| 72 | == Inheriting == |
| 73 | |
| 74 | Inherence is written using `base =` as follows: |
| 75 | {{{ |
| 76 | my_new_config = Config( |
| 77 | base = parent, |
| 78 | other_var = .... |
| 79 | ) |
| 80 | }}} |
| 81 | |
| 82 | `config` is a global object defined by configuration system. It holds current configuration status. |
| 83 | |
| 84 | == Variables == |
| 85 | |
| 86 | `soclib-cc`'s `-t` ''arg'' option will change used configuration. It will make configuration system look for |
| 87 | `config.`''arg''. You should have defined it before. |
| 88 | |
| 89 | == What was done in quick start == |
| 90 | |
| 91 | {{{ |
| 92 | |
| 93 | # Defining a SystemC implementation inheriting everything |
| 94 | # from default SystemC declaration |
| 95 | config.systemc_22 = Config( |
| 96 | base = config.systemc, |
| 97 | dir = "/home/me/tools/systemc/2.2" |
| 98 | ) |
| 99 | |
| 100 | # Then defining a new default configuration, |
| 101 | # inheriting from previous default configuration |
| 102 | config.default = Config( |
| 103 | base = config.default, |
| 104 | systemc = config.systemc_22, |
| 105 | ) |
| 106 | |
| 107 | # Now with SystemCASS |
| 108 | |
| 109 | # Declare a new SystemC implementation |
| 110 | config.systemc_cass = Config( |
| 111 | base = config.systemc, |
| 112 | dir = "/home/me/tools/systemc/cass", |
| 113 | ) |
| 114 | |
| 115 | config.use_systemcass = Config( |
| 116 | base = config.default, |
| 117 | |
| 118 | # This defines a new path to store compiled objects to |
| 119 | # See 'fields' section below |
| 120 | repos = "repos/systemcass_objs", |
| 121 | |
| 122 | # and here we tell this configuration use the SystemC implentation |
| 123 | # declared above. |
| 124 | systemc = config.systemc_cass, |
| 125 | ) |
| 126 | }}} |
| 127 | |
| 128 | = Fields = |
| 129 | |
| 130 | You may put "%(''name'')s" anywhere in strings used for expansion, this will expand to |
| 131 | value of `name` attribute in the same class. See `systemc` definition below. |
| 132 | |
| 133 | == Build environment == |
| 134 | |
| 135 | This is the one you may specify from command line with `-t`. By default, this is |
| 136 | `default`. It inherits directly or indirectly from `config.build_env`. |
| 137 | |
| 138 | toolchain:: |
| 139 | A class derived from `config.toolchain` |
| 140 | systemc:: |
| 141 | A class derived from `config.systemc` |
| 142 | mode:: |
| 143 | Default mode. default: "release" |
| 144 | repos:: |
| 145 | Path where object files are stored, it may be absolute or relative to current path (where soclib-cc is run) |
| 146 | |
| 147 | == SystemC == |
| 148 | |
| 149 | `dir`:: |
| 150 | The directory containing SystemC installation |
| 151 | `os`:: |
| 152 | The current os, for expansion in following variable |
| 153 | `libdir`:: |
| 154 | "%(dir)s/lib-%(os)s" |
| 155 | `libs`:: |
| 156 | Link flags. default: ['-L%(libdir)s', '-lsystemc'] |
| 157 | `cflags`:: |
| 158 | Cflags. default: [ '-I%(dir)s/include' ] |
| 159 | |
| 160 | == Toolchain == |
| 161 | |
| 162 | `prefix`:: |
| 163 | a string prepended to all tollchain tools. (eg: "i686-pc-linux-gnu-") |
| 164 | `cflags`:: |
| 165 | global cflags. default: "-Wall" |
| 166 | `libs`:: |
| 167 | global linking arguments. default: "-lbfd" |
| 168 | `release_cflags`:: |
| 169 | cflags used for a "release" build, ie everyday build. default: "-O2" |
| 170 | `release_libs`:: |
| 171 | linking arguments for a "release" build. default: none |
| 172 | `debug_cflags`:: |
| 173 | cflags used for a "debug" build, ie when there is a bug to nail down. default: "-ggdb" |
| 174 | `debug_libs`:: |
| 175 | linking arguments for a "debug" build. default: none |
| 176 | `prof_cflags`:: |
| 177 | cflags used for a "profiling" build, ie performance test build. default: "-pg" |
| 178 | `prof_libs`:: |
| 179 | linking arguments for a "profiling" build. default: "-pg" |
| 180 | `max_processes`:: |
| 181 | Maximum simultaneous compilation processes run (same as -j command-line flag) |
| 182 | `max_name_length`:: |
| 183 | Maximum file name length for the file system `repos` |
| 184 | is located in. If object file has a longer name, |
| 185 | it is hashed to get a shorter one, around 16 chars. |
| 186 | |
| 187 | * Cflags used for compilation will be `cflags` + ''mode''`_cflags` |
| 188 | * Libs used for compilation will be `libs` + ''mode''`_libs` |
| 189 | * ''mode'' is selected in current build environment, or on command line (flag `-m`) |
| 190 | |
| 191 | = Adding other component libraries to soclib-cc search path = |
| 192 | |
| 193 | Soclib-cc searches metadata files in soclib's module directories. This default behavior can |
| 194 | be tweaked to add other paths on search list. Simply call `addDescPath` in any of your configuration |
| 195 | files: |
| 196 | {{{ |
| 197 | config.addDescPath("/path/to/my/components") |
| 198 | }}} |
| 199 | |
| 200 | This method may be called more than once to add more directories. |