Changes between Initial Version and Version 1 of Soclib Cc/Design Guide

Timestamp:

Mar 27, 2007, 6:07:37 PM (17 years ago)

Author:

Nicolas Pouillon

Comment:

--

Soclib Cc/Design Guide

@@ +1 @@
+
+= SoCLib's compilation helper =
+
+== Why ? ==
+
+=== We use a lot of tricky things things ===
+
+ * Different SystemC backends (SystemC-OSCI, SystemCASS, SoCView)
+   each of them is a different implementation of the same LRM, and
+   yields incompatible objects
+ * Templated classes, with separate implementation.
+   In order to reduce compilation time when a file changes, splitting
+   implementation from header is the right thing to do. Unfortunatelly
+   it involves manually instaciating source code for each used
+   template.
+ * Different build modes (debugging, profiling release, others ??)
+ * Compiled objects reuse: as we may build lots of SoCs with minor
+   modifications, reusing compiled objects from one build to the other
+   seems interesting (considering templated C++ build time)
+
+=== Reuse of current tools ?? ===
+
+This could be seen as reimplementing make, or even SCons, and this is
+not totally false. This is all about flexibility, and user-input
+readibility. 
+
+This very tool has been implemented as a `make` wrapper before,
+generated Makefiles were unreadable (all templates parameters in the
+middle, ...), and it did not work so well. It had been developped in a
+week, debugged in two weeks.
+
+Soclib-cc has been totally developped in 16 hours.
+
+= Configuration =
+
+In order to compile SoCLib objects, we need:
+ * a working SystemC installation
+ * a working GNU-Bfd installation (used for loading binaries into the platform)
+ * a working GNU-C++ compiler
+
+Soclib-cc processes three files in order:
+ 1. ''soclib-dir]''`/etc/soclib.conf`
+ 1. `~/.soclib/global.conf`
+ 1. `./soclib.conf`
+
+These files contain multiple concurrent configurations for building
+SoCLib. One of them will be chosen (explicitely) as the default
+one. Others may be used on demand (through command-line or local
+configuration file)
+ * File ![1] is installation-global. It should be modified by the
+   administrator for a network-wide configuration.
+ * File ![2] is useful for a developper's own configuration. This
+   allows to use a local development branch of a local SystemC, ...
+ * File ![3] is directory-local, this allows to choose different
+   flavours of previously declared configurations
+
+
+== Usage ==
+
+Soclib-cc may be used two ways:
+ * As a compiler wrapper. It will just be a CXX wrapper, handling
+   compilation or linkage on demand. This can be useful for external
+   Makefile integration.
+ * As a complete platform compiler. From an ad-hoc platform definition
+   (wrappers can be written to accept other formats), the complete
+   simulator will be compiled.
+
+Try running `soclib-cc -h`.
+
+=== As a compiler ===
+
+The usual way:
+
+{{{
+$ soclib-cc -c -o obj.o file.cc
+$ soclib-cc -o sim obj.o ...
+}}}
+
+=== As a platform compiler ===
+
+{{{
+$ soclib-cc -p platform_def
+}}}
+
+== Global flags ==
+
+ -v::
+  Print command lines
+ -q::
+  Dont say anything
+ -m MODE::
+  Change compilation mode (release, debug, prof)
+  This changes in an homogenous way the building
+
+
+== Object repository ==
+
+As objects can be reused between builds, or even between platforms, we
+may want to place objects in a global repository.
+
+Default repository is in current directory, in 'repos/'. If you want,
+you can specify an absolute path in configuration, enabling a global
+object repository (per user, per host, per network...).