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.

Automatic versus customised installation

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.

Task Archive Files

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.

Reviewing and Uninstalling Tasks

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.

Exporting Tasks

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.

Task Archive File Contents

This information should be of interest to developers.

The distribution may contain files with the following extensions, which will normally be installed in the following directories:

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).

CCP4i Packages Files

The CCP4i packages file ccp4i_packages.def in a task archive contains additional information about the new task which is used in installation:

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
endif

Command Line Installation and Uninstallation

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.