Congegni/sintonia
7
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity

added installation guidelines

Browse source
This commit is contained in:
maroy 2005-10-03 13:25:15 +00:00
parent 162a969646
commit 65507bce95
4 changed files with 480 additions and 45 deletions
Download patch file Download diff file Expand all files Collapse all files

182
livesupport/doc/developmentEnvironment/buildEnvironment.html
View file

@ -1,74 +1,228 @@
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html> <html>
<head> <head>
<meta content="text/html; charset=UTF-8"
http-equiv="content-type">
<meta content="text/html; charset=UTF-8" http-equiv="content-type">
<title>Build environment</title> <title>Build environment</title>
<meta content="$Author$" name="author"> <meta content="$Author$" name="author">
</head> </head>
<body> <body>
<h1>Preface</h1> <h1>Preface</h1>
This document is part of the <a href="http://livesupport.campware.org/">LiveSupport</a> This document is part of the <a href="http://livesupport.campware.org/">LiveSupport</a>
project, Copyright &#169; 2004 <a href="http://www.mdlf.org/">Media project, Copyright &copy; 2004 <a href="http://www.mdlf.org/">Media
Development Loan Fund</a>, under the GNU <a Development Loan Fund</a>, under the GNU <a href="http://www.gnu.org/licenses/gpl.html">GPL</a>.<br>
href="http://www.gnu.org/licenses/gpl.html">GPL</a>.<br>
<ul> <ul>
<li>Author: $Author$</li> <li>Author: $Author$</li>
<li>Version: $Revision$</li> <li>Version: $Revision$</li>
<li>Location: $URL$<br>
<li>Location: $URL:
svn+ssh://maroy@code.campware.org/home/svn/repo/livesupport/trunk/livesupport/doc/developmentEnvironment/buildEnvironment.html
$<br>
</li> </li>
</ul> </ul>
<h1>Scope</h1> <h1>Scope</h1>
This document describes the build environment for components of the This document describes the build environment for components of the
LiveSupport project.<br> LiveSupport project.<br>
<h1>Introduction</h1> <h1>Introduction</h1>
As seen in the <a href="directoryStructure.html">directory structure</a> As seen in the <a href="directoryStructure.html">directory structure</a>
description, each component is contained in its own directory, and has description, each component is contained in its own directory, and has
the same general directory layout, which includes a Makefile on the top the same general directory layout, which includes a <code>configure</code> script on the top
of the directory. All components are build by <a of the directory. This script is responsible for gathering compilation and installation information, and for creating a <code>Makefile</code> in the top directory. All components are built by using <a href="http://www.gnu.org/directory/make.html">GNU make</a> working on
href="http://www.gnu.org/directory/make.html">GNU make</a> working on that <code>Makefile</code>.<br>
that Makefile. This document describes the targets for that Makefile.<br>
<br> <br>
Parts of this document is inspired by the <a
href="http://www.gnu.org/prep/standards.html">GNU Coding Standards</a> This document describes details about the <code>configure</code> script,&nbsp;the targets for the generated <code>Makefile</code>, and related files involved with the installation of the component.<br>
<br>
Parts of this document are inspired by the <a href="http://www.gnu.org/prep/standards.html">GNU Coding Standards</a>
<a href="http://www.gnu.org/prep/standards_50.html">Makefile <a href="http://www.gnu.org/prep/standards_50.html">Makefile
Conventions Standard targets</a>.<br> Conventions Standard targets</a>.<br>
<h2>Make targets<br>
</h2>
<h1>The <code>configure</code> script and generated files<br>
</h1>
<h2><code>configure</code> options</h2>
The <code>configure</code> script should honor the generic directory settings passed to it:<br>
<br>
<pre>Installation directories:<br> --prefix=PREFIX install architecture-independent files in PREFIX<br> [/usr/local]<br> --exec-prefix=EPREFIX install architecture-dependent files in EPREFIX<br> [PREFIX]<br><br>Fine tuning of the installation directories:<br> --bindir=DIR user executables [EPREFIX/bin]<br> --sbindir=DIR system admin executables [EPREFIX/sbin]<br> --libexecdir=DIR program executables [EPREFIX/libexec]<br> --datadir=DIR read-only architecture-independent data [PREFIX/share]<br> --sysconfdir=DIR read-only single-machine data [PREFIX/etc]<br> --sharedstatedir=DIR modifiable architecture-independent data [PREFIX/com]<br> --localstatedir=DIR modifiable single-machine data [PREFIX/var]<br> --libdir=DIR object code libraries [EPREFIX/lib]<br> --includedir=DIR C header files [PREFIX/include]<br> --oldincludedir=DIR C header files for non-gcc [/usr/include]<br> --infodir=DIR info documentation [PREFIX/info]<br> --mandir=DIR man documentation [PREFIX/man]<br></pre>
<br>
Other configuration-time options should be processed using <code>--with-XXX</code> arguments, using the <a href="http://www.gnu.org/software/autoconf/manual/autoconf-2.57/html_node/autoconf_130.html#IDX835"><code>AC_ARG_WITH</code></a> <code>autoconf</code> macro.<br>
<br>
Note: when writing <code>etc/configure.ac</code>, the input for the <code>configure</code> script, the <a href="http://autoconf-archive.cryp.to/">Autoconf Macro Archive</a> can provide quite useful.<br>
<br>
<h2>generated files</h2>
The main file generated by the <code>configure</code> script will the the <code>Makefile</code>. The input for the <code>Makefile</code>, <code>etc/Makefile.in</code>, can refer to the variables substituted by <code>configure</code> in the following way:<br>
<br>
<pre><code>prefix = @prefix@<br>some_other_var = @some_other_var@</code></pre>
<br>
Because these variables might need to be overwritten when running the <code>Makefile</code>, make sure to use the same name for the variable inside the <code>Makefile</code> as was used by the configure script (as in the above example). For example:<br>
<br>
<pre><code># these are wrong!<br>PREFIX = @prefix@<br>myvar = @some_other_var@<br><br># these are correct, and have the same desired effect:<br></code><code>prefix = @prefix@<br>some_other_var = @some_other_var@<br>PREFIX = ${prefix}<br>myvar = ${some_other_var}</code></pre>
<span style="font-weight: bold;"><br>
</span><span style="font-weight: bold;"></span>Using the same names will make it possible to overwrite the values substituted by <code>configure</code> when invoking the <code>Makefile</code>, for example:<br>
<br>
<pre><code>make prefix=/foo/bar install</code></pre>
<br>
will cause installation under the prefix <code>/foo/bar</code>, irrespective of the prefix supplied to <code>configure</code>.<br>
<span style="font-weight: bold;"></span><span style="font-weight: bold;"></span>
<h1>Make targets<br>
</h1>
The following make targets are required for all components to support:<br> The following make targets are required for all components to support:<br>
<ul> <ul>
<li>all</li> <li>all</li>
<li>clean</li> <li>clean</li>
<li>depclean</li> <li>depclean</li>
<li>doc<br> <li>doc<br>
</li> </li>
<li>dist</li> <li>dist</li>
<li>check</li> <li>check</li>
<li>install</li>
</ul> </ul>
<h4>all</h4> <h4>all</h4>
Compile all source files for this component.&nbsp; As a result, the Compile all source files for this component.&nbsp; As a result, the
component is ready to be run (if an executable) or linked to (if a component is ready to be run (if an executable) or linked to (if a
library).<br> library).<br>
This target traverses the dependent modules, and executes the all This target traverses the dependent modules, and executes the all
target on them, if their targets do not exist.<br> target on them, if their targets do not exist.<br>
<h4>clean</h4> <h4>clean</h4>
Delete all files generated by the all target, but only for this module Delete all files generated by the all target, but only for this module
(e..g. no files for dependent modules are deleted).<br> (e..g. no files for dependent modules are deleted).<br>
<h4>depclean</h4> <h4>depclean</h4>
Delete all the dependent target files. Executing the depclean target Delete all the dependent target files. Executing the depclean target
with an all target afterwards results in a full recompilation of all with an all target afterwards results in a full recompilation of all
the dependent modules.<br> the dependent modules.<br>
<h4>doc</h4> <h4>doc</h4>
Generate the documentation for this component. This would include Generate the documentation for this component. This would include
processing info pages, or using tools to generate documentation based processing info pages, or using tools to generate documentation based
on comments in the source code (like javadoc).<br> on comments in the source code (like javadoc).<br>
<h4>dist</h4> <h4>dist</h4>
Create a distribution package for this component. This involves Create a distribution package for this component. This involves
possibly compiling, document generation and other tasks, and results in possibly compiling, document generation and other tasks, and results in
an archive containing the distribution.<br> an archive containing the distribution.<br>
<h4>check</h4> <h4>check</h4>
Run all tests, especially unit tests, for the component. This usually Run all tests, especially unit tests, for the component. This usually
results in a generated test-report.<br> results in a generated test-report.<br>
<br> <br>
<h4>install</h4>
Installs the component into the specified prefix. (See the <a href="installation.html">Installation</a> document for details.)<br>
<br>
</body> </body>
</html> </html>

