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

Thu Dec 4 03:01:59 EET 2008

Author: marivoll
Date: 2008-12-04 03:01:58 +0200 (Thu, 04 Dec 2008)
New Revision: 16849

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


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

--- projects/haf/doc/mvo/system-model-2.txt	2008-12-03 14:02:39 UTC (rev 16848)
+++ projects/haf/doc/mvo/system-model-2.txt	2008-12-04 01:01:58 UTC (rev 16849)
@@ -1,114 +1,180 @@
 TODO:
 
- - Documentation in the archive
- - Extended archive: extra categories
  - Building binaries for the archive from secret sources
 
 
 			  MAEMO SYSTEM MODEL
 			  ------------------
 
-			       Part II
+* Introduction
 
-			       Binaries
+The "Maemo system" (or just "Maemo") is the software that powers
+Nokia's Internet Tablets.
 
+Maemo contains an operating system (the "Maemo OS") that runs in a
+variety of configurations on a variety of devices.  The OS includes
+the usual software components like programs, libraries, kernels,
+firmware, etc.
 
-[ Part I of the Maemo System Model describes source code: how it is
-  stored, compiled, maintained, and released; how bugs are tracked;
-  how it is structured into domains, sub-systems, layers, and
-  components; how the Maemo system is bootstrapped from source; how we
-  import upstream sources; how we handle NMUs; etc.
+Maemo contains the "Maemo SDK", the tools needed to develop the Maemo
+OS and the add-ons: build tools, documentation tools, packaging tools,
+image creation tools, etc.
 
-  This text has been written before Part I, so I had to make a few
-  assumptions about Part I that might turn out to be wrong.  The
-  assumptions are:
+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.
 
-  - We are talking about the "Maemo" system, from its Harmattan
-    version onwards.
+Maemo contains applications, plugins, theme graphics and other
+optional add-ons that run on the Maemo OS or enhance it.  Add-ons like
+these that are not part of Maemo are generally ignored.
 
-  - Maemo contains an operating system (the "Maemo OS") that runs in a
-    variety of configurations on a variety of devices.  The OS
-    includes programs, libraries, kernels, firmware, etc.
+Maemo is open to anyone.  Different parties work on different parts
+but they all work on the single Maemo system.  Nokia is one party, and
+all parties together form the Maemo community.  The cost of including
+ones software into Maemo (and by that effectively joining the Maemo
+community) is outweighted by the benefits.
 
-  - Maemo contains applications, plugins, theme graphics and other
-    optional add-on "modules" that run on the Maemo OS or enhance it.
-    The current "Extras" repository is part of Maemo, for example, and
-    applications like the Browser or Email are not necessarily part of
-    the OS module.
+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 contains the "Maemo SDK": the tools needed to develop the
-    Maemo OS and the add-ons: build tools, documentation tools,
-    packaging tools, image creation tools, etc.
+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.
 
-  - 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.
+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.
 
-  - 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
-    Maemo community.  Nokia gets some special treatment as the 'owner'
-    of the Maemo project and the maintainer of large and important
-    parts of it, but not much.
+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.
 
-  - Ultimately, all our packages are published, with or without
-    source, with or without explicit license agreements.  Things that
-    are never to be published are not part of the Maemo system.
+Architecture and archive are connected by the concept of "Packages".
 
-  - Sources are stored and worked on in many different ways, but they
-    all come together in the form of Debian source packages that are
-    stored in the Maemo archive.  These source packages are compiled
-    by one or more buildbots in a controlled environment into Debian
-    binary packages.  That's the interface between Part I and Part II
-    of the Maemo system model.  I assume that Debian binary packages
-    have already been introduced as part of the compilation process.
+* Packages
 
-  Most of this is modeled after Debian, of course.  The significant
-  differences are:
+Maemo uses the Debian package format for representing and formally
+naming its pieces.  The archive stores these packages and the package
+management tools of Maemo install them into various places, such as a
+device or a SDK target environment.
 
-  - There is no "unstable".
+Software is usually developed without the help of packages, and
+packaging it for inclusion in the Maemo archive is often a distinct
+separate step.
 
-  - We release "modules", not a whole distribution.  Modules are
-    prepared in "testing" until they are ready to be copied into
-    "stable".
+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.
 
-  - Upload and download rights are more complicated since
-    unfortunately not everyone is equal in the land of Maemo.
+In the following, "package" refers to a binary package.  Source
+packages are mostly ignored and treated as an implementation detail.
 
-  There are differences to our current way of working as well, of
-  course:
+Maemo supports multiple machine architectures.  If a package is
+machine architecture dependent, its sources are compiled once for each
+architecture.  These separate compilation results are stored in
+separate files, but this text still treats them as a single package.
 
-  - Everything is public by default.  There is support for keeping
-    things secret, but this should always be regarded as an exception
-    rather than the rule.
+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.
 
-  - The "extras" repositories are an inherent part of the plan.
+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
+and version already exists in the Maemo archive, no other package with
+the same name and version can be uploaded to it.
 
-  - Everything is compiled in "testing" and released to "stable" from
-    there.  That includes 3rd party application developers.  "Testing"
-    must be good enough as an SDK for "stable".
+* System architecture
 
-  - Upgrade chaining is not implemented by the archive.  We need to
-    come up with another way of doing it.
+Maemo is purposeful and flexible.
 
-]
+** Components
 
