Last modified: Fri Jun 12 18:24:30 BST 2009
Nick West
The diagram below illustrates the key features.
To install on some remote site the user specifies the target machine and the software application to be installed. RSD assembles a script with this information together with the URL of the web directory and submits it.
RSD supports recursive installation, that is to say an application's list of components can include other supporting applications that are to be installed, if necessary, before installing its own component libraries.
If the process completes successfully then the application is considered to be installed. If the installation of any library or supporting application fails, installation terminates. In either case all the installation logs are returned to the launch site for examination. After fixing up any problems the installation job can be run again and, RSD attempts a validation before installation of each library, any libraries that were successfully installed before will not be reinstalled.
If running in a GRID environment, RSD uses lcg-ManageVOTag to maintain software tags.
When installing and removing software the user can designate the required platform using the --platform option, and if this fails to match the host platform RSD terminates. This will prevent an RSD job accidentally running on the wrong platform and acting on the wrong application build.
build_config_table.datHowever for rolling software this leads to a steadily growing table plus management overhead switching users to new versions and removing old versions. To reduce this burden RSD has two features, described below.
# To support "rolling software", where new versions come out frequently # but follow the same build, the application version number can be # replaced a perl wild-card expression. When a match is found any # character * in the associated library list by the matching version. # For example:- # # Application:grid_tools:V.*-build_1 # grid_tools:* # # Will match: Application:grid_tools:V01-16-07-build_1 # and will associate library list: grid-tools:V01-16-07 # # This avoids having to update this file each time a new version comes out. # # Note that:- # # 1) .* means any character string. # Another example: V\d\d-\d\d-\d\d also matches (\d - any digit) # # 2) The version number has to be terminated by the string '-build' # # 3) Exact match takes priority over wild-card match. # # 4) If there are multiple matches the association is ambiguous, so fails.
The normal sequence of events is as follows:-
--soft_link=ver{:delete}
where ver is one of
new Make installing version new-XXX
pro Make installing version pro-XXX and move previous pro-XXX to old-XXX
Also make installing version new-XXX if higher than existing new-XXX
old Make installing version old-XXX
If :delete specified any version that was pointed to by a soft
link before the change, but no longer is, will be deleted.
The normal sequence of events is to install an application twice:-
{global options} command {command options} {command args}
--build_config_table=<file>
Supply build configuration table instead of using the built-in one.
Caution: launch command does not propagate file or command to use it.
Only use with launch if
add --install_global_option=--build_config_table=<file>
<file> is visible at install site
--debug=<level> Set debug to required level (1, 2 or 3) [Default:0]
--download_method={cp|wget}
Select tar file download method
wget [Default]
cp (useful when running RSD locally without web visible dirs)
--expt=<experiment> To change from the default experiment
--http_proxy=<proxy> To select a non-standard proxy for wget when installing
--log_file=<file> Write log output to this file. [Default:/dev/stdout]
--max_safe_purge_frac=<f> Maximum fraction of unused libraries safe be purge [Default 0.2]
--upload_method={cp|scp}
Select assembled tar file upload method
scp [Default]
cp (useful when running RSD locally without web visible dirs)
none Don't upload, just assemble
--web_url=<url> Specify an alternative web URL.
--work_dir=<dir> Write temporary data to this directory. [Default:./]
assemble <library>:<version>
Options:-
--web_account=user@host (not used if --upload_method=cp)
--web_dir=directory
--use_local ROOT only: Use current ROOTSYS
The assemble command is used to build a tar file (normally of source
code) for a selected version of a library and upload it onto the web
visible directory. Uploading uses scp command. The
--web_account option can be used to control the remote account and
host used and --web_dir the directory.In the case of ROOT, the option --use_local can be used to create a tar from the currently defined ROOTSYS, which is useful when an "off-tag" version is required.
There is a Naming Convention for libraries and versions and the configuration file
build_config_table.datlists the libraries and supporting applications that are required for each application.
install <top-dir> <application>:<version>
Options:-
--force Force reloading of tar file and skip pre-install validating
--install_log=<file> Collect all the installation logs and return a single .tar.gz in <file>
--no_survey Don't perform end of install software survey
--platform=<platform> Required platform. One of SL3 [default], SL4
--soft_link=ver{:delete}
Add soft link and optionally delete obsolete versions.
NB Actual soft links will be made platform specific e.g. pro-SL4
Will bypass install entirely if application exists and not --force.
See Soft Link Support
--validate_only Don't install, just validate.
The install command steers the installation of specified version of a
selected application into the specified top level directory which must
be given as in absolute NOT relative form as RSD doesn't normally use
the same working directory as its user. For a list of applications RSD
can install see the configuration file.
build_config_table.dat
By default, before installing each library, RSD runs a validation check and skips installation if it passes. This saves time if attempting to complete an installation that had earlier failed part way through. The --force option can be used to force all libraries to reinstall from scratch. The option is not propagated through to any supporting application.
Normally you don't run the install command directly but instead run the launch command that runs the install command on a remote machine and there RSD supplies a --install_log option so that all the individual library log files are returned as a single gzipped tar file.
The --validate_only option is useful if you just want to check that an application is O.K., but don't want to install, even if it isn't. This option is propagated through to any supporting application.
launch <target> <application>:<version>
<target> is one of:-
self:<sw_dir> Install locally using sw_dir as top level directory
e.g. self:/data/minos/minos2/west/rsd_tests
lcg:<queue> Install on LCG queue.
e.g. lcg:lcgce02.gridpp.rl.ac.uk:2119/jobmanager-lcgpbs-minosL
Assumes LCG env. var. $VO_<expt>_SW_DIR will be set there.
lcg:<queue>:<sw_dir> Install on LCG queue into specified directory.
e.g. lcg:lcgce02.gridpp.rl.ac.uk:2119/jobmanager-lcgpbs-minosL:/stage/minos-data1/software/grid
pbs:<sw_dir> Install using PBS (via Ganga)
e.g. pbs:/stage/minos-data1/software/grid
pbs-<queue>:<sw_dir> As pbs:<sw_dir> but to a specific queue rather than the default.
e.g. pbs-prod4:/stage/minos-data1/software/grid
Options:-
--install_global_option=<install option> Pass global option to installer
e.g. --install_global_option=--debug=1
--install_command_option=<install option> Pass command option to installer
e.g. --install_command_option=--force
--remove Run remove job rather than install job
The launch job is used to generate a job to run the install (or
remove) command on a target machine. The <target> argument
determines the location of the target machine. For testing purposes it
can designate a self target and specify the top-level directory under
which to install. Currently the only other type of target is an LCG GRID
host and the queue must correspond to one in the
lcg-infosites --vo <experiment> ce
list.The --install_global_option and --install_command_option can be used to add global and command arguments respectively to the install command.
The --remove option is used to completely remove all the constituent libraries of an application. There are no safety checks, you have been warned!! Supporting applications are not removed.
rsd lib_list minossoft:S08-03-20-R1-28-build_1
remove <top-dir> <application>:<version>
Options:-
--install_log=<file> Collect all the deinstallation logs and return a single .tar.gz in <file>
--platform=<platform> Required platform. One of SL3 [default], SL4
De-install a complete set of libraries on target site
below <top-dir>. As with the install,
you don't this normally issue this command directly but rather
indirectly when you use the launch --remove
command. Supporting applications are not removed.
This command is used to run tests on RSD itself. Currently, there is only valid command argument.
test replace_sw_tag
bash: source $SRT_PUBLIC_CONTEXT/GridTools/Scripts/setup/setup_minos_lcg_grid.sh
csh: setenv MOG_TOOLS $SRT_PUBLIC_CONTEXT/GridTools
source $SRT_PUBLIC_CONTEXT/GridTools/Scripts/setup/setup_minos_lcg_grid.csh
The rather odd name reflects the fact that RSD is a tool developed for
the LHC Computing Grid.To install RSD, which is part of GridTools, on other sites see Installing GridTools and follow steps 1 to 3.
grep "App:" $RSD_HOME/libs_and_builds/build_config_table.dat | cut -f1 -d ' 'All that RSD needs to install an application is a top level directory under which to install any/all applications. For example to install application XXX:YYY-build_1 (e.g. minossoft:R2.0.1-build_1) under /minos/scratch/nwest:-
my_top_dir=/minos/scratch/nwest (not required; just for convenience) rsd install $my_top_dir XXX:YYY-build_1If the install fails you can check the log of the library that failed to install by looking below the top directory ($my_top_dir in our case) for the file:-
$my_top_dir/rsd/<library-name>-*/rsd_admin/install.logOnce the installation has completed the environment can be set up with:-
source $my_top_dir/apps/XXX/YYY-build_1-<platform>/setup_library/setup_XXX.bash or .csh where <platform> = e.g. SL4
my_top_dir=/minos/scratch/nwestInstallation of Minossoft is complicated by the fact that Minossoft requires the separate application BFieldMap; it was kept separate so that it can be updated without having to rebuild Minossoft and can be shared between different releases of Minossoft. Trying:-
grep "App:" $RSD_HOME/libs_and_builds/build_config_table.dat | cut -f1 -d ' 'gives
App:BFieldMap:.*-build_1means that this is Rolling Software so that new versions can be added and old ones removed with new/pro/old soft links moving forward. However, to install a specific version we need the latest BFieldMap which can be found by looking in the afs area
ls -l /afs/fnal.gov/files/data/minos/d160/remote_software_deployment/bfieldmap*at the time of writing this the latest was
bfieldmap-2008-02-08.tar.gzTo install it:-
rsd install $my_top_dir --soft_link=pro:delete BFieldMap:2008-02-08-build_1The --soft_link=pro:delete option forces the installed application to have a 'pro' soft - something that the Minossoft installation requires.
Now you are ready to install Minossoft e.g.:-
rsd install $my_top_dir minossoft:R2.0.1-build_1As part of the installation procedure a loon job is run to validate the build and for this the database environmental variables need to be provided. The installation script has hardwired sets for certain locations, e.g. FNAL, but if installing at other sites define the ENV_TSQL_* before running RSD so that it will pick up your values.
Once the installation has completed the environment can be set up with:-
bash: source $my_top_dir/apps/minossoft/R2.0.1-build_1-SL4/setup_library/setup_minossoft.bash csh: source $my_top_dir/apps/minossoft/R2.0.1-build_1-SL4/setup_library/setup_minossoft.csh
It is also convenient to define an rsd alias (csh) or subroutine (sh/bash) as:-
perl -w $RSD_HOME/driver/rsd.pm
If you want to add new experiments or change the defaults that RSD assumes see Extending Experiment Support
RSD uses the Ganga job submission system for submitting jobs to the LCG GRID. If RSD cannot find Ganga it will fail. The environmental variable:-
GANGA_BINmust point to the Ganga executable so that RSD can locate it.
build_config_table.datHere is a typical entry:-
Application:geant4_vmc:R2.2-build_0 libsigc++:1.2.5 mysql:5.0.22 clhep:2.0.3.1 geant4:8.3 pythia:6.4.09 root:v5-15-08 geant4_vmc:v2-2 bfieldmap:2006-01-24 minossoft:S07-06-04-R1-25Application geant4_vmc:R2.2-build_0 is built from the 9 entries in software stack listed after it. Building begins with the first entry (libsigc++:1.2.5), followed by the second and so on. Once a library has been installed RSD makes it available for subsequent library installations which can then bind to it, for example by using the headers it provides. So the order of software stack denotes the library dependency.
<library name>-<library version>-<N>
where N = unique serial number 1, 2, ...
The library itself is held in:-
libs/<library name>-<library version>-<N>and the administration information, including the context in which the library is built, and all build products stored external to the library itself are held in:-
rsd/<library name>-<library version>-<N>
Caution: Care must be taken with any soft links created during installation as they will be moved once the library build is complete and some relative ones might break. Soft links should only be one of the following:-
minossoft -> minossoft-R1.24
It is the responsibility of the writer of the installing script to ensure that this rule is observed.
Suppose there are two independent libraries A and B and that libraries C, D, E, and F can be used with either of both. Further assume that the software stacks are ordered as follows:-
C D E F B A A B A BThis will result in both A and B being built twice, once in the context of no supporting libraries and then again in the context of the other as a supporting library. The solution is to be consistent in the ordering and include the library even if not needed, for example:-
C D E F B B B B A A A ANow A and B are only built once, A in the context of no supporting libraries and B in the (spurious) context of supporting library A. To ensure consistency the combination of these two libraries could be called a supporting application of some type and then that application could just be included in the application in the software stacks for C, D, E, and F.
Environment Directory Notes
variable
HOME .../ Holds global log files
install_<application_id>_install_logs.tar.gz (individual install logs)
RSD_SW_DIR /
...apps/ Applications area
. ...app name/ e.g. minossoft/
RSD_TOP_DIR . ...app ver/ platform specific version e.g. R.1.20-build_1-SL3/
. . May be a rolling software soft link Contains 'installed_libraries' .
. ...xxx/ Where xxx = build product subdirectories e.g. bin, include, lib.
. . Contents are all soft links to ../../../../rsd/*/xxx
. ...lib file ID/ Form: <name>-<ver> e.g. root-v5-14-00b.
. . Soft link to ../../../../libs/<name>-<ver>-<build number>
. . e.g. ../../../../libs/root-v5-14-00-0
. ...setup_library/ Recommended area for setup scripts (or soft links to them)
. Naming convention setup_<lib name>.sh/.csh e.g. setup_root.csh
.
...libs/ Library build area
. ...lib build ID/ Form: <name>-<ver>-<build number>/ Library build ID
. e.g. root:v5-12-00-0
. Contains unwound library tar file and any internal build products
.
...rsd/ RSD admin area
. ...lib build ID/ RSD data associated with corresponding library in libs/
. ...xxx/ Where xxx = build product including subdirectories e.g. bin, include, lib.
. ...rsd_admin/ RSD adim dir with:-
. <name>-<ver>.tar.gz Tar file
. install.log Build log
. install.wlog wget log
. install.sh Install script wrapper
. install.status One line install status. If in error, will start with '?'
. install.context One line build context e.g. libsigc++:1.2.5 mysql:5.0.22
. install.date One line build date e.g. Mon Jun 18 14:18:56 BST 2007
.
RSD_HOME ...rsd_home/ The RSD code
...config/ Experiment specific configuration files.
...driver Generic (independent of supported software specifics) driver
...doc/ Documentation
...libs_and_builds/ Software specific scripts to configure and build
launch_[install|remove]_<application_id>.sh
$RSD_HOME/driver/initialise_globals.pm
| Variable | Meaning |
|---|---|
| RSD_DEBUG | Debug flag. Set to 1 for debug |
| RSD_LIBRARY_VERSION | Library version |
| RSD_LIB_STATUS_FILE | File used to communicate one-line exit message from script |
| RSD_LOG_FILE | RSD (top level) log file |
| RSD_PRINT | Print utility used to print to RSD_LOG_FILE RSD in order to maintain a consistent format with RSD driver entries. |
| RSD_RETURN | Utility to be sourced to return status. It takes 2 args:- 1) Return code (0 = success) 2) Message Example: . RSD_RETURN 1 "Failed to build library" |
| RSD_RUN | Utility to be sourced to execute a single script line The utility checks the result of execution and quits if it fails Example: . $RSD_RUN tar xzf $RSD_TAR_FILE |
| RSD_SITE_NAME | Generic site name. e.g. "ral_t1_ui" |
| RSD_TAR_FILE | Tar file |
| RSD_WORK_DIR | Empty work directory for use if required |
To provide good diagnostics, all scripts are expected to:-
Example
$RSD_PRINT "..Checking for msrt..."
Example
. $RSD_RETURN 0 "Ran minossoft tests O.K."
Example
. $RSD_RUN loon -b -q $RSD_PRINT "..Checking odbc. library exists" . $RSD_RUN ls -l lib/libodbc*.soThe second example shows a way to check that files exist - it's a good idea to precede these with a RSD_PRINT explaining the purpose.
Just look at
$RSD_HOME/libs_and_buildsfor examples using these helper scripts.
| Variable | Meaning |
|---|---|
| RSD_USE_LOCAL | =1 if --local sepcfied, ==0 otherwise Used when assembling ROOT to take ROOTSYS rather than CVS. |
| Variable | Meaning |
|---|---|
| HOME | Log in directory |
| RSD_HOME | Top level directory for RSD tools |
| RSD_LIB_BUILD_DIR | The directory where the installing library will eventually be placed |
| RSD_LIB_INSTALL_LOG_FILE | Library install log (create if installing, check is validating) |
| RSD_MODE | One of "installing" or "validating" |
| RSD_HOST_PLATFORM | Host platform e.g. SL3 |
| RSD_SW_DIR | The software top level directory (holds apps/, libs/ and rsd/) |
| RSD_TOP_DIR | The top level directory to install under It will be of the form: ../<application-name>/<application-version>/ |
| For each supporting library XXX (e.g. XXX = root) The character '+' is not permitted in environment names so is removed e.g. RSD_SUP_LIB_libsigc_VER=1.2.5 | |
| RSD_SUP_LIB_XXX_VER | Version number |
| RSD_SUP_LIB_XXX_DIR | Directory |
...apps/
...app name/
...app ver/
...setup_library/
The recommended name convention for the setup scripts for library XXX
(e.g. XXX = ROOT) is:-
setup_XXX.csh
setup_XXX.sh
It is also recommended that the install script starts by briefly
documenting if it produces a setup script and if so what it does.
It's also a good idea to list what supporting libraries it requires.
Fir example, take a look at:-
install_minossoftNow none of this is compulsory; RSD isn't going to police this rule. However it is a good idea that people who are supporting a library within the RSD framework have a standard place so that clients have a standard place to look.
| GRID Resource | Use |
|---|---|
| $VO_<experiment>_SW_DIR | Top-level directory for software installation See Directory Structure |
| $HOME/.BrokerInfo | Used to get the CE name. |
| $EDG_WL_LOG_DESTINATION | Used to get the CE name if unable to find .BrokerInfo. |
$RSD_HOME/libs_and_builds/assemble_XXX.sh $RSD_HOME/libs_and_builds/install_XXX.shThese scripts have to handle all the versions of library XXX. For examples, look at the scripts in
$RSD_HOME/libs_and_buildsand for more inforamtion on writing these scripts see the Library_Script API
$RSD_HOME/libs_and_builds/build_config_table.datReview the individual library assemble and install scripts to ensure that can handle any new versions.
$RSD_HOME/libs_and_builds/assemble_XXX.sh $RSD_HOME/libs_and_builds/install_XXX.sh
Now it is possible to override defaults at execution time by selecting the appropriate options, for example:-
--download_method={cp|wget}
Select tar file download method
wget [Default]
cp (useful when running RSD locally without web visible dirs)
--expt=<experiment> To change from the default experiment
--http_proxy=<proxy> To select a non-standard proxy for wget when installing
--web_url=<url> Specify an alternative web URL.
but it is tedious, not to mention error prone, to have to use such
options on a permanent basis and RSD has a configuration system to
eliminate this. All configuration material is held in the
subdirectory:-
config/Configuration depends on two elements:-
config/<experiment>.site_namewhich should contain a single line giving the host name. This file remains local to the site and is included in the .cvsignore list.
When RSD begins execution it attempts to locate the file:-
config/<experiment>-<host name>.config
e.g. config/minos-ral_t1_ui.config
and if successful, executes it. To see what can be changed look at:-
config/example.config
By creating additional files it is possible to configure RSD at your
sites.Note that it is not necessary to update the CVS Repository for RSD to use your configuration for remote installation. When you use the assemble command to create the tar file for RSD itself, it takes its material from your version of RSD (as pointed to by RSD_HOME) and it will be that version that will be used remotely. That's not to say that configuration files for other experiments are not welcome in the Repository, just email if you want something added.
Of course this system relies on you remembering that
--expt=<experiment>option, so is still error prone. To deal with this, add the file
config/.experiment
containing the name of your experiment and RSD will use this (although
--expt will still override). Also when running the launch
command, RSD will include the --expt option in the target
install command, so will insure that launching and installing
always use the same experiment regardless of whether the .experiment
file is present at the remote site.
build_config_table.datincludes at trivial application: test_rsd that is used for testing RSD itself.