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

[From: subversion at stage.maemo.org]

Author: marivoll
Date: 2008-12-05 03:25:38 +0200 (Fri, 05 Dec 2008)
New Revision: 16867

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-04 15:55:30 UTC (rev 16866)
+++ projects/haf/doc/mvo/system-model-2.txt	2008-12-05 01:25:38 UTC (rev 16867)
@@ -73,18 +73,27 @@
 Source packages are released by their maintainers and compiled into
 binary packages.  Binary packages are installed into devices etc.
 
-In the following, "package" refers to a binary package.  Source
-packages are mostly ignored and treated as an implementation detail.
+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
+files can be, for example, stored directly in a filesystem, they can
+be archived into a tarball, or hosted in a version control system.
 
-Maemo supports multiple machine architectures.  If a package is
+A binary package is a file following the Debian policy for binary
+packages.  It usually has a name of the form
+"package_version_architecture.deb".
+
+Maemo supports multiple machine architectures.  If a binary 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.
+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
 and version already exists in the Maemo archive, no other package with
@@ -92,38 +101,124 @@
 
 * System architecture
 
-Maemo is purposeful and flexible.
+The Maemo system is documented as a set of hypertext documents.  This
+set is generated from information found in the Maemo archive.  Some of
+it is manually written and extracted from specially marked packages,
+other parts are generated programmatically under control of other
+packages.
 
 ** Components
 
-Components are in packages.
+Components are the basic software artifacts: static ones like
+programs, libraries, modules, plugins, functions, classes and dynamic
+ones like data bases, processes, objects, pipes.  Static components
+are contained in packages and the package management tools can map
+from many static components to package names.  Dynamic components
+appear at run-time.
 
+Components are identified and named in an ad-hoc manner when it is
+helpful.  Components are expected to change frequently and are not
+formally tracked in the architecture documentation.
+
+** Subsystems
+
+A subsystem is a collection of source packages that are functionally
+related and maintained in close cooperation.  Subsystems roughly mark
+the boundaries between "us" and "them", where cooperation between
+developers no longer happens automatically and can benefit from a
+little formality.
+
+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.
+
 ** Interfaces
 
-Interfaces have names.  Packages provide interfaces.  Usually, the
-package name is the name of the single interface it provides.
+[ Need some input from the services discussion here. ]
 
-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, ...
+Interfaces are contracts between components.  However, interfaces are
+only tracked on a subsystem level.
 
-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.
+Interfaces have a name, and optionally a version.
 
-** Subsystems
+Two things about interfaces are of interest: finding clients of
+interfaces so that changes to interfaces can be managed, and finding
+providers of required interfaces so that a working system can be
+assembled from the available components.
 
-Collections of functionally related packages.  Packages declare their
-subsystem.
+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.
 
+Packages that use the interfaces provided by this subsystem should be
+found automatically and listed as well.
+
+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.
+
+A package interface is a interface that is made available by
+installing a specific package.  Examples are shared libraries, header
+files to compile against shared libraries, programs, or sets of data
+files such as translations.  Package interfaces should follow Debian
+policy.  The name and version of the package is the name and version
+of the interface.  The package management tools make sure that package
+interface dependencies are satisfied.
+
+A subsystem need only list those package interfaces of the ones it
+provides that people will have to specify by hand (e.g. build
+dependencies).  Package interfaces that are handled automatically by
+the build-tools need not be listed.
+
+A virtual package interface is a interface that is made available by
+installing any one of the set of packages that "provide" the interface
+(in the sense of Debian policy).  The name used in the "provide"
+declarations is the name of the interface.  Virtual package interfaces
+have no version.  The package management tools make sure that virtual
+package interface dependencies are satisfied.  Virtual package
+interface names must be unique in the Maemo archvie and must not be
+the name of any package.
+
+A D-Bus interface is a connection that can be found on the session or
+system D-Bus with a well-known bus name.  The well-known bus name of
+the connection is the name of the interface.  D-Bus interfaces have no
+versions.  There is no automatic way to find clients or providers of
+D-Bus interfaces statically, but there probably should be one.
+
+A configuration file modification interface ("file interface" for
+short) is a interface that clients use by modifying well known files
+or directories.  For example, dropping .desktop files into
+/usr/share/applications/hildon/ is a file interface.  The well-known
+name of the file or directory is the name of the file interface.  File
+interfaces have no version.  Clients and providers of file interfaces
+are hard to find automatically, but we should try.  The provider of a
+file interface might help with the process.
+
 *** Top-level interfaces
 
+A set of interfaces.
+
 ** Layers
 
-Subsystem completely in one layer.  No dependencies from (a package in
-a subsystem in a) lower layer to an upper layer.
+The Maemo system is roughly structured into three layers: base,
+middleware, and applications.
 
+A subsystem must be contained completely in one layer.  Thus a layer
+is defined by listing its subsystems.
+
+A package in a lower layer can not depend on a package in an upper
+layer.
+
 *** Base
 
 Bottom layer, basic OS services such as hardware adaptation, network,
@@ -142,12 +237,11 @@
 
 *** Applications
 
-Subsystems in the application layer are mostly independent from each
-other.
+Subsystems in the application layer are independent from each other.
 
 ** Domains
 
-Collection of subsystems, maps to teams.
+Collection of subsystems, map to teams.
 
 * Archive