Preface
This document is part of the LiveSupport
project, Copyright © 2004 Media
Development Loan Fund, under the GNU GPL.
- Author: $Author: maroy $
- Version: $Revision: 1.1 $
- Location: $Source: /home/paul/cvs2svn-livesupport/newcvsrepo/livesupport/doc/developmentEnvironment/directoryStructure.html,v $
Scope
This document describes the directory structure used for all component
of the LiveSupport project.
Introduction
It is important to define a common and uniform directory structure in
order to allow more seamless cooperation between participants of the
project. It also helps referencing the various components (modules,
etc.), as all the components will have a predictable and stable file
hierarchy.
As seen below, the main inspiration for each components directory
structure is the Filesystem
Hierarchy Standard.
Overall structure
The base livesupport directory contains all the special tools needed to
build, test and run LiveSupport, along with all the source code that
constitutes LiveSupport itself.
The self written part of LiveSupport project consists of re-usable
modules, and products.
Modules are components that do not execute by themselves, but have a
useful, preferably generic functionality. Products are the executable
components that are actually run by users.
Both modules and products may reference (depend on) other modules, but
circular reference is not allowed.
Other needed parts of the directory structure are involved with
external libraries LiveSupport depends on, and a running environment
where LiveSupport can run.
The directory structure is organized in the following way:
livesupport
|-- Makefile
|-- doc
|-- etc
|-- modules
| |-- module1
| |-- module2
...
| `-- moduleN
|-- products
| |-- product1
| |-- product2
| ...
| `-- productN
|-- tools
| |-- tool1
| |-- tool2
| ...
| `-- tool3
`-- usr
Referencing modules and the running environment
As a consequence of the directory structure above, if a module is
referencing an other (e.g. moduleX), than it can be sure that it is
located at ../moduleX
. If a product is referencing the
same module, it can be sure that it is located at ../../modules/moduleX
.
Furthermore, if a module or product is referencing the running
environment under livesupport/usr
, it can also be sure
that it is located at ../../usr
from either the module or
the product directory.
Referencing always means exactly that: no contents are copied from one
module directory to an other. For example for a module or product to
reference the shared libraries of moduleX means to do exactly that:
link to the library ../../modules/moduleX/lib/libmoduleX.so
.
Top-level Makefile
The top-level Makefile provides targets that effect the whole of the
LiveSupport project. Currently the only target is doc
,
which generates the documentations for the whole project under the doc
directory.
Documentation directory
The doc directory contains generic documentation with respect to the
whole LiveSupport project. Documentation pertaining to a module or
products should go under the modules' or products' directory,
respectively.
Configuration files
Under the etc
directory project-wide configuration files
are found, like the ones used by the top-level Makefile.
Module structure
Each module has the same directory structure, which is as follows:
moduleX
|-- Makefile
|-- bin
|-- etc
|-- include
| `-- LiveSupport
| `-- ModuleX
|-- lib
|-- src
|-- tmp
`-- var
Makefile
A makefile executable by GNU make. See the build environment document for a
detailed description.
bin
Directory containing all executables, either if these are executable
used for building the module, or executables resulting from the build.
etc
All configuration files go here.
include
The public C/C++ header files for this module. The include files are
stored in a subdirectory that completely replicates the namespacing of
the module itself, in a case-sensitive manner. Thus a header file name Foo.h
for ModuleX
would be contained in the directory include/LiveSupport/ModuleX/Foo.h
,
and would be included with the line:
#include "LiveSupport/ModuleX/Foo.h"
lib
Directory containing all shared and static libraries that are generated
by building the module. All external, third-party libraries used by
this module should be installed into the ../../usr/lib
directory. The libraries are named resembling the full namespacing of
the module, but all lower cased. For example, the library for moduleX
would be named liblivesupport_modulex.so
, and thus would
be linked to with the linker option -L../../modules/moduleX/lib
-llivesupport_modulex
.
src
Contains all source files. A source file is a file which is processed
(compiled, etc.) by the build process, and as a result some target
files are generated from it.
tmp
A temporary directory, holding temporary files used by the build
process. This directory either does not exist in the configuration
management system, or is empty there.
var
Directory containing data. This can range from XML data to HTML pages
to all other files that are not source files (are not processed by the
build process). Note that web-page scripting files like PHP files also
fall into this category.
Product structure
The directory structure for a product is in essence the same as for
modules, described above, with the difference that products don't have
externally visible include files, thus their directories don't contain
an include
directory.
Tools structure
The tools directory is an archive of tools and external libraries used
for either building or running the LiveSupport system. These tools are
installable to the usr directory of the LiveSupport directory tree.
Each tool has its own directory, where several versions of the same
tool may reside. Thus the generic directory structure is as follows:
tools
|-- tool1
| |-- tool1-X
| |-- tool1-Y
| ...
| `-- tool1-Z
...
`-- toolN
|-- toolN-A
|-- toolN-B
...
`-- toolN-C
Thus a user can select version X of toolK to be installed by selecting
the directory tools/toolK/toolK-X
. Each tool directory
has the following structure:
toolK-X
|-- bin
| `-- install.sh
|-- etc
|-- src
| `-- toolK-X.tar.gz
`-- tmp
The script bin/install.sh
is responsible for installing
the specific tool under the livesupport/usr
directory.
This typically involves the following steps:
cd tmp
tar xfz ../src/toolK-X.tar.gz
./configure --prefix=../../../../usr
make install
In case the source needs to patched before compilation, the patches may
be contained in the etc
directory.
usr structure
The usr directory is similar to the /usr system directory on UNIX
systems (see the Filesystem
Hierarchy Standard). This directory contains all the external tools
needed by either developing or running the LiveSupport system. This
directory is separate from the system /usr directory in order to
facilitate changing the configuration for LiveSupport related libraries
and tools in user space.