Preface

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.