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

[From: subversion at stage.maemo.org]

Author: marivoll
Date: 2008-12-09 14:48:47 +0200 (Tue, 09 Dec 2008)
New Revision: 16912

Modified:
   projects/haf/doc/mvo/system-model-2.txt
Log:
More fantastic stuff about interfaces!


Modified: projects/haf/doc/mvo/system-model-2.txt
===================================================================
--- projects/haf/doc/mvo/system-model-2.txt	2008-12-09 12:48:26 UTC (rev 16911)
+++ projects/haf/doc/mvo/system-model-2.txt	2008-12-09 12:48:47 UTC (rev 16912)
@@ -12,11 +12,16 @@
 .. Components
 .. Subsystems
 .. Interfaces
-... Top-level interfaces
+... Package interfaces
+... Virtual package interfaces
+... D-Bus interfaces
+... File interfaces
+... Miscellaneous interfaces
+... Interfaces examples
 .. Layers
-... Base
-... Middleware
-... Applications
+... Base layer
+... Middleware layer
+... Applications layer
 .. Domains
 
 . Archive
@@ -102,18 +107,21 @@
 
 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.
+files can be stored directly in a filesystem, for example, they can be
+archived into a tarball, or they can be hosted in a version control
+system.
 
-A binary package is a file following the Debian policy for binary
-packages.  It usually has a name of the form
+A binary package is one file per architecture following the Debian
+policy for binary packages.  The files usually have names 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 ".deb" files, but this text still treats them as a single
-binary package.
+separate ".deb" files, but for simplicity, this text still treats them
+as a single binary package.  This means that machine architectures are
+not allowed to drift apart in the archive: every architecture must
+contain the same version of a package, or none at all.
 
 In the following, "package" refers to binary packages.
 
@@ -134,10 +142,10 @@
 
 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.
+ones like data bases, processes, objects, pipes, etc.  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
@@ -168,73 +176,181 @@
 subsystem are managed in whatever way the subsystem maintainers agree
 on.
 
-Interfaces have a formal name, and optionally a version.
+Interfaces have a name, but no version.  They are formally tracked in
+the Maemo archive (somehow) and available to tools.
 
-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.
+[ Versioning interfaces is ultimately not enough.  The evolution of an
+  interafce can be time stamped with versions, but these time stamps
+  can not really express the impact the interface changes have on
+  clients.  Some kinds of interfaces, such as package interfaces (see
+  below) put restrictions on how interfaces can evolve which might
+  make a interface version useful, but in general, compatibility
+  between providers and clients of an interface can not be expressed
+  with a single scalar.
+]
 
-In general, a subsystem should list all interfaces that it provides,
-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.
+A interface belongs to exactly one subsystem and the interface
+documentation is maintained by the maintainers of that subsystem.  A
+subsystem explicitly lists the interfaces it contains.
 
-Packages that use the interfaces provided by a subsystem should be
-found automatically and listed as well.
+A interface can have providers and clients.  Generally, the packages
+with the components related to an interface are found automatically
+from the definition of that interface.  From packages we can find
+subsystems, and thus we can also talk about subsystems as the
+providers and clients of interfaces.
 
-Thus, interfaces formally tracked in the Maemo archive and available
-to tools.
+A component is said to "depend" on a second component if the first
+component becomes completely useless or even harmful when the second
+component is not available.  These dependencies are usually found via
+interfaces.  As with clients and providers, dependencies can travel up
+the food chain and we can talk about one subsystem depending on
+another.
 
+Not all clients of a interface depend on the providers of that
+interface.  When there is no provider, the client might have reduced
+functionality, but could otherwise work just fine.
+
 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
 miscellaneous interfaces.
 
+*** Package interface
+
 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.
+files to compile against shared libraries, programs with well-known
+names, or sets of data files such as translations.  The name of the
+package is the name of the interface.
 
-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.
+Not all packages of a subsystem are automatically package interfaces
+for the purpose of this discussion.  Only those packages need to be
+listed that developers of other subsystems need to mention in source
+code by hand.  Dependencies between package that are handled
+automatically by the build-tools need not be listed as formal package
+interfaces.
 
+For example, you only need to list the -dev package for a shared
+library package, and only if you are actually exporting it from your
+subsystem.
+
+The clients of a package interface are found automatically via the
+Depends, Recommends, and Suggests package relationships.
+
+*** Virtual package interface
+
 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.