141
livesupport/doc/developmentEnvironment/directoryStructure.html
View file

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

36
livesupport/doc/developmentEnvironment/index.html
View file

@ -1,35 +1,63 @@
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html> <html>
<head> <head>
<meta content="text/html; charset=UTF-8" http-equiv="content-type"> <meta content="text/html; charset=UTF-8" http-equiv="content-type">
<title>LiveSupport development environment</title> <title>LiveSupport development environment</title>
<meta content="$Author$" name="author"> <meta content="$Author$" name="author">
</head> </head>
<body> <body>
<h1>Preface</h1> <h1>Preface</h1>
This document is part of the <a href="http://livesupport.campware.org/">LiveSupport</a> This document is part of the <a href="http://livesupport.campware.org/">LiveSupport</a>
project, Copyright © 2004 <a href="http://www.mdlf.org/">Media project, Copyright &copy; 2004 <a href="http://www.mdlf.org/">Media
Development Loan Fund</a>, under the GNU <a Development Loan Fund</a>, under the GNU <a href="http://www.gnu.org/licenses/gpl.html">GPL</a>.<br>
href="http://www.gnu.org/licenses/gpl.html">GPL</a>.<br>
<ul> <ul>
<li>Author: $Author$</li> <li>Author: $Author$</li>
<li>Version: $Revision$</li> <li>Version: $Revision$</li>
<li>Location: $URL$</li>
<li>Location: $URL:
svn+ssh://maroy@code.campware.org/home/svn/repo/livesupport/trunk/livesupport/doc/developmentEnvironment/index.html
$</li>
</ul> </ul>
<h1>Scope</h1> <h1>Scope</h1>
This document gives an overview of the LiveSupport development This document gives an overview of the LiveSupport development
environment.<br> environment.<br>
<h1>Introduction</h1> <h1>Introduction</h1>
The LiveSupport project defines a uniform development environment to The LiveSupport project defines a uniform development environment to
enhance collaboration of participants in the project. The following enhance collaboration of participants in the project. The following
aspects of the environment are defined so far:<br> aspects of the environment are defined so far:<br>
<ul> <ul>
<li><a href="fileConventions.html">file conventions</a></li> <li><a href="fileConventions.html">file conventions</a></li>
<li><a href="directoryStructure.html">directory structure</a></li> <li><a href="directoryStructure.html">directory structure</a></li>
<li><a href="buildEnvironment.html">build <li><a href="buildEnvironment.html">build
environment</a></li> environment</a></li>
<li><a href="installation.html">component installation guidelines</a></li>
</ul> </ul>
<br> <br>
<br> <br>
</body> </body>
</html> </html>

