CCP4 web logo CCP4i: Graphical User Interface
Installing New Task Interfaces

next button previous button

Introduction - Installation Options

Installing New Task Interfaces
Installation area: "main" versus "private" CCP4i areas
Automatic versus customised installation
Task Archive Files

Reviewing and Uninstalling Tasks

Exporting Tasks

Task Archive File Contents
CCP4i Packages Files
Install Scripts

Command Line Installation and Uninstallation

Introduction - Installation options

The installation window gives three options:

Install a new task
Installs new task interface files from a task archive file
Uninstall an existing task
Removes the files for a task interface which have previously been installed using the install procedure.
This option also lets you review the files that have been installed for each task, without performing the uninstallation
Export a task
For interface developers Create a task archive file which can be installed by other users

Installing New Task Interfaces

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.

Installation area: "main" versus "private" CCP4i areas

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.

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.

There may be additional files which CCP4i uses when installing the task

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

File TypeFile ExtensionSubdirectory
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).

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:

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

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

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.

next button previous button