[maemo-commits] [maemo-commits] r16886 - projects/haf/doc/mvo

[From: subversion at stage.maemo.org]

Author: marivoll
Date: 2008-12-05 17:30:14 +0200 (Fri, 05 Dec 2008)
New Revision: 16886

Modified:
   projects/haf/doc/mvo/system-model-2.txt
Log:
Updated.


Modified: projects/haf/doc/mvo/system-model-2.txt
===================================================================
--- projects/haf/doc/mvo/system-model-2.txt	2008-12-05 14:45:32 UTC (rev 16885)
+++ projects/haf/doc/mvo/system-model-2.txt	2008-12-05 15:30:14 UTC (rev 16886)
@@ -1,11 +1,40 @@
-TODO:
 
- - Building binaries for the archive from secret sources
-
-
 			  MAEMO SYSTEM MODEL
 			  ------------------
 
+Table of Contents
+
+. Introduction
+
+. Packages
+
+. System architecture
+.. Components
+.. Subsystems
+.. Interfaces
+... Top-level interfaces
+.. Layers
+... Base
+... Middleware
+... Applications
+.. Domains
+
+. Archive
+.. Categories
+.. Distributions
+... Compatibility
+... Integration snapshots
+... Urgent updates
+... Continuity
+.. Repositories
+.. Expiration
+
+. Releasing
+.. Upgrade chaining
+.. Configurations
+.. Images
+.. Meta packages
+
 * Introduction
 
 The "Maemo system" (or just "Maemo") is the software that powers
@@ -35,28 +64,29 @@
 ones software into Maemo (and by that effectively joining the Maemo
 community) is outweighted by the benefits.
 
-Maemo combines free and non-free software, but it is a public
-endeavor: software that is not yet published (in source or binary-only
-form) can not be a part of the Maemo system, because a system is only
-a system when its parts are aware of each other and accomodate each
-other.
+Maemo is public.  Maemo combines free and non-free software, but it is
+a public endeavor: software that is not yet published (in source or
+binary-only form) can not be a part of the Maemo system, because a
+system is only a system when its parts are aware of each other and
+accomodate each other.
 
 Maemo is the son of Debian (and Ubuntu is its brother).  Maemo
 inherits many of its basic features from Debian and stays in close
 contact with it by letting code flow between the two easily.
 
 The following sections describe the Maemo system in more detail, but
-still from a safe distance.  There are two important aspects of the
-Maemo system: the structure of its components and the support for
-developing it.
+still from a safe distance.
 
+There are two important aspects of the Maemo system: the structure of
+its components and the support for developing it.
+
 These two aspects are called the "System Architecture" (the animal)
 and the "Archive" (its habitat).  The Maemo animal could be cared for
 inside the existing and well maintained Debian habitat, but Maemo's
 lifecycle is probably too different from Debian's for this.  Thus we
 have a dedicated Maemo archive.
 
-Architecture and archive are connected by the concept of "Packages".
+Architecture and archive are connected by "Packages".
 
 * Packages
 
@@ -65,13 +95,10 @@
 management tools of Maemo install them into various places, such as a
 device or a SDK target environment.
 
-Software is usually developed without the help of packages, and
-packaging it for inclusion in the Maemo archive is often a distinct
-separate step.
-
 Packages come in two basic kinds: source packages and binary packages.
 Source packages are released by their maintainers and compiled into
-binary packages.  Binary packages are installed into devices etc.
+binary packages.  Binary packages are installed into installation
+targets.
 
 A source package is a file tree that follows the Debian policy for
 source packages.  (I.e., it has a "debian/" directory in it.) The
@@ -88,14 +115,10 @@
 separate ".deb" files, but this text still treats them as a single
 binary package.
 
-In other words, successfully building a package means compiling its
-sources for each machine architecture successfully.  Different machine
-architectures are not allowed to drift apart.
-
 In the following, "package" refers to binary packages.
 
 A package has a name and a version, both strings.  The name and
-version uniquely identifies a package.  If a package with a given name
+version uniquely identify a package.  If a package with a given name
 and version already exists in the Maemo archive, no other package with
 the same name and version can be uploaded to it.
 
@@ -131,20 +154,21 @@
 Subsystems have unique names and are tracked in the architecture
 documentation.
 