+(in the sense of Debian policy).  The name used in the Provides
+declaration is the name of the interface.  Virtual package interface
+names must be unique in the Maemo archvie and must not be the name of
+any package.
 
+A subsystem should list those virtual package interfaces that it
+defines and that it maintains the documentation for.  Both providers
+and clients of virtual package interfaces are found automatically, but
+only a subsystem can decide for which virtual package interfaces it is
+responsible.
+
+*** D-Bus interface
+
 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.
+the connection is the name of the interface.  Like virtual package
+interfaces, D-Bus interfaces can have multiple providers and one
+subsystem needs to claim responsibility for the interface.
 
+Packages that are providers or clients of D-Bus interfaces should be
+automatically findable in the archive.  We probably should invent ways
+to extract this information from the source code somehow and put it
+into the packages.
+
+*** File interface
+
 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.
+name of the file or directory is the name of the file interface.  If
+the file or directory name is not unique, it should be qualified via a
+suffix of the form "#foo".
 
-*** Top-level interfaces
+A package is a provider of a file interface when it contributes
+information to the well-known file or directory.  It is a client when
+it reads information from it.  A file interfaces is usually owned by
+the subsystem that contains its major client.
 
-A set of interfaces.
+Like with D-Bus interfacex, providers and clients of file interfaces
+are not readily identifiable by just looking at the packages.  We
+should make some rules to make this reliable.
 
+*** Miscellaneous interfaces
+
+If a interface needs to be formally defined but doesn't fit any of the
+previous kinds, it is given a name of the form "misc:foo".
+
+*** Interface examples
+
+- Shared library
+
+Shared libraries should follow Debian policy.  This means that there
+is generally one package with the library itself, one package with
+headers and other information needed to compile against the library, a
+package with the documentation, and maybe some other packages.
+
+Such a shared library provides a package interface.  The name of the
+interface is the name of the package with the development information.
+The interface is used by putting this name into the Build-Depends
+field of other source packages.
+
+Other symbols that could name this interface like the identifier to
+use with pkg-config, the name of the main header file, or the name to
+use with the "-l" linker option should be mentioned in the
+documentation, but the formal name of the interface is always the name
+of the development package.
+
+- Perl, Python, etc modules
+
+These are package interfaces and very similar to shared libraries,
+except that the interface is named after the package that contains the
+Perl, Python, etc files that are loaded into the interpreter, and
+developers put these names directly into the Depends fields of
+packages.
+
+- Plugins
+
+A component that can accept plugins needsa to document two things: how
+plugins can be registered with the component, and how the plugins will
+be called.  This is combined into one interface: the registration
+method decides what kind of interface it is, and the detailed
+defintion of the regitration method includes the conventions for
+calling the plugins.
+
+Plugins are the providers of this interface, and components that load
+the plugins are the clients.
+
+Many plugins are registered by dropping ELF shared objects into a
+well-known directory and are expected to export a certain set of
+symbols.  Such a mechanism is thus a file interface and is named after
+the directory where the plugins are dropped.  The interface
+documentation will describe the expected exported symbols.
+
+- Registering actions for mime types
+
+A package can announce a list of actions that it can perform on
+certain mime-types.  It does this by including that information in its
+.desktop file, as an extension of the fd.o standard.
+
+Thus, its a file interface that is owned by the subsystem that has
+defined the fd.o extension.  The name of the interface could be
+"/usr/share/applications/hildon#mime-actions".
+
+- X server
+
+This well known interface could be named "misc:x11" and it can include
+any and all extensions to the X protocol that anybody could ever come
+up with.  Sorry X, you are miscellaneous now.
+
 ** Layers
 
 The Maemo system is roughly structured into three layers: base,
@@ -246,20 +362,20 @@
 A package in a lower layer can not depend on a package in an upper
 layer.
 
-*** Base
+*** Base layer
 
-The bottom layer that contains basic OS services such as hardware
-adaptation, network, mass storage, text console, X11, package
+This is 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.
 
-*** Middleware
+*** Middleware layer
 
 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
+*** Applications layer
 
 Subsystems in the application layer must not have dependencies on each
 other.
@@ -267,7 +383,8 @@
 ** Domains
 
 A domain is a collection of subsystems.  It is mostly a organizational
-tool.
+tool.  Domains have their own brief document that mostly lists and
+introduces the subsystems.
 
 * Archive