CCP4i: Graphical User Interface | |
Installing New Task Interfaces |
Introduction - Installation Options
Reviewing and Uninstalling Tasks
Command Line Installation and Uninstallation
The installation window gives three options:
CCP4 may occasionally distribute the necessary code for an individual task interface between full releases. Non-CCP4 programs may also have CCP4i interfaces which are distributed independently of the CCP4 suite. These should be distributed as compressed .tar files which are referred to as task archives, and there is a tool to install them at the bottom of the Systems Admin menu, on the right hand side of the main window.
Using this tool you should be able to do an automatic installation - only needing to select the task source file and then hit the Apply button to install the necessary files. A record is kept of the installation and so that it is easy to uninstall previously installed tasks.
All the distributed code for CCP4i resides in the directory pointed to by the $CCP4I_TOP environment variable. This is referred to as the main CCP4i area. Files placed in this area will be accessible by all CCP4i users, so installing new interfaces here will make them available to everyone.
However, each user also has a ``private'' CCP4i area, which resides in the directory $USER/.CCP4. This area contains files which are specific only to the individual user (for example, their preferences). It also contains a copy of the main CCP4i directory structure (but not copies of the files).
Installing new task interfaces to this area means that only that user will be able to access them. Also, a version of the task interface installed here will be used in preference to any in the main CCP4i area.
The installation tool will read the task archive file and determine what files should be installed in which subdirectories. Choosing an automatic installation simply installs the files in the appropriate places and adds the new tasks to the modules file without an further user intervention. This is the recommended method.
Alternatively a customised installation can be performed. The user can choose to omit files from the installation, prevent the running of any install script supplied with the taks, and can edit the task references which are to be added to the modules file. Alternatively it can be used as a way of reviewing what will be installed before proceeding with the full installation.
In both cases, the installation of each package is recorded in the CCP4i Packages File. This records key information which allows the package to be uninstalled in future.
The task archive file is a compressed archive file (file extension .tar.gz) containing all the files which are needed for the new interface. This file should have been prepared by whoever wrote the new interface.
The installation procedure should automatically unpack this file, in order to examine its contents and to perform the install. (The install should also work if the archive ``file'' is actually the unpacked directory.)
Details of the contents of the task archive file can found below.
Once a task has been installed it is easy to remove it again using the uninstall option. You may wish to do this for example if you have previously installed the task in your ``private'' CCP4i area (see the information on Installation areas for a detailed explanation).
The uninstall is completely automatic. Simply select the name of the task package that you want to uninstall - the window will update to show the associated files for that package, and any task references which were also installed. Clicking the "Apply" button will then remove all the files and task references, and will restore any backup files that it finds.
This utility is intended for interface developers, and allows them to create a task archive file for a new task by selecting the files to be included, and the task references that should be installed. It also allows the specification of attributes such as the version number of the task, and an install script - see the information on Task Archive File Contents.
This information should be of interest to developers.
There may be additional files which CCP4i uses when installing the taskThe distribution may contain files with the following extensions, which will normally be installed in the following directories:
File Type | File Extension | Subdirectory |
---|---|---|
Task file | .def | $CCP4I_TOP/tasks |
Def file | .tcl | $CCP4I_TOP/tasks |
Script file | .script | $CCP4I_TOP/scipts |
Run/template file | .com | $CCP4I_TOP/templates |
Help file | .html | $CCP4I_HELP/extra |
There should also be a file called modules.def (or just modules, for older style task packages) which contains the task references to be added into the file $CCP4I_top/etc/modules.def. The task references define the buttons in the list of tasks in the main window, which are normally used to launch a task.
Normally the new task name will appear at the bottom of the list of tasks in the module menu on the left hand side of the main window. This may not be appropriate and you may need to use the Edit Modules File utility to change the order. (If the new task interface is intended to completely replace an existing task interface you may wish to delete the reference to the old task interface using this utility.)
Task archives created with the Export Task facility will also contain a CCP4i packages file (ccp4i_packages.def) which contains additional information about the task, for example the version number (if any).
The CCP4i packages file ccp4i_packages.def in a task archive contains additional information about the new task which is used in installation:
Attribute | Description | Comments |
---|---|---|
Package name | Identifier for the new task | Used to group together files and task references which define the new task interface, for review and uninstall purposes |
Package version | Version control string of the form a[.b[.c]] | Not compulsory but recommended. You cannot install an older version of a task over a newer version - in these cases you will need to uninstall the existing version first. |
Install script | Script supplied by the task author which will be run before the installation is allowed to proceed. | See the section on Install Scripts. |
Some task archives may include an install script. This is a small script supplied by the developer of the new task, which will be run automatically prior to the installation being performed.
The install script should perform any necessary checks on the system, to make sure that the task interface will work once it is installed - for example, if the new task runs a program called my_prog then the install script should check that my_prog is installed.
Install scripts are not compulsory - for most tasks it is not expected that they will be necessary.
A simple example of an install script in C-shell is:
#!/bin/csh # Check that new_prog is in CBIN if (-e ${CBIN}/new_prog) then # new_prog was found - exit normally exit 0 else # new_prog was not found - print a message and # exit with non-zero status echo "new_prog not found" echo "Install new_prog before installing this interface" exit 1 endifIf the install script returns a non-zero exit status then the installation procedure will display the message from the script and then halt the install.
It is possible to perform the installation or uninstallation of a task automatically from the command line, using the -install and -uninstall options of ccp4ish.
These options are intended for developers of third-party software, to incorporate into their own installation procedures - for example, in a Makefile the install and uninstall targets could include (un)installation of the new interface for that software.
Since the command line procedures are completely automatic, it is important that the task archive has been produced using the Export Task function.