This document describes the installation procedures used by the components of the Campcaster 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:
don’t assume that the directory prefixes supplied to configure will be the final installation directories for the component
don’t assume that the machine used for compilation will be the same machine the tool is used on (think binary package building)
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:
create and customize configuration files
setup & configure external resources, like:
database tables
update configuration files of other tools used by this component
Assumptions:
don’t assume that the component has been built (compiled) on the same system as the one doing post-installation setup.
running this step and pre-uninstallation should be a null operation
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:
destroying databases
reverting configuration changes to external resources made in during post-installation setup
Assumptions:
this is the inverse of the post-installation setup procedure
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:
don’t assume that the directory prefixes supplied to configure will be the final installation directories for the component
don’t assume that the machine used for compilation will be the same machine the tool is used on (think binary package building)
3. compile the sources
Assumptions:
No hard-coded references should be made to any resources the component depends on. For example:
don’t hard-code shared library paths that are being linked to
don’t hard-code PHP include paths that are referenced
don’t hard-code paths that were supplied to configure
4. install the component
When using package managers, this step is usually two-fold:
make install is executed, with ${prefix} and other variables overwritten, so that the package is installed into a temporary directory
the files installed by the call to make install will be copied to their true target location when the package build based on them is installed on a target system
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:
make install really should just copy files, and neither do, nor assume anything more than that.
make install should also copy all files needed to perform the post-installation setup and pre-uninstall steps.
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:
only files that were installed by make install can be used to perform the post-installation setup
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:
only files that were installed by make install can be used to perform the pre-uninstallation step