From 65507bce95d2f16897fede7846b7423cbb8e6563 Mon Sep 17 00:00:00 2001 From: maroy Date: Mon, 3 Oct 2005 13:25:15 +0000 Subject: [PATCH] added installation guidelines --- .../buildEnvironment.html | 182 ++++++++++++++++-- .../directoryStructure.html | 141 +++++++++++--- .../doc/developmentEnvironment/index.html | 36 +++- .../developmentEnvironment/installation.html | 166 ++++++++++++++++ 4 files changed, 480 insertions(+), 45 deletions(-) create mode 100644 livesupport/doc/developmentEnvironment/installation.html diff --git a/livesupport/doc/developmentEnvironment/buildEnvironment.html b/livesupport/doc/developmentEnvironment/buildEnvironment.html index 2471d0d7f..a31eac310 100644 --- a/livesupport/doc/developmentEnvironment/buildEnvironment.html +++ b/livesupport/doc/developmentEnvironment/buildEnvironment.html @@ -1,74 +1,228 @@ - + + + + + + + + + + + Build environment + + + +

Preface

+ + This document is part of the LiveSupport -project, Copyright © 2004 Media -Development Loan Fund, under the GNU GPL.
+project, Copyright © 2004 Media +Development Loan Fund, under the GNU GPL.
+ + + +

Scope

+ + This document describes the build environment for components of the LiveSupport project.
+ +

Introduction

+ + As seen in the directory structure description, each component is contained in its own directory, and has -the same general directory layout, which includes a Makefile on the top -of the directory. All components are build by GNU make working on -that Makefile. This document describes the targets for that Makefile.
+the same general directory layout, which includes a configure script on the top +of the directory. This script is responsible for gathering compilation and installation information, and for creating a Makefile in the top directory. All components are built by using GNU make working on +that Makefile.
+
-Parts of this document is inspired by the GNU Coding Standards + +This document describes details about the configure script, the targets for the generated Makefile, and related files involved with the installation of the component.
+ + +
+ + +Parts of this document are inspired by the GNU Coding Standards Makefile Conventions Standard targets.
-

Make targets
-

+ + +

The configure script and generated files
+ +

+ +

configure options

+ +The configure script should honor the generic directory settings passed to it:
+ +
+ +
Installation directories:
  --prefix=PREFIX         install architecture-independent files in PREFIX
                          [/usr/local]
  --exec-prefix=EPREFIX   install architecture-dependent files in EPREFIX
                          [PREFIX]

Fine tuning of the installation directories:
  --bindir=DIR           user executables [EPREFIX/bin]
  --sbindir=DIR          system admin executables [EPREFIX/sbin]
  --libexecdir=DIR       program executables [EPREFIX/libexec]
  --datadir=DIR          read-only architecture-independent data [PREFIX/share]
  --sysconfdir=DIR       read-only single-machine data [PREFIX/etc]
  --sharedstatedir=DIR   modifiable architecture-independent data [PREFIX/com]
  --localstatedir=DIR    modifiable single-machine data [PREFIX/var]
  --libdir=DIR           object code libraries [EPREFIX/lib]
  --includedir=DIR       C header files [PREFIX/include]
  --oldincludedir=DIR    C header files for non-gcc [/usr/include]
  --infodir=DIR          info documentation [PREFIX/info]
  --mandir=DIR           man documentation [PREFIX/man]
+ +
+ +Other configuration-time options should be processed using --with-XXX arguments, using the AC_ARG_WITH autoconf macro.
+ +
+ +Note: when writing etc/configure.ac, the input for the configure script, the Autoconf Macro Archive can provide quite useful.
+ +
+ +

generated files

