Changes between Version 1 and Version 2 of Soclib Cc/Soclib Conf

Timestamp:

May 19, 2010, 10:36:07 PM (14 years ago)

Author:

Nicolas Pouillon

Comment:

--

Soclib Cc/Soclib Conf

@@ -6 +6 @@
 SoCLib's configuration file is used by [SoclibCc soclib-cc] to find
 your tools paths. You may override:
- * SystemC implementation to use (its paths, ...)
- * Compiler and compiler flags
- * Where objects reside
+ * libraries: SystemC implementation to use (its paths, ...), tlm, ...
+ * toolchain: Compiler and compiler flags
+ * build env: toolchain, libraries and other flags (where objects reside, ...)
 
 Let's suppose we want to override SystemC's path, we can write the following `~/.soclib/global.conf`:
 {{{
-config.systemc_22 = Config(
-        base = config.systemc,
+config.libsystemc_22 = Library(
+        parent = config.systemc,
         dir = "/home/me/tools/systemc/2.2"
         )
 
-config.default = Config(
-        base = config.default,
-        systemc = config.systemc_22
-        )
+config.foo = BuildEnv(
+        parent = config.build_env,
+        libraries = [config.libsystemc_22],
+        )
+
+config.default = config.foo
 }}}
 
 Now let's suppose we would like to add another configuration where we use SystemCass.
-We don't want compiled objects to mix-up, so we'll set another built files repository.
-
-{{{
-config.systemc_cass = Config(
-        base = config.systemc,
+We don't want compiled objects to mix-up, so we'll set another repository for built files.
+
+{{{
+config.libsystemcass = Library(
+        parent = config.systemc,
         dir = "/home/me/tools/systemc/cass",
         libs = config.systemc.libs + ["-Wl,-rpath,%(libdir)s", "-ldl", "-fopenmp"],
         )
 
-config.use_systemcass = Config(
-        base = config.default,
+config.systemcass = BuildEnv(
+        parent = config.default,
         repos = "repos/systemcass_objs",
-        systemc = config.systemc_cass
+        libraries = [config.libsystemccass],
         )
 }}}
@@ -42 +44 @@
 Now if we want to compile a platform with SystemCass, the only thing to is to tell it to `soclib-cc`:
 {{{
-$ soclib-cc -t use_systemcass
+$ soclib-cc -t systemcass
 }}}
 
 The argument after `-t` is the configuration name, attribute set to `config` in this line:
 {{{
-config.use_systemcass = Config( ....
-}}}
+config.systemcass = BuildEnv( ....
+}}}
+
+The only configuration names that can be passed to `-t` are the ones associated to `BuildEnv`s.
 
 = The long theory =
 
-== Default configuration ==
+== Configuration objects ==
 
 SoCLib's configuration file is using inherence in order to be able to share
 parameters among different similar instances.
 
-There are 3 base configurations to inherit from:
- * `config.toolchain` to define a compiler suite
- * `config.systemc` to define a SystemC implementation
- * `config.build_env` to define a build environment. This one must reference one instance of each of the above.
-
-There are 2 default configuration classes:
+There are 3 base configurations objects to define:
+ * `Toolchain` to define a compiler suite
+ * `Library` to define a library, like a SystemC implementation
+ * `BuildEnv` to define a build environment. This one must reference one instance of each of the above.
+
+You must define a set of these classes. There is
+a default configuration. It is composed of 3
+default configuration classes:
  * `config.systemc`.
-   * It inherits from `config.systemc`, you may inherit from either of them
+   * It is a `Library`.
    * It expects the environment variable `$SYSTEMC` to point to your actual SystemC installation directory
- * `config.default`.
-   * It inherits from `config.build_env`, you may inherit from either of them
-   * It uses the default compiler (`gcc` & `g++`) and `config.systemc`
+ * `config.toolchain`.
+   * It is a `Toolchain`.
+   * It uses the default compiler (`gcc` & `g++`)
+ * `config.build_env`.
+   * It is a `BuildEnv`.
+   * It uses the two previous ones.
 
 == Inheriting ==
 
-Inherence is written using `base =` as follows:
-{{{
-my_new_config = Config(
-    base = parent,
-    other_var = ....
+Inherence is written using `parent =` as follows:
+{{{
+config.my_new_toolchain = Toolchain(
+    parent = config.toolchain,
+    cflags = ....
     )
 }}}
 
 `config` is a global object defined by configuration system. It holds current configuration status.
+
+== Inherence and default fields values ==
+
+Using a `parent` is optional. If you use `parent =`, all the parent's fields are used
+as default values for the newly created configuration. Thus you only have to override
+custom fields.
+
+You can also use no `parent`, then all fields are needed, see below for the list.
 
 == Variables ==
@@ -90 +107 @@
 
 {{{
-
 # Defining a SystemC implementation inheriting everything
 # from default SystemC declaration
-config.systemc_22 = Config(
-        base = config.systemc,
+config.libsystemc_22 = Library(
+        parent = config.systemc,
         dir = "/home/me/tools/systemc/2.2"
         )
 
 # Then defining a new default configuration,
-# inheriting from previous default configuration
-config.default = Config(
-        base = config.default,
-        systemc = config.systemc_22,
-        )
+# inheriting from default build environment
+config.sc22 = BuildEnv(
+        parent = config.build_env,
+        libraries = [config.libsystemc_22],
+        )
+config.default = config.sc22
 
 # Now with SystemCASS
 
 # Declare a new SystemC implementation
-config.systemc_cass = Config(
-        base = config.systemc,
+config.libsystemccass = Library(
+        parent = config.systemc,
         dir = "/home/me/tools/systemc/cass",
         )
 
-config.use_systemcass = Config(
-        base = config.default,
+config.scass = BuildEnv(
+        parent = config.default,
 
         # This defines a new path to store compiled objects to
@@ -122 +139 @@
         # and here we tell this configuration use the SystemC implentation
         # declared above.
-        systemc = config.systemc_cass,
+        libraries = [config.libsystemcass],
         )
 }}}
@@ -131 +148 @@
 value of `name` attribute in the same class. See `systemc` definition below.
 
-== Build environment ==
-
-This is the one you may specify from command line with `-t`. By default, this is
-`default`. It inherits directly or indirectly from `config.build_env`.
-
- toolchain::
-  A class derived from `config.toolchain`
- systemc::
-  A class derived from `config.systemc`
- mode::
-  Default mode. default: "release"
- repos::
-  Path where object files are stored, it may be absolute or relative to current path (where soclib-cc is run)
-
-== SystemC ==
-
- `dir`::
-  The directory containing SystemC installation
- `os`::
-  The current os, for expansion in following variable
- `libdir`::
-  "%(dir)s/lib-%(os)s"
+cflags, <mode>_cflags, libs, <mode>_libs are all optional.
+
+== Library ==
+
+ `name`::
+  Name of the library (what it implements), "systemc" is currently the only specified value.
+ `vendor`::
+  Provider of the library, used for some quirks in soclib-cc. "modelsim" and "OSCI" are currently the only specified values.
  `libs`::
   Link flags. default: ['-L%(libdir)s', '-lsystemc']
  `cflags`::
   Cflags. default: [ '-I%(dir)s/include' ]
+ `release_cflags`::
+  cflags used for a "release" build, ie everyday build.
+ `release_libs`::
+  linking arguments for a "release" build.
+ `debug_cflags`::
+  cflags used for a "debug" build, ie when there is a bug to nail down.
+ `debug_libs`::
+  linking arguments for a "debug" build.
+ `prof_cflags`::
+  cflags used for a "profiling" build, ie performance test build.
+ `prof_libs`::
+  linking arguments for a "profiling" build.
+
+
+[source:trunk/soclib/utils/lib/python/soclib_cc/config/built-in.conf#L38 Default config.systemc] example:
+{{{
+config.systemc = Library(
+    name = 'systemc',
+    vendor = 'OSCI',
+    libs = ['-L%(libdir)s', '-lsystemc', '-lpthread'],
+    cflags = ['-I%(dir)s/include'],
+
+    # libs and cflags are implemented a generic way, now we
+    # have to provide "libdir" and "dir"
+
+    libdir = '%(dir)s/lib-%(os)s',
+    dir = "${SYSTEMC}",
+
+    # Again, libdir uses 'dir' and 'os', thus we have to define "os"
+    # here we use the value provided by a function.
+    os = _platform(),
+    )
+}}}
 
 == Toolchain ==
 
  `prefix`::
-  a string prepended to all tollchain tools. (eg: "i686-pc-linux-gnu-")
+  a string prepended to all toolchain tools.
  `cflags`::
-  global cflags. default: "-Wall"
+  global cflags.
  `libs`::
-  global linking arguments. default: "-lbfd"
+  global linking arguments.
  `release_cflags`::
-  cflags used for a "release" build, ie everyday build. default: "-O2"
+  cflags used for a "release" build, ie everyday build.
  `release_libs`::
-  linking arguments for a "release" build. default: none
+  linking arguments for a "release" build.
  `debug_cflags`::
-  cflags used for a "debug" build, ie when there is a bug to nail down. default: "-ggdb"
+  cflags used for a "debug" build, ie when there is a bug to nail down.
  `debug_libs`::
-  linking arguments for a "debug" build. default: none
+  linking arguments for a "debug" build.
  `prof_cflags`::
-  cflags used for a "profiling" build, ie performance test build. default: "-pg"
+  cflags used for a "profiling" build, ie performance test build.
  `prof_libs`::
-  linking arguments for a "profiling" build. default: "-pg"
+  linking arguments for a "profiling" build.
  `max_processes`::
   Maximum simultaneous compilation processes run (same as -j command-line flag)
+
+ * Cflags used for compilation will be `cflags` + ''mode''`_cflags`
+ * Libs used for compilation will be `libs` + ''mode''`_libs`
+ * ''mode'' is selected in current build environment, or on command line (flag `-m`)
+
+== Build environment ==
+
+This is the one you may specify from command line with `-t`. By default, this is
+the configuration set to `config.default` last. The following fields must be set.
+
+ `toolchain`::
+  A `Toolchain` to use for compilation
+ `libraries`::
+  A list (enclosed in []) of `Library` to be used for compilation and linkage of programs.
+ `repos`::
+  Path where object files are stored, it may be absolute or relative to current path (where soclib-cc is run)
  `max_name_length`::
   Maximum file name length for the file system `repos`
   is located in. If object file has a longer name,
-  it is hashed to get a shorter one, around 16 chars.
-
- * Cflags used for compilation will be `cflags` + ''mode''`_cflags`
- * Libs used for compilation will be `libs` + ''mode''`_libs`
- * ''mode'' is selected in current build environment, or on command line (flag `-m`)
+  it is hashed to get a shorter one, around 12 chars.
+ `repos`::
+  A directory to store temporary build files.
+ `cache_file`::
+  A path to a file where to store metadata file indexation cache. Default is
+  "%(repos)s/soclib_cc.cache", i.e. a path relative to `repos`.
 
 = Adding other component libraries to soclib-cc search path =
 
 Soclib-cc searches metadata files in soclib's module directories. This default behavior can 
-be tweaked to add other paths on search list. Simply call `addDescPath` in any of your configuration
-files:
+be tweaked to add other paths on search list. Simply call `addDescPath`:
 {{{
 config.addDescPath("/path/to/my/components")