Distribution Policy
	Support and Keeping in Touch
	General Notes and System Requirements
	Starlink Software Store - Latest News
	Introduction - Using the Software Store
	Starlink Software Available for Download on the Store
	Starlink Software Request Forms
	Starlink Software `Built' Distribution
	Starlink Software `Built' Files
	Starlink Software `Source' Distribution
	Starlink Software `Source' Files
	Starlink Source Directories
	The star_build script
	Starlink Standard Makefiles

1. Obtain the shell archive file, by selecting an item from one of the four lists of available software (Libraries, Applications, Utilities and Information) and submitting the resultant Starlink Software Request form(s). The archive file will be returned as a document with a content type of application/octet-stream. Save the file in a convenient place. Browsers will normally default to saving application/octet-stream documents onto disk - if yours does not, configure it appropriately. If the shell archive file download works for you then you can skip to stage 2 below, ignoring the information on downloading via ftp.
   

   Download via ftp

   The WWW can be unreliable for downloading some of the larger items in the Starlink Software Store (up to 200Mb). Furthermore, on Linux there is a problem with unpacking the shell archives produced by the Software Store which can give the error "xmalloc: execute_cmd.c:510: cannot allocate 159771854 bytes (0 bytes allocated)", this is due to a bug in Bourne shell ('sh' or 'bash'). You may be able to use the 'ash' shell in place of Bourne shell to unpack the archive.

   An alternative but more labour-intensive method has been set up. The individual files which are packaged up by the Software Store shell archive file can be obtained separately using anonymous ftp. To obtain a list of ftp links to the required files in the Software Store and instructions on how to build/install them, substitute the name of the software item you want for PKG in the following URL:

   http://www.starlink.ac.uk/cgi-store/ftpform1?PKG

   You will first be asked to submit a form specifying the Software Store format you require.

   The software item name can be found by looking at the four lists of available software (Libraries, Applications, Utilities and Information). An example from the first item in the Libraries list (AGI, Applications Graphics Interface) would look like, http://www.starlink.ac.uk/cgi-store/ftpform1?AGI. PKG can be upper or lower case.

2. Execute the archive file using the Bourne shell or 'ash', for example:

              % sh {archive_name}
             

              % ash {archive_name}
             

   where {archive_name} is the name of the saved file. The 'ash' shell should be used under Linux if you experience trouble with Bourne shell ('sh' or 'bash'), such as out of memory errors. Executing the archive file will unpack it into a special source directory and subdirectories of it. It will then, optionally or automatically, proceed with Stage 3.

3. For each required item:

   	Ensure that the source subdirectory for the item contains a `built' system (by building it if necessary).
   	`Install' the built files in subdirectories bin, lib, etc... of a directory designated as the top-level Starlink software directory. At Starlink sites this directory is /star.

	Type 1: Primarily for software libraries or simple applications or utilities, these offer a choice of format (source or built etc. depending upon what is available) and a list of any subsidiary Starlink Software Items which will be required to use the requested item. The user can choose not to take the subsidiary items if, for instance, they have already been obtained.
	Type 2: Offers the choice of format for larger applications which are more likely to be obtained in the ready-built state and thus not require all the libraries etc. which would be required to build them. They may however require some subsidiary Starlink Software Items in order to run.
	Type 2a: If a type 2 item requires any subsidiary items at runtime, or if 'Source only' format is requested and it requires other items to build, a type 2a form is returned when the type 2 form is submitted. This new form is similar to the type 1 but restricts the available formats of subsidiary items to those which are sensible given the choice for the main item.

The built systems are available with or without source for:

	Alpha_OSF/1
	Solaris
	Linux

All packages are available `without source' and some also `with source'. A `with source' distribution will also contain pkg_source.tar, the source tar file for the package.

	Object libraries and, for appropriate platforms, shareable libraries. There are often different versions for use stand-alone (libpkg.a, libpkg.so) or with ADAM (libpkg_adam.a, libpkg_adam.so).
	Public Fortran INCLUDE files and C header files (pkg_par, pkg_err, pkg.h etc.)
	Scripts used to specify the required libraries at link-time. (pkg_link and pkg_link_adam).
	A script used to produce links to the Fortran INCLUDE files (pkg_dev).
	A file containing messages associated with error codes for this package. (fac_???_err - where ??? is some number).

	Application programs and scripts.
	ADAM Interface Modules.
	Startup shell scripts for the package.
	ICL startup scripts for the package.
	Help files.
	Data files etc.
	Demonstrations.

