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

[From: subversion at stage.maemo.org]

Author: marivoll
Date: 2008-11-14 01:59:05 +0200 (Fri, 14 Nov 2008)
New Revision: 16674

Modified:
   projects/haf/doc/mvo/system-model-2.txt
Log:
Configurations, meta packages.


Modified: projects/haf/doc/mvo/system-model-2.txt
===================================================================
--- projects/haf/doc/mvo/system-model-2.txt	2008-11-13 19:19:44 UTC (rev 16673)
+++ projects/haf/doc/mvo/system-model-2.txt	2008-11-13 23:59:05 UTC (rev 16674)
@@ -1,9 +1,7 @@
 TODO:
 
- - "Maemo" -> "Maemo system".
- - "Releasing" -> "Releasing and Updating"
- - Documentation in the archive
- - Extended archive: extra categories
+ - Extended archive: extra categories, generalizing the "pending"
+   stuff.
  - Building binaries for the archive from secret sources
 
 
@@ -42,6 +40,13 @@
     Maemo OS and the add-ons: build tools, documentation tools,
     packaging tools, image creation tools, etc.
 
+  - Maemo contains its documentation: reference documentation that is
+    generated from source code, introductions and other navigational
+    aids to find the reference documentation, example programs, free
+    standing texts such as tutorials, internal design documents, etc.
+    These documents are automatically extracted from the archive and
+    published on maemo.org.
+
   - Maemo is developed by multiple 'non-consenting' parties.
     Different parties work on different parts but they all work on the
     single Maemo project.  Nokia is one party, the rest forms the
@@ -402,36 +407,6 @@
 
 [...]
 
-* Installation
-
-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 (and
-nothing else).
-
-Typically, packages are 'installed' into an image by letting the
-package management tools create a root filesystem in the normal way.
-Such a root filesystem can then be maintained at run-time with the
-package management tools as well.  Some packages might be used to
-create specialized images, like the kernel image that is flashed into
-its own partition without a filesystem.  Some packages might be used
-to pre-load files into the prepared root filesystem, or into other
-filesystems.  These files are then not subject to package management
-at run-time, which might be appropriate for things like pre-loaded
-images and videos.
-
-The Maemo SDK runs in Scratchbox targets.  It is installed by
-extracting a 'rootstrap' tarball into the target.  This rootstrap
-tarball is also prepared from packages in the Maemo archive (and
-nothing else).
-
-The tools for creating the installation images and rootstrap tarballs
-are contained in the Maemo archive and are maintained like any other
-component.
-
-Both the Maemo OS in a device and the Maemo SDK in a Scratchbox target
-are maintained by installing packages from the Maemo archive and
-removing already installed packages with the package management tools.
-
 * Releasing
 
 Packages are released by copying them in groups from harmattan-testing
@@ -493,3 +468,142 @@
 influences which version of a package is the installation candidate;
 packages whose Maemo-Upgrade-Only-From field is not satisfied are
 ignored by the package management tools.