+ +The main file generated by the configure script will the the Makefile. The input for the Makefile, etc/Makefile.in, can refer to the variables substituted by configure in the following way:
+ +
+ +
prefix = @prefix@
some_other_var = @some_other_var@
+ +
+ +Because these variables might need to be overwritten when running the Makefile, make sure to use the same name for the variable inside the Makefile as was used by the configure script (as in the above example). For example:
+ +
+ +
# these are wrong!
PREFIX = @prefix@
myvar = @some_other_var@

# these are correct, and have the same desired effect:
prefix = @prefix@
some_other_var = @some_other_var@
PREFIX = ${prefix}
myvar = ${some_other_var}
+ +
+ +Using the same names will make it possible to overwrite the values substituted by configure when invoking the Makefile, for example:
+ +
+ +
make prefix=/foo/bar install
+ +
+ +will cause installation under the prefix /foo/bar, irrespective of the prefix supplied to configure.
+ + +

Make targets
+ + +

+ + The following make targets are required for all components to support:
+ + + +

all

+ + Compile all source files for this component.  As a result, the component is ready to be run (if an executable) or linked to (if a library).
+ + This target traverses the dependent modules, and executes the all target on them, if their targets do not exist.
+ +

clean

+ + Delete all files generated by the all target, but only for this module (e..g. no files for dependent modules are deleted).
+ +

depclean

+ + Delete all the dependent target files. Executing the depclean target with an all target afterwards results in a full recompilation of all the dependent modules.
+ +

doc

+ + Generate the documentation for this component. This would include processing info pages, or using tools to generate documentation based on comments in the source code (like javadoc).
+ +

dist

+ + Create a distribution package for this component. This involves possibly compiling, document generation and other tasks, and results in an archive containing the distribution.
+ +

check

+ + Run all tests, especially unit tests, for the component. This usually results in a generated test-report.
+ +
+ +

install

+ +Installs the component into the specified prefix. (See the Installation document for details.)
+ +
+ diff --git a/livesupport/doc/developmentEnvironment/directoryStructure.html b/livesupport/doc/developmentEnvironment/directoryStructure.html index 5c2989b6d..e100a3c0c 100644 --- a/livesupport/doc/developmentEnvironment/directoryStructure.html +++ b/livesupport/doc/developmentEnvironment/directoryStructure.html @@ -1,156 +1,241 @@ - + + + + + + Directory structure + + +

Preface

+ This document is part of the LiveSupport -project, Copyright © 2004 Media -Development Loan Fund, under the GNU GPL.
+project, Copyright © 2004 Media +Development Loan Fund, under the GNU GPL.
+ +

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
+
livesupport
|-- configure
|-- bin
|-- doc
|-- etc
|-- src
|   |-- modules
|   |   |-- module1
|   |   |-- module2
|    ...
|   |   `-- moduleN
|   |-- products
|   |   |-- product1
|   |   |-- product2
|   |    ...
|   |   `-- productN
|   `-- tools
|       |-- tool1
|       |-- tool2
|        ...
|       `-- tool3
|-- tmp
|-- usr
`-- var
+
+

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 +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.

+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 LiveSupport 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 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.
+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
|-- Makefile
|-- bin
|-- etc
|-- include
|   `-- LiveSupport
|       `-- ModuleX
|-- lib
|-- src
|-- tmp
`-- var
-

Makefile

