167 lines
6.7 KiB
HTML
167 lines
6.7 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>Component Installation Guidelines</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/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. 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 <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 & 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. 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>
|