documentation moved to wiki
authorTimo Savola <tsavola@movial.fi>
Fri, 25 Jul 2008 15:42:20 +0000 (18:42 +0300)
committerTimo Savola <tsavola@movial.fi>
Fri, 25 Jul 2008 15:42:46 +0000 (18:42 +0300)
http://sandbox.movial.com/wiki/index.php/Matrix

17 files changed:
doc/config.txt [deleted file]
doc/example/component-meta/plug [deleted file]
doc/example/component-meta/sample.package [deleted file]
doc/example/project-config/board-arm [deleted file]
doc/example/project-config/board-pc [deleted file]
doc/example/project-config/components [deleted file]
doc/example/project-config/main [deleted file]
doc/example/project-config/rootfs [deleted file]
doc/metadata.txt [deleted file]
doc/repositories.txt [deleted file]
example/component-meta/plug [new file with mode: 0644]
example/component-meta/sample.package [new file with mode: 0644]
example/project-config/board-arm [new file with mode: 0644]
example/project-config/board-pc [new file with mode: 0644]
example/project-config/components [new file with mode: 0644]
example/project-config/main [new file with mode: 0644]
example/project-config/rootfs [new file with mode: 0644]

diff --git a/doc/config.txt b/doc/config.txt
deleted file mode 100644 (file)
index 65ccb22..0000000
+++ /dev/null
@@ -1,119 +0,0 @@
-Project configuration
-=====================
-
-In Matrix, "config" refers to project configuration.  It's mostly about
-describing the project at a high level.  it shouldn't be confused with
-Makefiles.  Every Matrix invocation starts by parsing a config file called
-`main`.  Some configuration parameters can be overridden or extended via
-command-line parameters (which are documented on the matrix(1) man page).
-
-
-Finding files
--------------
-
-Config files are located by going through a list of directories and collecting
-all files which match the given name or glob pattern (see the glob(7) man
-page).  All of the collected files are parsed.  The list of config directories
-initially contains the current working directory: the `main` config file is
-(nearly) always read from the current working directory.  New config
-directories can be added in config files or on the command-line.
-
-
-File format
------------
-
-The config files are actually snippets of Python code.  The user can choose to
-do anything which is supported by the Python version being used, but most of
-the configuration tasks can be done using a few functions provided by Matrix;
-they can be considered the supported API.  Manipulating the internal
-configuration variables directly is also possible, but that might lead to
-incompatibilities during upgrades.  It's also probably a good idea to agree on
-a minimum Python version when writing advanced config files (Matrix itself is
-compatible with Python 2.3, which is a good suggestion).
-
-The local variables introduced by config files are local to the file.  The
-syntax is simply `'name' = 'value'`.  The names of local variables should begin
-with a lowercase letter (or underscore) to separate them from the Matrix API
-functions which start with an uppercase letter.  If values need to be passed to
-other scripts, it's possible via environment variables (by using Python's
-standard "os" module) or by adding variables to Matrix's configuration state
-(it's a good idea to use some project-specific prefix to avoid namespace
-pollution).
-
-Nearly all API function parameters are strings.  Strings are formed by quoting
-text with single (`'`) or double (`"`) quotes.  Strings can be concatenated
-with the `+` operator.
-
-Python function parameters can be specified positionally (`func(1, 2, 3)`)
-and/or by name (`func(a=1, b=2, c=3)`).  It's good practise to use the latter
-form in Matrix config files because some functions can be called in several
-ways.
-
-
-API functions
--------------
-
-ConfigDir(path) ::
-       Append a directory to the config file search list.
-
-ConfigDir(path, url, branch) ::
-       Append a directory to the config file search list.  If it doesn't
-       exist, try to clone `url` using Git and check out `branch` (defaults to
-       "master").  If `path` is omitted, it will be deducted from `url`.
-
-ConfigDir(path, url, branch, optional=True) ::
-       Same as above, but does nothing unless `path` is specified on the
-       command line.
-
-Parse(name) ::
-       Evaluate the matching config file(s) immediately.  (See the "Finding
-       files" section.)
-
-Parse(name, required=False) ::
-       Evaluate the matching config file(s) immediately.  Don't fail even if
-       no files are found.  (See the "Finding files" section.)
-
-Board(name, arch, gcc_march) ::
-       Declare a target machine type.  `name` is a symbolic name for referring
-       to the board declaration later on.  `arch` is the high-level CPU
-       architecture family name (in case source packages need that information
-       for something).  `gcc_march` will be passed verbatim to the compiler as
-       a parameter to the `-march=` option.  (There are a lot more optional
-       parameters - see the examples for details.)
-
-UseBoard(name) ::
-       Use the given target machine declaration when building packages.
-
-Root(url, branch) ::
-       Append a (remote) Git repository location ("root") to the component
-       search list.  The`url` shouldn't be a complete Git repository
-       location, but a prefix under which multiple repositories can be found
-       under "meta" and "source" subdirectories.  All components found under
-       the given location will use `branch` (which defaults to "master") by
-       default.
-
-Component(name) ::
-       Declare a source package ("component").
-
-Component(name, branch) ::
-       Declare a source package ("component").  Override the default branch
-       (which is defined along with the root location).
-
-ProvideComponent(name) ::
-       Declare a component as "environment-provided"; its sources are not
-       needed and other components' dependencies to it are automatically
-       satisfied.  It doesn't matter if the component was previously declared
-       using 'Component()'.
-
-SetFlag(name) ::
-       Set a flag which can be used to customize component build process.  A
-       flag can be set multiple times without a problem.  The flag is exported
-       in the build environment as a variable the value of which is "1".
-
-ClearFlag(name) ::
-       Unset a flag.  It won't be exported to the build environment at all.
-
-GetVariables() ::
-       Returns an object containing the internal configuration variables as
-       attributes.  New variables can be introduced by simply assigning to a
-       previously nonexistent attribute.
diff --git a/doc/example/component-meta/plug b/doc/example/component-meta/plug
deleted file mode 100644 (file)
index 8a1a550..0000000
+++ /dev/null
@@ -1,16 +0,0 @@
-# This is an example meta/plug file
-
-MATRIX_BUILD_STYLE = autotools
-MATRIX_FAKEROOT = install
-
-# this makes the build happen outside of the source tree
-MATRIX_OBJ_DIR = meta/obj
-
-# run autogen.sh with no parameters
-MATRIX_AUTOGEN_WITH = 
-
-ifdef custom_flag
-MATRIX_CONFIGURE_ENV = "CC=my-special-gcc"
-endif
-
-MATRIX_CONFIGURE_ARGS = "--prefix=/usr"
diff --git a/doc/example/component-meta/sample.package b/doc/example/component-meta/sample.package
deleted file mode 100644 (file)
index d6fe5d6..0000000
+++ /dev/null
@@ -1,5 +0,0 @@
-# This is an example meta/sample.package file
-
-depends = "some_package1 some_package2"
-conflicts = "some_package3 some_package1"
-architectures = ["arm"]
diff --git a/doc/example/project-config/board-arm b/doc/example/project-config/board-arm
deleted file mode 100644 (file)
index ddcfe3e..0000000
+++ /dev/null
@@ -1,11 +0,0 @@
-Board(
-       name            = "arm",
-       arch            = "arm",
-       gcc_march       = "armv5t",
-       gcc_options     = (
-               "-O2",
-               "-mfloat-abi=softfp",
-               "-Wno-poison-system-directories",
-       ),
-       gnu_host        = "arm-unknown-linux-gnueabi",
-)
diff --git a/doc/example/project-config/board-pc b/doc/example/project-config/board-pc
deleted file mode 100644 (file)
index df56235..0000000
+++ /dev/null
@@ -1,6 +0,0 @@
-Board(
-       name            = "pc",
-       arch            = "x86",
-       gcc_march       = "i686",
-       gnu_host        = "i686-pc-linux-gnu",
-)
diff --git a/doc/example/project-config/components b/doc/example/project-config/components
deleted file mode 100644 (file)
index a38fdb2..0000000
+++ /dev/null
@@ -1,2 +0,0 @@
-Component("busybox")
-Component("my-application")
diff --git a/doc/example/project-config/main b/doc/example/project-config/main
deleted file mode 100644 (file)
index ebdbcea..0000000
+++ /dev/null
@@ -1,11 +0,0 @@
-Parse("board-*")
-Parse("components")
-
-Root("git://example.com/matrix-components")
-
-UseBoard("arm")
-
-SetFlag("debug")
-SetFlag("no-docs")
-SetFlag("no-examples")
-SetFlag("no-tests")
diff --git a/doc/example/project-config/rootfs b/doc/example/project-config/rootfs
deleted file mode 100644 (file)
index 15875f8..0000000
+++ /dev/null
@@ -1,93 +0,0 @@
-# List of paths that will be copied (recursively)
-include_paths = [
-  "/bin",
-  "/sbin",
-  "/lib",
-  "/etc",
-  "/home",
-  "/usr/bin",
-  "/usr/sbin",
-  "/usr/lib",
-  "/usr/libexec",
-  "/usr/share/locale/en_GB",
-  "/usr/share/X11",
-  "/usr/share/fonts",
-  "/usr/share/hal",
-  "/usr/share/kilikali",
-  "/usr/share/themes",
-  "/usr/share/dbus-1",
-  "/usr/share/application-registry",
-  "/usr/share/applications",
-  "/usr/share/pixmaps",
-  "/usr/share/icons",
-  "/usr/share/scim/icons",
-  "/usr/share/matchbox",
-  "/usr/share/matchbox-keyboard",
-  "/usr/share/matchbox-panel/battery",
-  "/usr/share/gnome",
-  "/usr/share/gnome-volume-manager",
-  "/usr/share/mime-info",
-  "/usr/share/nm-applet",
-  "/usr/share/alsa"
-]
-
-# List of individual files that will be copied
-include_files = [
-  "/usr/share/usb.ids",
-  "/usr/share/terminfo/x/xterm"
-]      
-
-# List of paths that will be filtered out from the copied dirs
-exclude_paths = [
-  "/usr/lib/pkgconfig",
-# The gconv dir in gconv dir is a bug. This is fixed in new SB toolchains.
-  "/usr/lib/gconv/gconv",
-  "/var/run/NetworkManager",
-  "/usr/lib/xulrunner-devel-1.9a9pre"
-]
-
-# List of individual files that will be filtered out from the copy
-exclude_files = [
-       "/usr/share/hal/fdi/preprobe/20thirdparty/10-nfsroot.fdi"
-]
-
-# List of regular expressions that will cause the matched files to be filtered out
-exclude_expressions = [
-  ".*\.l?a$"
-]
-
-# List of paths that will be created as empty directories (with parents if needed)
-created_paths = [
-  "/boot",
-  "/dev/pts",
-  "/lib",
-  "/media",
-  "/mnt",
-  "/proc",
-  "/root",
-  "/sbin",
-  "/home",
-  "/sys",
-  "/tmp",
-  "/var/empty",
-  "/var/run/sshd",
-  "/var/run/NetworkManager",
-  "/var/state/dhcp"
-]
-
-# List of directories to be chowned to (user,group).
-change_owner = {
-  "/home/aeki": ("10042", "10042")
-}
-
-# List of device nodes to be created
-devices = {
-  "console" : ("c", 5, 1),
-  "null"    : ("c", 1, 3),
-  "random"  : ("c", 1, 8),
-  "urandom" : ("c", 1, 9),
-  "tty0"    : ("c", 4, 0),
-  "tty1"    : ("c", 4, 1),
-  "tty2"    : ("c", 4, 2),
-  "tty3"    : ("c", 4, 3)
-}
diff --git a/doc/metadata.txt b/doc/metadata.txt
deleted file mode 100644 (file)
index 5b4d11f..0000000
+++ /dev/null
@@ -1,65 +0,0 @@
-Component meta data
-===================
-
-Matrix components (source packages) consist of two parts: source code and
-meta data used to describe the component.  Each component's metadata is stored
-in a dedicated Git repository and checked out under the "`meta`" directory at
-the root of the source code hierarchy.
-
-
-Package files
--------------
-
-A component can provide one or more binary packages.  If the build results are
-not packaged into separate binary archives (as opposed to a filesystem image),
-the package files are essentially only used for determining the correct build
-order.  The package files are named as "`'name'.package`".
-
-The package files are evaluated using Python and can define the following
-variables:
-
-depends::
-       Whitespace-separated list of dependencies (by package name, not
-       component name).
-
-conflicts::
-       Whitespace-separated list of conflicting packages.
-
-architectures::
-       List of architectures to support.  (See the 'Board()' config API
-       function in the "Project configuration" document.)
-
-
-The plug
---------
-
-The "`plug`" file is a GNU Makefile which is used for plugging the component
-into the Matrix build process.  It should set the `MATRIX_BUILD_STYLE` variable
-to one of the following values:
-
-autotools::
-       The component can be built using the `./configure && make && make
-       install` incantation and supports standard configuration parameters
-       (such as `--prefix`).  If found, the `autogen.sh` script is
-       automatically run before configure.
-       The following flags (see the 'SetFlag()' config API function in the
-       "Project configuration" document) are automatically converted to common
-       configure options: `no-docs`, `no-examples`, `no-tests`, `debug` and
-       `quiet`.
-
-make::
-       The component can be built using the `make && make install` incantation
-       and may support the `PREFIX` or `prefix` variables.
-
-custom::
-       The plug file declares custom `configure`, `build` and `install`
-       targets for manually invoking the component's build system.
-
-Optional variables:
-
-MATRIX_FAKEROOT::
-       Enables fakeroot for some of the build stages.  The value is a list
-       of the keywords `autogen`, `configure`, `build`, `install` and `all`.
-       It makes most sense to use fakeroot the `install` mode which causes any
-       file mode and ownership changes to be saved for use later when
-       packaging.
diff --git a/doc/repositories.txt b/doc/repositories.txt
deleted file mode 100644 (file)
index 526d553..0000000
+++ /dev/null
@@ -1,31 +0,0 @@
-Component repository layout
-===========================
-
-Remote repositories
--------------------
-
-The project contents (source code packages and build metadata) are stored in
-Git repositories, typically on one or more remote servers.  A "component"
-consists of two repositories: one for the source code and one for the meta
-data.  They are searched from the remote locations ("roots" - see the 'Root()'
-config API function in the "Project configuration" document) by forming the
-following URLs:
-
-  - `'root'/source/'component'.git`
-  - `'root'/meta/'component'.git`
-
-The two repositories can be located under different roots - and actually under
-multiple roots.  The roots are ordered from "generic" to "specific": a latter
-(more specific) root may override a component repository in a former (more
-generic) root.
-
-
-Working directories
--------------------
-
-Matrix clones and checks out the source code repository in the
-`src/'component'` directory and the meta data repository in the
-`src/'component'/meta` directory.  The check-outs can be directly used for
-developing the code in addition to automated building using Matrix.  Changes
-can be pushed to the remote repositories if the root was configured with an
-`ssh` or `rsync` URL.
diff --git a/example/component-meta/plug b/example/component-meta/plug
new file mode 100644 (file)
index 0000000..8a1a550
--- /dev/null
@@ -0,0 +1,16 @@
+# This is an example meta/plug file
+
+MATRIX_BUILD_STYLE = autotools
+MATRIX_FAKEROOT = install
+
+# this makes the build happen outside of the source tree
+MATRIX_OBJ_DIR = meta/obj
+
+# run autogen.sh with no parameters
+MATRIX_AUTOGEN_WITH = 
+
+ifdef custom_flag
+MATRIX_CONFIGURE_ENV = "CC=my-special-gcc"
+endif
+
+MATRIX_CONFIGURE_ARGS = "--prefix=/usr"
diff --git a/example/component-meta/sample.package b/example/component-meta/sample.package
new file mode 100644 (file)
index 0000000..d6fe5d6
--- /dev/null
@@ -0,0 +1,5 @@
+# This is an example meta/sample.package file
+
+depends = "some_package1 some_package2"
+conflicts = "some_package3 some_package1"
+architectures = ["arm"]
diff --git a/example/project-config/board-arm b/example/project-config/board-arm
new file mode 100644 (file)
index 0000000..ddcfe3e
--- /dev/null
@@ -0,0 +1,11 @@
+Board(
+       name            = "arm",
+       arch            = "arm",
+       gcc_march       = "armv5t",
+       gcc_options     = (
+               "-O2",
+               "-mfloat-abi=softfp",
+               "-Wno-poison-system-directories",
+       ),
+       gnu_host        = "arm-unknown-linux-gnueabi",
+)
diff --git a/example/project-config/board-pc b/example/project-config/board-pc
new file mode 100644 (file)
index 0000000..df56235
--- /dev/null
@@ -0,0 +1,6 @@
+Board(
+       name            = "pc",
+       arch            = "x86",
+       gcc_march       = "i686",
+       gnu_host        = "i686-pc-linux-gnu",
+)
diff --git a/example/project-config/components b/example/project-config/components
new file mode 100644 (file)
index 0000000..a38fdb2
--- /dev/null
@@ -0,0 +1,2 @@
+Component("busybox")
+Component("my-application")
diff --git a/example/project-config/main b/example/project-config/main
new file mode 100644 (file)
index 0000000..ebdbcea
--- /dev/null
@@ -0,0 +1,11 @@
+Parse("board-*")
+Parse("components")
+
+Root("git://example.com/matrix-components")
+
+UseBoard("arm")
+
+SetFlag("debug")
+SetFlag("no-docs")
+SetFlag("no-examples")
+SetFlag("no-tests")
diff --git a/example/project-config/rootfs b/example/project-config/rootfs
new file mode 100644 (file)
index 0000000..15875f8
--- /dev/null
@@ -0,0 +1,93 @@
+# List of paths that will be copied (recursively)
+include_paths = [
+  "/bin",
+  "/sbin",
+  "/lib",
+  "/etc",
+  "/home",
+  "/usr/bin",
+  "/usr/sbin",
+  "/usr/lib",
+  "/usr/libexec",
+  "/usr/share/locale/en_GB",
+  "/usr/share/X11",
+  "/usr/share/fonts",
+  "/usr/share/hal",
+  "/usr/share/kilikali",
+  "/usr/share/themes",
+  "/usr/share/dbus-1",
+  "/usr/share/application-registry",
+  "/usr/share/applications",
+  "/usr/share/pixmaps",
+  "/usr/share/icons",
+  "/usr/share/scim/icons",
+  "/usr/share/matchbox",
+  "/usr/share/matchbox-keyboard",
+  "/usr/share/matchbox-panel/battery",
+  "/usr/share/gnome",
+  "/usr/share/gnome-volume-manager",
+  "/usr/share/mime-info",
+  "/usr/share/nm-applet",
+  "/usr/share/alsa"
+]
+
+# List of individual files that will be copied
+include_files = [
+  "/usr/share/usb.ids",
+  "/usr/share/terminfo/x/xterm"
+]      
+
+# List of paths that will be filtered out from the copied dirs
+exclude_paths = [
+  "/usr/lib/pkgconfig",
+# The gconv dir in gconv dir is a bug. This is fixed in new SB toolchains.
+  "/usr/lib/gconv/gconv",
+  "/var/run/NetworkManager",
+  "/usr/lib/xulrunner-devel-1.9a9pre"
+]
+
+# List of individual files that will be filtered out from the copy
+exclude_files = [
+       "/usr/share/hal/fdi/preprobe/20thirdparty/10-nfsroot.fdi"
+]
+
+# List of regular expressions that will cause the matched files to be filtered out
+exclude_expressions = [
+  ".*\.l?a$"
+]
+
+# List of paths that will be created as empty directories (with parents if needed)
+created_paths = [
+  "/boot",
+  "/dev/pts",
+  "/lib",
+  "/media",
+  "/mnt",
+  "/proc",
+  "/root",
+  "/sbin",
+  "/home",
+  "/sys",
+  "/tmp",
+  "/var/empty",
+  "/var/run/sshd",
+  "/var/run/NetworkManager",
+  "/var/state/dhcp"
+]
+
+# List of directories to be chowned to (user,group).
+change_owner = {
+  "/home/aeki": ("10042", "10042")
+}
+
+# List of device nodes to be created
+devices = {
+  "console" : ("c", 5, 1),
+  "null"    : ("c", 1, 3),
+  "random"  : ("c", 1, 8),
+  "urandom" : ("c", 1, 9),
+  "tty0"    : ("c", 4, 0),
+  "tty1"    : ("c", 4, 1),
+  "tty2"    : ("c", 4, 2),
+  "tty3"    : ("c", 4, 3)
+}