-A makefile executable by GNU make. See the build environment document for a + +
moduleX
|-- configure
|-- bin
|-- etc
|-- include
|   `-- LiveSupport
|       `-- ModuleX
|-- lib
|-- src
|-- tmp
`-- var
+ +

configure

+ +An autoconf-style configure script. 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.
+ +Directory containing all executables.
+

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 +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
+ +
toolK-X
|-- configure
|-- bin
|-- etc
|-- src
|   `-- toolK-X.tar.gz
`-- tmp
+ +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 @@ -158,6 +243,8 @@ 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.
+
+ diff --git a/livesupport/doc/developmentEnvironment/index.html b/livesupport/doc/developmentEnvironment/index.html index e5be5401b..6bac3135f 100644 --- a/livesupport/doc/developmentEnvironment/index.html +++ b/livesupport/doc/developmentEnvironment/index.html @@ -1,35 +1,63 @@ + + + + + LiveSupport development environment + + +

Preface

+ This document is part of the LiveSupport -project, Copyright © 2004 Media -Development Loan Fund, under the GNU GPL.
+project, Copyright © 2004 Media +Development Loan Fund, under the GNU GPL.
+ +

Scope

+ This document gives an overview of the LiveSupport development environment.
+

Introduction

+ The LiveSupport project defines a uniform development environment to enhance collaboration of participants in the project. The following aspects of the environment are defined so far:
+ +
+
+ diff --git a/livesupport/doc/developmentEnvironment/installation.html b/livesupport/doc/developmentEnvironment/installation.html new file mode 100644 index 000000000..495b6b082 --- /dev/null +++ b/livesupport/doc/developmentEnvironment/installation.html @@ -0,0 +1,166 @@ + + + + + + + + + + Component Installation Guidelines + + + + + + +

Preface

+ +This document is part of the LiveSupport +project, Copyright © 2004 Media +Development Loan Fund, under the GNU GPL.
+ + + +

Scope

+ +This document describes the installation procedures used by the components of the LiveSupport project.
+ +

Introduction

+Component installation is a process more tricky than it seems at first. +For example, when using a binary package manager, the component is +configured and compiled on a different system (the one creating the +binary package) than the one it will run on at the end.
+
+Installation also involves related issues like uninstallation and product +version migration, which also have to be discussed here.
+
+

Installation use cases

+

Basic installation

+The basic installation procedure is as follows.
+

1.  setting up the sources

+Get and unpack the source tarball(s), patch them if necessary. Make sure all tools required by the build are present.
+

2. configuring the sources

+Run the configure script on the unpacked source tree.
+
+Assumptions:
+ +

3. compile the sources

+The sources are compiled (if needed) by the invoking make all.
+

4. install the component

+Install (copy) the component, possibly into a different directory than +what was specified at step 2. This basically involves copying relevant +files from the (built) source directory tree into a target directory +tree.
+

5. post-installation setup

+Do post-installation (post-copy) setup of the component. This might involve the following:
+ +Assumptions:
+ +
+

Basic uninstallation

+The basic uninstallation procedure is the following.
+

1. pre-uninstallation steps

+Destroy any resources used by the component, with the components itself still being installed. This might involve:
+ +Assumptions:
+ +

2. uninstall the component

+Remove the components files from the filesystem.
+
+

Upgrading

+TODO: detail the upgrading procedure
+
+

Provisions in the build environment

+For the above goals to be met, the following structure is needed for each component in the build environment:
+
+
componentX
|-- configure
|-- bin
|   |-- autogen.sh
|   |-- postInstall.sh
|   `-- preUninstall.sh
`-- etc
    |-- acinclude.m4
    |-- configure.ac
    `-- Makefile.in
+

Considerations about specific installation steps

+

1.  setting up the sources

+none: this step is external to the package.
+

2. configuring the sources

+Assumptions: + +

3. compile the sources

+Assumptions:
+ +

4. install the component

+When using package managers, this step is usually two-fold:
+ +Note that there is a lot of package manager-specific magic happening +between these two steps, and that the steps usually take place on +different machines (after all the package is only build on one, while +it will be installed on a miriad of systems).
+
+Assumptions:
+ +

5. post-installation setup

+The bin/postInstall.sh script should be used to perform +the post-installation setup. The script should expect all variables it +needs to be supplied by command-line arguments.
+
+Assumptions:
+ +

Considerations about specific uninstallation steps

+

1. pre-uninstallation steps

+The bin/preUninstall.sh script should be used to perform +the pre-uninstallation steps. The script should expect all variables it +needs to be supplied by command-line arguments.
+
+Assumptions:
+ +

2. uninstall the component

+none: this step is external to the package
+ + +