-Every source package must belong to exactly one subsystem, and a
-source package formally declares its subsystem.  Thus, the source
-packages of a subsystem do not need to be listed manually in the
-subsystem documentation; rather, that list is extracted from the
-packages.
+A source package belongs to at most one subsystem, which it declares
+in its meta data.  Thus, the source packages of a subsystem do not
+need to be listed manually in the subsystem documentation; rather,
+that list is extracted from the packages.
 
 ** Interfaces
 
 [ Need some input from the services discussion here. ]
 
 Interfaces are contracts between components.  However, interfaces are
-only tracked on a subsystem level.
+only tracked on a subsystem level.  Interfaces that are internal to a
+subsystem are managed in whatever way the subsystem maintainers agree
+on.
 
-Interfaces have a name, and optionally a version.
+Interfaces have a formal name, and optionally a version.
 
 Two things about interfaces are of interest: finding clients of
 interfaces so that changes to interfaces can be managed, and finding
@@ -152,20 +176,23 @@
 assembled from the available components.
 
 In general, a subsystem should list all interfaces that it provides,
-with pointers to their documentation.  That list might be made by
-automatically finding all interfaces provided by the packages of the
-subsystem and filtering out the intra-subsystem interfaces by hand.
-The interfaces used by a subsystem should be found automatically, as
-far as possible, and the generated list should be included in the
-documentation automatically.
+with pointers to their documentation.  That list will likely need to
+be maintained by hand, maybe by automatically finding all interfaces
+provided by the packages of the subsystem and filtering out the
+intra-subsystem interfaces by hand.  The interfaces used by a
+subsystem should be found automatically, as far as possible, and the
+generated list should be included in the documentation automatically.
 
-Packages that use the interfaces provided by this subsystem should be
+Packages that use the interfaces provided by a subsystem should be
 found automatically and listed as well.
 
+Thus, interfaces formally tracked in the Maemo archive and available
+to tools.
+
 There are different kinds of interfaces, which are explained in more
 detail below: package interfaces, virtual package interfaces, D-Bus
 interfaces, file-based configuration modification interfaces, and
-unclassified interfaces.
+miscellaneous interfaces.
 
 A package interface is a interface that is made available by
 installing a specific package.  Examples are shared libraries, header
@@ -221,13 +248,10 @@
 
 *** Base
 
-Bottom layer, basic OS services such as hardware adaptation, network,
-mass storage, text console, X11, package management, compiler,
-build tools in general, etc.
+The bottom layer that contains basic OS services such as hardware
+adaptation, network, mass storage, text console, X11, package
+management, compiler, build tools in general, etc.
 
-The base layer is represented as one or more configurations, one for
-each supported installation target.
-
 *** Middleware
 
 Everything that is not in the Base or Applications layer.  Packages in
@@ -237,11 +261,13 @@
 
 *** Applications
 
-Subsystems in the application layer are independent from each other.
+Subsystems in the application layer must not have dependencies on each
+other.
 
 ** Domains
 
-Collection of subsystems, map to teams.
+A domain is a collection of subsystems.  It is mostly a organizational
+tool.
 
 * Archive
 
@@ -256,10 +282,10 @@
   package starts to erode within Debian itself, and might be replaced
   with pointers into a VCS instead.  The concept of a source package
   then only refers to a tree with a debian/ directory.  Maybe such a
-  thing should be called "debianized source" and not source package.
-  The Maemo archive could be extended to include a VCS component, and
-  when building new packages from their source, the source is pushed
-  into that VCS.
+  thing should be called "debianized source tree" and not source
+  package.  The Maemo archive could be extended to include a VCS
+  component, and when building new packages from their source, the
+  source is pushed into that VCS.
 ]
 
 The package management tools on devices and other installation targets
@@ -579,7 +605,7 @@
 packages whose Maemo-Upgrade-Only-From field is not satisfied are
 ignored by the package management tools.
 
-* Configurations
+** Configurations
 
 A configuration is a named set of packages that is specified in one
 way or another.  They are used in a number of places where a set of
@@ -632,7 +658,7 @@
 Depending on its intended use, a configuration can have more
 attributes than just a name and a list of packages.
 
-* Images
+** Images
 
 The Maemo OS runs on a number of devices.  It is installed via one or
 more "images" that are prepared from packages in the Maemo archive.
@@ -657,7 +683,7 @@
 and are maintained like any other component.  They are controlled by
 the attributes of a configuration.
 
-* Meta packages
+** Meta packages
 
 The package management tools in an installation are not directly aware
 of configurations; they only work with packages and their