This document describes the directory structure used for all component
of the Campcaster 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.
The base campcaster directory contains all the special tools needed to
build, test and run Campcaster, along with all the source code that
constitutes Campcaster itself.
The self written part of Campcaster 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 Campcaster depends on, and a running environment
where Campcaster can run.
The directory structure is organized in the following way:
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 campcaster/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.
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.
Top-level configure script
The top-level configure script takes care of autoconf-style configuring the whole Campcaster project. This involves running configure in all tool, module and product directories, and creating a top-level Makefile.
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.
Documentation directory
The doc directory contains generic documentation with respect to the
whole Campcaster 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 configure script. This
typically involves having autoconf sources (configure.ac,
acinlcude.m4), and the input for the top-level Makefile (Makefile.in).
Module structure
Each module has the same directory structure, which is as follows:
moduleX |-- configure |-- bin |-- etc |-- include | `-- Campcaster | `-- ModuleX |-- lib |-- src |-- tmp `-- var
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/Campcaster/ModuleX/Foo.h,
and would be included with the line:
#include "Campcaster/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 libcampcaster_modulex.so, and thus would
be linked to with the linker option -L../../modules/moduleX/lib
-lcampcaster_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 Campcaster system. These tools are
installable to the usr directory of the Campcaster 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:
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:
The configure script is an autoconf-style configure script that creates a Makefile in the tool directory, reflecting typical configuration settings like --prefix.
Executing make install in the tool directory will result in the
compilation and installation of the specific tool into the specified ${prefix}.
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 Campcaster system. This
directory is separate from the system /usr directory in order to
facilitate changing the configuration for Campcaster related libraries
and tools in user space.