166
livesupport/doc/developmentEnvironment/installation.html Normal file
View file

@ -0,0 +1,166 @@
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html>
<head>
<meta content="text/html; charset=UTF-8" http-equiv="content-type">
<title>Component Installation Guidelines</title>
<meta content="$Author: fgerlits $" name="author">
</head>
<body>
<h1>Preface</h1>
This document is part of the <a href="http://livesupport.campware.org/">LiveSupport</a>
project, Copyright &copy; 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: fgerlits $</li>
<li>Version: $Revision: 1601 $</li>
<li>Location: $URL:
svn+ssh://maroy@code.campware.org/home/svn/repo/livesupport/trunk/livesupport/doc/developmentEnvironment/buildEnvironment.html
$<br>
</li>
</ul>
<h1>Scope</h1>
This document describes the installation procedures used by the components of the LiveSupport project.<br>
<h1>Introduction</h1>
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.<br>
<br>
Installation also involves related issues like uninstallation and product
version migration, which also have to be discussed here.<br>
<br>
<h1>Installation use cases</h1>
<h2>Basic installation</h2>
The basic installation procedure is as follows.<br>
<h4>1. &nbsp;setting up the sources</h4>
Get and unpack the source tarball(s), patch them if necessary. Make sure all tools required by the build are present.<br>
<h4>2. configuring the sources</h4>
Run the <code>configure</code> script on the unpacked source tree.<br>
<br>
Assumptions:<br>
<ul>
<li>don't assume that the directory prefixes supplied to <code>configure</code> will be the final installation directories for the component</li>
<li>don't assume that the machine used for compilation will be the same machine the tool is used on (think binary package building)</li>
</ul>
<h4>3. compile the sources</h4>
The sources are compiled (if needed) by the invoking&nbsp;<code></code><code>make all</code>.<br>
<h4>4. install the component</h4>
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.<br>
<h4>5. post-installation setup</h4>
Do post-installation (post-copy) setup of the component. This might involve the following:<br>
<ul>
<li>create and customize configuration files</li>
<li>setup &amp; configure external resources, like:</li>
<ul>
<li>database tables</li>
<li>update configuration files of other tools used by this component</li>
</ul>
</ul>
Assumptions:<br>
<ul>
<li>don't assume that the component has been built (compiled) on the same system as the one doing post-installation setup.</li>
<li>running this step and pre-uninstallation should be a null operation</li>
</ul>
<br>
<h2>Basic uninstallation</h2>
The basic uninstallation procedure is the following.<br>
<h4>1. pre-uninstallation steps</h4>
Destroy any resources used by the component, with the components itself still being installed. This might involve:<br>
<ul>
<li>destroying databases</li>
<li>reverting configuration changes to external resources made in during post-installation setup</li>
</ul>
Assumptions:<br>
<ul>
<li>this is the inverse of the post-installation setup procedure</li>
</ul>
<h4>2. uninstall the component</h4>
Remove the components files from the filesystem.<br>
<br>
<h2>Upgrading</h2>
TODO: detail the upgrading procedure<br>
<br>
<h1>Provisions in the build environment</h1>
For the above goals to be met, the following structure is needed for each component in the build environment:<br>
<br>
<pre>componentX<br>|-- configure<br>|-- bin<br>| |-- autogen.sh<br>| |-- postInstall.sh<br>| `-- preUninstall.sh<br>`-- etc<br> |-- acinclude.m4<br> |-- configure.ac<br> `-- Makefile.in<br></pre>
<h2>Considerations about specific installation steps</h2>
<h4>1. &nbsp;setting up the sources</h4>
none: this step is external to the package.<br>
<h4>2. configuring the sources</h4>
Assumptions:
<ul>
<li>don't assume that the directory prefixes supplied to <code>configure</code> will be the final installation directories for the component</li>
<li>don't assume that the machine used for compilation will be the same machine the tool is used on (think binary package building)</li>
</ul>
<h4>3. compile the sources</h4>
Assumptions:<br>
<ul>
<li>No hard-coded references should be made to any resources the component depends on. For example:</li>
<ul>
<li>don't hard-code shared library paths that are being linked to</li>
<li>don't hard-code PHP include paths that are referenced</li>
<li>don't hard-code paths that were supplied to configure</li>
</ul>
</ul>
<h4>4. install the component</h4>
When using package managers, this step is usually two-fold:<br>
<ul>
<li><code>make install</code> is executed, with <code>${prefix}</code> and other variables overwritten, so that the package is installed into a temporary directory</li>
<li>the files installed by the call to <code>make install</code> will be copied to their true target location when the package build based on them is installed on a target system</li>
</ul>
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).<br>
<br>
Assumptions:<br>
<ul>
<li><code>make install</code> really should just copy files, and neither do, nor assume anything more than that.</li>
<li><code>make install</code> should also copy all files needed to perform the post-installation setup and pre-uninstall steps.</li>
</ul>
<h4>5. post-installation setup</h4>
The <code>bin/postInstall.sh</code> 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.<br>
<br>
Assumptions:<br>
<ul>
<li>only files that were installed by <code>make install</code> can be used to perform the post-installation setup</li>
</ul>
<h2>Considerations about specific uninstallation steps</h2>
<h4>1. pre-uninstallation steps</h4>
The <code>bin/preUninstall.sh</code> 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.<br>
<br>
Assumptions:<br>
<ul>
<li>only files that were installed by <code>make install</code> can be used to perform the pre-uninstallation step</li>
</ul>
<h4>2. uninstall the component</h4>
none: this step is external to the package<br>
</body>
</html>