+
+* 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
+packages needs to be specified, such as when releasing or updating
+harmattan-stable, and when preparing installers.
+
+A simple way to specify a configuration is to list its packages
+explicitly.  Another way might be to specify it relative to one or
+more existing configurations, ony listing the packages that should be
+added and removed from the 'parent' configurations.  Another useful
+thing is to transform the names of packages, by substituting "rx44"
+for "@VARIANT@", say.
+
+More complicated ways to specify configurations should be allowed for.
+In general, it should be possible to specify a configuration
+programmatically, with access to at least all the information in the
+Maemo archive.
+
+The packages computed in of these ways are said to be "listed" by the
+configuration.
+
+A configuration also specifies a set of "base" configurations.
+
+The set of packages that are "contained" in a configuration is defined
+to be the set of packages that the package management system would
+install into a empty root filesystem when asked to install the listed
+packages together with the listed packages of the base configurations,
+minus the packages that are contained in the base configurations.
+
+[ The reason why the listed packages of the base configurations are
+  installed as well is to allow those configurations to resolve
+  ambiguities.  A package might depend on "liba | libb", and the base
+  configuration might resolve this by including liba.  Similar for
+  virtual packages.
+
+  It should be possible to compute the base configurations for a
+  configuration from the dependency graph: if a listed package of
+  configuration B is reachable from a listed package of configuration
+  A, then B is a base for A.  This will usually find too many bases
+  that might conflict with each other and prevent "apt-get install"
+  from doing its job.
+]
+
+Thus, the set of listed packages in a configuration does not need to
+be complete: only those packages that are not installed anyway to
+satisfy a dependency need to be included.  In fact, as few packages as
+possible should be listed so that the normal package dependencies can
+take care of assembling a working set in a flexible way.
+
+Depending on its intended use, configurations can have more attributes
+than just a name and a list of packages.
+
+* 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
+(and nothing else).
+
+Often, packages are 'installed' into a image by letting the package
+management tools create a root filesystem in the normal way.  Such a
+root filesystem can then be maintained at run-time with the package
+management tools as well.  Packages might also be used to create more
+specialized images, like the kernel image that is flashed into its own
+partition without a filesystem.  Some packages might be used to
+pre-load files into the prepared root filesystem, or into other
+filesystems.  These files are then not subject to package management
+at run-time, which might be appropriate for things like pre-loaded
+images and videos.
+
+The Maemo SDK runs in Scratchbox targets.  It is installed by
+extracting a 'rootstrap' tarball into the target.  This rootstrap is
+also filesystem image that is prepared from packages in the Maemo
+archive (and nothing else).
+
+The tools for creating these images are contained in the Maemo archive
+and are maintained like any other component.  They are controlled by
+the attributes of a configuration.
+
+* Meta packages
+
+The package management tools in an installation are not directly aware
+of configurations; they only work with packages and their
+dependencies.
+
+However, users should be able to perform package management operations
+based on configurations.  For example, updates to the OS should not be
+presented package by package.  The user should not be expected to
+recognize those packages.  Rather, the OS update should be presented
+as a single item to the user.
+
+Currently, the package management UI can only handle packages.  Thus,
+configurations need to represented in terms of packages.
+
+Some configurations list only a single package.  For example, an
+application might consist of tens of packages, but there is likely one
+"main" package that causes the application to appear in the menu of
+the Desktop.  Thus, the main package of the application can be made
+visible in the Application Manager.
+
+Other configurations need to list more than one package.  The typical
+example is the OS itself: there is no natural main package that can
+represent it.  These configurations can be represented by an
+artificial "meta package".
+
+The packages of the configuration are used to determine the
+dependencies of the meta package.  Other attributes of the meta
+package, such as its name and its description, are also controlled by
+the configuration.
+
+A typical meta package will have dependencies to all packages that are
+contained in its configuration.  They will typically have the form "P
+(= V)" or "P (>= V)" where V is the most recent version of P in the
+distribution that the meta package is uploaded to.
+
+The "P (>= V)" form of a dependency is preferred so that
+configurations can overlap without fighting each other.  It also
+allows partial updates in a development environment such as
+harmattan-testing.  Thus, if a meta package uses the strict "P (= V)"
+form, a variant of the meta package should also be provided with the
+"P (>= V)" form.
+
+Even if there is a natural main package for a configuration, it might
+be advantagous to use a meta package anyway since they offer more
+control.  Returning to the previous example, the only thing that can
+be represented in the UI of the package management tools is an update
+to the main package.  Updates to dependency packages are not visible
+(and would likely be confusing if they were).  The application package
+would need to be updated artificially to pull in the updated
+dependency package.  It is cleaner to do use a meta package instead.
+
+Meta packages enter the archive like other packages.  They are
+normally uplaoded to harmattan-testing, except for urgent updates,
+when they go to harmattan-proposed-updates.
+
+Other configuration can include these meta packages in their set of
+listed packages.  For example, a configuration that is used to control
+the content of a filesystem image will refer to the