251 lines
9.0 KiB
HTML
251 lines
9.0 KiB
HTML
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
|
|
<html>
|
|
<head>
|
|
|
|
|
|
<meta content="text/html; charset=UTF-8" http-equiv="content-type">
|
|
|
|
|
|
|
|
<title>Directory structure</title>
|
|
<meta content="$Author$" name="author">
|
|
</head>
|
|
|
|
|
|
<body>
|
|
|
|
<h1>Preface</h1>
|
|
|
|
This document is part of the <a href="http://livesupport.campware.org/">LiveSupport</a>
|
|
project, Copyright © 2004 <a href="http://www.mdlf.org/">Media
|
|
Development Loan Fund</a>, under the GNU <a href="http://www.gnu.org/licenses/gpl.html">GPL</a>.<br>
|
|
|
|
<ul>
|
|
|
|
<li>Author: $Author$</li>
|
|
|
|
<li>Version: $Revision$</li>
|
|
|
|
<li>Location: $URL:
|
|
svn+ssh://maroy@code.campware.org/home/svn/repo/livesupport/trunk/livesupport/doc/developmentEnvironment/directoryStructure.html
|
|
$<br>
|
|
|
|
</li>
|
|
|
|
</ul>
|
|
|
|
<h1>Scope</h1>
|
|
|
|
This document describes the directory structure used for all component
|
|
of the LiveSupport project.<br>
|
|
|
|
<h1>Introduction</h1>
|
|
|
|
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.<br>
|
|
|
|
<br>
|
|
|
|
As seen below, the main inspiration for each components directory
|
|
structure is the <a href="http://www.pathname.com/fhs/">Filesystem
|
|
Hierarchy Standard</a>.<br>
|
|
|
|
<h1>Overall structure</h1>
|
|
|
|
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.<br>
|
|
|
|
<br>
|
|
|
|
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.<br>
|
|
|
|
<br>
|
|
|
|
Both modules and products may reference (depend on) other modules, but
|
|
circular reference is not allowed.<br>
|
|
|
|
<br>
|
|
|
|
Other needed parts of the directory structure are involved with
|
|
external libraries LiveSupport depends on, and a running environment
|
|
where LiveSupport can run.<br>
|
|
|
|
<br>
|
|
|
|
The directory structure is organized in the following way:<br>
|
|
|
|
<br>
|
|
|
|
<code></code>
|
|
<pre>livesupport<br>|-- configure<br>|-- bin<br>|-- doc<br>|-- etc<br>|-- src<br>| |-- modules<br>| | |-- module1<br>| | |-- module2<br>| ...<br>| | `-- moduleN<br>| |-- products<br>| | |-- product1<br>| | |-- product2<br>| | ...<br>| | `-- productN<br>| `-- tools<br>| |-- tool1<br>| |-- tool2<br>| ...<br>| `-- tool3<br>|-- tmp<br>|-- usr<br>`-- var<br></pre>
|
|
|
|
<br>
|
|
|
|
<h2>Referencing modules and the running environment<br>
|
|
|
|
</h2>
|
|
|
|
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 <code>../moduleX</code>. If a product is referencing the
|
|
same module, it can be sure that it is located at <code>../../modules/moduleX</code>.<br>
|
|
|
|
<br>
|
|
|
|
Furthermore, if a module or product is referencing the running
|
|
environment under <code>livesupport/usr</code>, it can also be sure
|
|
that it is located at <code>../../../usr</code> from either the module or
|
|
the product directory.<br>
|
|
|
|
<br>
|
|
|
|
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 <code>../../modules/moduleX/lib/libmoduleX.so</code>.<br>
|
|
<br>
|
|
Please note that the above relative reference are valid in the build
|
|
environment only! After a module or product is installed, it can make
|
|
no assumptions on the relative locations of other components.<br>
|
|
|
|
<h1>Top-level configure script</h1>
|
|
|
|
The top-level <code>configure</code> script takes care of <a href="http://www.gnu.org/software/autoconf/">autoconf</a>-style configuring the whole LiveSupport project. This involves running <code>configure</code> in all tool, module and product directories, and creating a top-level <code>Makefile</code>.<br>
|
|
<br>
|
|
The configure script is expected to run autoconf in case the
|
|
autoconf-style environment has not yet been set up. This typically
|
|
involves executing an autogen.sh script from the bin directory.<br>
|
|
|
|
<br>
|
|
|
|
<h1>Documentation directory</h1>
|
|
|
|
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.<br>
|
|
|
|
<h1>Configuration files</h1>
|
|
|
|
Under the <code>etc</code> directory project-wide configuration files
|
|
are found, like the ones used by the top-level configure script. This
|
|
typically involves having autoconf sources (configure.ac,
|
|
acinlcude.m4), and the input for the top-level Makefile (Makefile.in).<br>
|
|
|
|
<h1>Module structure</h1>
|
|
|
|
Each module has the same directory structure, which is as follows:<br>
|
|
|
|
<br>
|
|
|
|
<pre>moduleX<br>|-- configure<br>|-- bin<br>|-- etc<br>|-- include<br>| `-- LiveSupport<br>| `-- ModuleX<br>|-- lib<br>|-- src<br>|-- tmp<br>`-- var<br></pre>
|
|
|
|
<h4>configure</h4>
|
|
|
|
An <a href="http://www.gnu.org/software/autoconf/">autoconf</a>-style configure script. See the <a href="buildEnvironment.html">build environment</a> document for a
|
|
detailed description.<br>
|
|
|
|
<h4>bin</h4>
|
|
|
|
Directory containing all executables.<br>
|
|
|
|
<h4>etc</h4>
|
|
|
|
All configuration files go here.<br>
|
|
|
|
<h4>include</h4>
|
|
|
|
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 <code>Foo.h</code>
|
|
for <code>ModuleX</code> would be contained in the directory <code>include/LiveSupport/ModuleX/Foo.h</code>,
|
|
and would be included with the line:<br>
|
|
|
|
<br>
|
|
|
|
<pre>#include "LiveSupport/ModuleX/Foo.h"<br></pre>
|
|
|
|
<h4>lib</h4>
|
|
|
|
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 <code>../../../usr/lib</code>
|
|
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 <code>liblivesupport_modulex.so</code>, and thus would
|
|
be linked to with the linker option <code>-L../../modules/moduleX/lib
|
|
-llivesupport_modulex</code>.<br>
|
|
|
|
<h4>src</h4>
|
|
|
|
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.<br>
|
|
|
|
<h4>tmp</h4>
|
|
|
|
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.<br>
|
|
|
|
<h4>var</h4>
|
|
|
|
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.<br>
|
|
|
|
<h1>Product structure</h1>
|
|
|
|
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 <code>include</code> directory.<br>
|
|
|
|
<h1>Tools structure</h1>
|
|
|
|
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.<br>
|
|
|
|
Each tool has its own directory, where several versions of the same
|
|
tool may reside. Thus the generic directory structure is as follows:<br>
|
|
|
|
<pre>tools<br>|-- tool1<br>| |-- tool1-X<br>| |-- tool1-Y<br>| ...<br>| `-- tool1-Z<br> ...<br>`-- toolN<br> |-- toolN-A<br> |-- toolN-B<br> ...<br> `-- toolN-C<br></pre>
|
|
|
|
Thus a user can select version X of toolK to be installed by selecting
|
|
the directory <code>tools/toolK/toolK-X</code>. Each tool directory
|
|
has the following structure:<br>
|
|
|
|
<pre>toolK-X<br>|-- configure<br>|-- bin<br>|-- etc<br>|-- src<br>| `-- toolK-X.tar.gz<br>`-- tmp<br></pre>
|
|
|
|
The <code>configure</code> script is an autoconf-style configure script that creates a <code>Makefile</code> in the tool directory, reflecting typical configuration settings like <code>--prefix</code>.
|
|
Executing make install in the tool directory will result in the
|
|
compilation and installation of the specific tool into the specified <code>${prefix}</code>. <br>
|
|
<br>
|
|
In case the source needs to patched before compilation, the patches may
|
|
be contained in the <code>etc</code> directory.<br>
|
|
|
|
<h1>usr structure</h1>
|
|
|
|
The usr directory is similar to the /usr system directory on UNIX
|
|
systems (see the <a href="http://www.pathname.com/fhs/">Filesystem
|
|
Hierarchy Standard</a>). 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.<br>
|
|
|
|
<br>
|
|
|
|
</body>
|
|
</html>
|