-* The Maemo archive
+Components are in packages.
 
-Maemo is maintained and distributed as a collection of packages.  All
-packages, both source packages and the binary packages that have been
-compiled from them, are contained in the "Maemo archive".
+** Interfaces
 
-The package management tools on the device are normally configured to
-access the Maemo archive only.  It is possible to extend this
-configuration so that a device has access to more packages than just
-the ones in the Maemo archive.  These packages are not considered to
-be part of Maemo, and whoever provides them is responsible to adapt
-them to changes in the Maemo archive.
+Interfaces have names.  Packages provide interfaces.  Usually, the
+package name is the name of the single interface it provides.
 
+Interfaces might have versions.  If the name of the interface is the
+name of a package, the version of the package is the version of the
+interface.  Otherwise, ...
+
+Packages depend on interfaces, which they formally declare, or just
+use interfaces if they happen to be available.  Whether or not a
+interface is available needs to be determined in a way specific to the
+interface.  The package management system does not help.
+
+** Subsystems
+
+Collections of functionally related packages.  Packages declare their
+subsystem.
+
+*** Top-level interfaces
+
+** Layers
+
+Subsystem completely in one layer.  No dependencies from (a package in
+a subsystem in a) lower layer to an upper layer.
+
+*** 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 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
+the middleware layer are pulled in by dependencies from the
+Applications layer.  Dense dependencies between subsystems in the
+middleware layer are expected and accepted.
+
+*** Applications
+
+Subsystems in the application layer are mostly independent from each
+other.
+
+** Domains
+
+Collection of subsystems, maps to teams.
+
+* Archive
+
+The Maemo system is maintained and distributed as a collection of
+packages.  All packages are contained in the "Maemo archive", and the
+archive also contains enough information to find the exact source code
+that was used to build the packages (if the source is publically
+available).
+
+[ Thus, the archive will typically store the source packages as well
+  and deliver them with apt-get source, but the concept of a source
+  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.
+]
+
+The package management tools on devices and other installation targets
+are normally configured to access the Maemo archive only.  It is
+possible to extend this configuration so that a device has access to
+more packages than just the ones in the Maemo archive.  These packages
+are not considered to be part of Maemo, and whoever provides them is
+responsible to adapt them to changes in the Maemo archive.
+
 All packages in the Maemo archive should work well with each other and
 in all possible configurations and targets, not just the officially
 supported configurations and targets.  They do this by declaring
@@ -118,14 +184,8 @@
 can not assume that it will never be a installation candidate in a
 device that runs the Maemo OS on real hardware.  If such a package
 must be prevented from being installed, the reasons need to be
-identified and expressed with dependencies and conflicts.  
+identified and expressed with dependencies and conflicts.
 
-There can only be a single source package in the whole Maemo archive
-with a given name and version; and only a single binary package with a
-given name, version, and architecture.  A given version of a package
-can be in more than one distribution at the same time, of course, but
-it must be the exact same ".dsc" or ".deb" file.
-
 ** Categories
 
 The packages in the Maemo archive are divided into one or more
@@ -147,7 +207,7 @@
  maemo.org-non-free
 
 In detail:
-
+   
  - nokia-free
 
  Packages in nokia-free are Free Software.  They are licensed with a
@@ -210,17 +270,19 @@
  of normal users use this distribution.
 
  Packages in harmattan-stable should be installable: all their
- run-time dependencies should be available, among other things.
+ run-time dependencies should be available, and installing should not
+ fail, among other things.
 
  Packages in harmattan-stable should be compilable: all their build
- dependencies should be available, among other things.
+ dependencies should be available, and building should not fail, among
+ other things.
 
  - harmattan-testing
 
- This distribution contains the current state of the upcoming release
- of Harmattan.  This is the build environment for most newly uploaded
- source packages.  Developers use this distribution in the SDK.  Beta
- testers use this distribution on their devices.
+ This distribution contains the current state of the upcoming releases
+ in the Harmattan project.  This is the build environment for most
+ newly build packages.  Developers use this distribution in the SDK.
+ Testers use this distribution on their devices.
 
  Packages in harmattan-testing don't need to be installable: it is OK
  if dependencies are missing, just as it is OK to have other critical
@@ -442,14 +504,14 @@
 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.
+The packages computed in one 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
+install into an 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.
 
@@ -473,14 +535,13 @@
 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.
+Depending on its intended use, a configuration 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).
+more "images" that are prepared from packages in the Maemo archive.
 
 Often, packages are 'installed' into a image by letting the package
 management tools create a root filesystem in the normal way.  Such a
@@ -496,7 +557,7 @@
 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).
+archive.
 
 The tools for creating these images are contained in the Maemo archive
 and are maintained like any other component.  They are controlled by