Having unpacked the shell archive, you should have the following files in your top-level Starlink source directory.

	README -- Instructions
	star_build -- A procedure to check and, if necessary, build and/or install a Starlink Software Item and all the items it depends upon.
	pkg_needs -- A list (possibly empty) of the items needed to build, install and use PKG.
	pkg_needs_run -- Where appropriate, a list of items required to install and use a ready-built version of PKG.
	Various subdirectories containing compressed tar files for the required Starlink Software Items. Each subdirectory has the name of the item in lower case.

Back to Index

Purpose:

Check and, if necessary, build and/or install a Starlink Software Item and all the other items required by it. It is also possible to execute certain targets of the Starlink Standard Makefiles for the items.

Invocation:

% star_build item [level]

item

is the name of the item (case independent).

level

optional, indicates the function to be performed.

	1 (default) Build a complete system.
	2 Build a subdirectory.
	deinstall - `deinstall' item and its subsidiaries.
	clean - `clean' the source directories of item and its subsidiaries.
	unbuild - `unbuild' item and its subsidiaries.
	check - `check' the state of item and its subsidiaries.

Description:

It is assumed that the current directory contains:

1. File pkg_needs (where pkg is the lower case of the item name), containing a list (possibly null) of the items needed to build or use item.
2. Where applicable, file pkg_needs_run containing a list of the items needed by item at run time.
3. Subdirectories, one for each of the items needed by item which are required to be built/installed.

If level is 1 or not present, all the items needed by item and then item itself will be checked and built and/or installed if necessary. star_build will obtain values for the environment variables INSTALL, STARLINK and SYSTEM (used by Starlink Standard Makefiles ) by prompting the user as required. Suitable suggested values will be offered and the chosen values saved for use as suggested values in subsequent invocations. Level 2 of star_build is then called for each of the items listed in the pkg_needs file and any pkg_needs_run file and, finally, for item itself.

If level is 2, star_build has been called from level 1 to build/install the named item. Level 2 must not be specified directly by users as it assumes that all required environment variables have been set.

If the subdirectory corresponding with the named item contains a Starlink export compressed tar file, it is assumed that a new version of the item has been obtained unless the directory also contains a .BUILT file which is newer. (Any .BUILT file extracted from the tar file is touched to flag the extraction.) If there is a new version, any existing version is deinstalled and unbuilt and the new version extracted and built and/or installed in its place.

If level is one of the other permitted values, values for INSTALL and STARLINK are found as for level 1 and if they are the same, make is performed on the specified target for any dependencies listed in the pkg_needs and/or pkg_needs_run file, and then for item itself. If INSTALL and STARLINK are different, only item itself is processed.

Item HTX is treated as a special case and handled last as it may be required to deinstall any of the other items.

	build - Build the libraries and executables etc. in the source directory.
	install - Install items beneath a top-level directory defined by the macro INSTALL.
	test - Run an installation test.
	clean - Remove intermediate files used in the build.
	deinstall - De-install the software from the INSTALL hierarchy.
	unbuild - Remove built files from the source directory.
	check - Report on current build/installation status.
	export_source - Produce a compressed tar file of all the source files.
	export - Produce a compressed tar file of the 'built' system together with the source.
	export_run - Produce a compressed tar file of the 'built' system without the source.

	/bin - to hold executables - applications often have their own subdirectories.
	/dates - to hold build date_stamp files
	/docs - to hold Starlink documents. Where hypertext versions of the documents are available, they will be linked, using the Starlink HTX system, to other Starlink documents, locally-held versions in preference but, failing that, via the Starlink document server to versions held at RAL.
	/etc - to hold miscellaneous files.
	/help - to hold help files and error messages - applications often have their own subdirectories.
	/include - to hold public Fortran INCLUDE files and C header files
	/lib - to hold subroutine object libraries.

	pkg.tar.Z (export_source).
	pkg_system.tar.Z (export built for system system).
	pkg_system_run.tar.Z (export_run built for system system).

Back to Index

Alan Chipperfield, Starlink, ajc@star.rl.ac.uk

Stephen Rankin, Starlink, ser@star.rl.ac.uk

24 12 2004