SSN/78.1

Starlink Project
Starlink System Note 78.1

Norman Gray, Peter W Draper, Mark B Taylor, Steven E Rankin

11 April 2005

Copyright 2004-5, Council for the Central Laboratory of the Research Councils
Copyright 2007, Particle Physics and Astronomy Research Council
Copyright 2007, Science and Technology Facilities Council

The Starlink Build System


Abstract

This document provides an introduction to the Starlink build system. It describes how to use the Starlink versions of the GNU autotools (autoconf, automake and libtool), how to build the software set from a checkout, how to add and configure new components, and acts as a reference manual for the Starlink-specific autoconf macros and Starlink automake features.

It does not describe the management of the CVS repository in detail, nor any other source maintainance patterns.

It should be read in conjunction with the detailed build instructions in the README file at the top of the source tree (which takes precedence over any instructions in this document, though there should be no major disagreements), and with sun248, which additionally includes platform-specific notes.

Contents

1 Introduction
 1.1 Quick entry-points
2 Tools
 2.1 Overview of the Autotools
  2.1.1 Autoconf
   2.1.1.1 M4 syntax and traps
  2.1.2 Automake
  2.1.3 Libtool
  2.1.4 Autoreconf: why you don’t need to know about aclocal
  2.1.5 Running ./configure
 2.2 Starconf, and the Starlink autoconf macros
  2.2.1 STARCONF_DEFAULT_PREFIX and STARCONF_DEFAULT_STARLINK
  2.2.2 Components
  2.2.3 File templates
  2.2.4 The format of the component.xml file
 2.3 Version numbers
 2.4 A few remarks on state
 2.5 Preprocessable Fortran
 2.6 Using the Starlink CVS repository
 2.7 CVS
  2.7.1 CVS and tagging
  2.7.2 CVS and recursion – checking out only a subtree
3 Building applications and libraries
 3.1 The top-level Makefile
 3.2 Bootstrapping and building the entire tree
 3.3 Building a single component
 3.4 Building monoliths
 3.5 Bootstrapping without building: configuring starconf and the autotools
4 Incorporating a package into the Starlink build system
 4.1 Autoconfing a library
 4.2 The build system ‘interface’
 4.3 Distribution of components
  4.3.1 Making a distribution
   4.3.1.1 A distribution from the complete tree
   4.3.1.2 Distributing a single component
 4.4 Regression tests
 4.5 Importing third-party sources
  4.5.1 Configuring m4
  4.5.2 Configuring CFITSIO
  4.5.3 Configuring tcl
  4.5.4 Time order of third-party sources
 4.6 Documentation
  4.6.1 Components containing only documentation
 4.7 Adding components: the final step
5 FAQs
 5.1 General FAQs
 5.2 Installation FAQs
 5.3 State FAQs
6 Miscellaneous hints and tips
 6.1 Forcing automake’s choice of linking language
 6.2 Conditionally building components, I
 6.3 Conditionally Building Components, II
 6.4 Manipulating compiler and linker flags
A The Starconf macros and variables
 A.1 AC_FC_CHECK_HEADERS
 A.2 AC_FC_CHECK_INTRINSICS
 A.3 AC_FC_HAVE_BOZ
 A.4 AC_FC_HAVE_OLD_TYPELESS_BOZ
 A.5 AC_FC_HAVE_PERCENTLOC
 A.6 AC_FC_HAVE_PERCENTVAL
 A.7 AC_FC_HAVE_TYPELESS_BOZ
 A.8 AC_FC_HAVE_VOLATILE
 A.9 AC_FC_LITERAL_BACKSLASH
 A.10 AC_FC_OPEN_SPECIFIERS
 A.11 AC_FC_RECL_UNIT
 A.12 AC_PROG_FC
 A.13 AC_PROG_FPP
 A.14 STAR_CHECK_PROGS
 A.15 STAR_CNF_BLANK_COMMON
 A.16 STAR_CNF_COMPATIBLE_SYMBOLS
 A.17 STAR_DECLARE_DEPENDENCIES
 A.18 STAR_DEFAULTS
 A.19 STAR_INITIALISE_FORTRAN_RTL
 A.20 STAR_LARGEFILE_SUPPORT
 A.21 STAR_LATEX_DOCUMENTATION
 A.22 Variable STAR_MANIFEST_DIR
 A.23 STAR_MESSGEN
 A.24 STAR_MONOLITHS
 A.25 STAR_PATH_TCLTK
 A.26 STAR_PLATFORM_SOURCES
 A.27 STAR_PREDIST_SOURCES
 A.28 STAR_PRM_COMPATIBLE_SYMBOLS
 A.29 STAR_SPECIAL_INSTALL_COMMAND
 A.30 STAR_SUPPRESS_BUILD_IF
 A.31 STAR_XML_DOCUMENTATION
 A.32 starxxx_DATA – special installation directories
 A.33 Obsolete macros
  A.33.1 AC_F77_HAVE_OPEN_READONLY
  A.33.2 STAR_DOCS_FILES and friends
  A.33.3 STAR_FC_LIBRARY_LDFLAGS
  A.33.4 STAR_HAVE_FC_OPEN_READONLY
B The relationship with the GNU autotools
C Possible future changes