The following macros may be used within the configure.ac file. Of these, only the STAR_DEFAULTS macro is
required to be in the file.
In the descriptions below, optional arguments are shown in square brackets, along with their default value. If
the sole argument is optional (for example in the case of STAR_DEFAULTS), you do not need to supply the
brackets.
The macros below ultimately do their work by expanding into shell script, and these results are exposed in
the ./configure file. Although it can occasionally be useful to examine these implementation
details, resist the temptation to write your configure.ac scripts based on what you find there. If
macro behaviour is not documented here, you should not rely on it. If you need to rely on it, then
consult with the starconf maintainer to have the documentation changed, and the behaviour thus
fixed.
AC_FC_CHECK_HEADERS(include-file...)
Fortran analogue of AC_CHECK_HEADERS, though it only takes the first argument, giving the list of include files to
check. For each include file, defines HAVE_include-file (in all capitals) if the include file is found. Respects the
current value of FCFLAGS.
AC_FC_CHECK_INTRINSICS (function...)
Like AC_CHECK_FUNCS, but instead determine the intrinsics available to the Fortran compiler. For each intrinsic in
the (whitespace-separated and case-insensitive) argument list, define HAVE_INTRINSIC_intrinsic if it is
available. For example, AC_FC_CHECK_INTRINSICS(sin) would define HAVE_INTRINSIC_SIN if the ‘sin’
intrinsic function were available (there are probably rather few Fortrans which don’t have this
function).
There are some functions, such as getcwd, getenv and chdir, which are provided as intrinsics by some Fortran
compilers, but which others supply as external routines in the Fortran runtime. To deal with this (exasperating)
situation, you need a construction like this in your configure.ac:
and then conditionalise on the defines HAVE_GETCWD and HAVE_INTRINSIC_GETCWD in your preprocessable code.
That is, you use the standard macro AC_CHECK_FUNCS, but wrapped in declarations which force
the check to use Fortran (this doesn’t work in standard autoconf, since the required support is
missing).
AC_FC_HAVE_BOZ
Test whether the FC compiler supports BOZ constants in the Fortran 95 style. These are integer constants written
in the format B’xxx’, O’xxx’ and Z’xxx’. If so set the preprocessor variable HAVE_BOZ to be 1. This should be
true of all Fortran 95, and later, compilers.
See also AC_FC_HAVE_TYPELESS_BOZ and AC_FC_HAVE_OLD_TYPELESS_BOZ.
AC_FC_HAVE_OLD_TYPELESS_BOZ
Test whether the Fortran compiler (FC) supports typeless BOZ constants in the OLD (VMS and g77)
Fortran style. These are constants written in the format ’xxx’X, which allow the initialisation of
any type to a specific bit pattern. If so set the preprocessor variable HAVE_OLD_TYPELESS_BOZ to be
1.
See also AC_FC_HAVE_BOZ and AC_FC_HAVE_TYPELESS_BOZ
AC_FC_HAVE_PERCENTLOC
Test whether the FC compiler has the %LOC extension. If so, define the preprocessor variable HAVE_PERCENTLOC to
be 1.
AC_FC_HAVE_PERCENTVAL
Test whether the FC compiler has the %VAL extension. If so, define the preprocessor variable HAVE_PERCENTVAL to
be 1.
AC_FC_HAVE_TYPELESS_BOZ
Test whether the Fortran compiler (FC) supports typeless BOZ constants in the Fortran 95 style. These are
constants written in the format X’xxx’ that allow the initialisation of any type of variable to a specific bit
pattern. If so set the preprocessor variable HAVE_TYPELESS_BOZ to be 1.
See also AC_FC_HAVE_BOZ and AC_FC_HAVE_OLD_TYPELESS_BOZ
AC_FC_HAVE_VOLATILE
Test whether the Fortran compiler (FC) supports the VOLATILE statement. VOLATILE is used to stop the
optimisation of a variable, so that it can be modified outside of the program itself. If supported the preprocessor
variable HAVE_VOLATILE is set to be 1.
AC_FC_LITERAL_BACKSLASH
Check whether the compiler regards the backslash character as an escape character. The backslash is not in the
Fortran character set, so ISO-1539 does not specify how this is to be interpreted, but many Unix Fortran
compilers interpret ’\n’, for example, as a newline, and ’ as a single backslash. Many Unix compilers have switches which allow you to choose between these two
modes.
’
This macro tests the behaviour of the currently selected compiler, and defines FC_LITERAL_BACKSLASH to 1 if
backslashes are treated literally – that is if ’\\’ is interpreted as a pair of backslashes and thus that ’\n’ is
interpreted as a pair of characters rather than a newline.
Note that, if you simply want to have a character constant which contains a single backslash, then the following initialisation will do that for you without any need for this macro (thanks to Peter Draper).
Fortran is required to truncate the initialising string without error, as noted in ISO-1539 sections 5.2.9 and 7.5.1.
AC_FC_OPEN_SPECIFIERS(specifier ...)
The Fortran OPEN statement is a rich source of portability problems, since there are numerous common
extensions which consiste of extra specifiers, several of which are useful when they are available. For each of the
specifiers in the (whitespace-separated) argument list, define HAVE_FC_OPEN_mungedspecifier if the specifier
may be given as argument to the OPEN statement. The mungedspecifier is the specifier converted
to uppercase and with all characters outside [a-zA-Z0-9_] deleted. Note that this may include
‘specifiers’ such as access=’append’ and [access=’sequential’,recl=1] (note quoting of comma)
to check combinations of specifiers. You may not include a space in the ‘specifier’, even quoted.
Each argument must be a maximum of 65 characters in length (to abide by Fortran 77 line-length
limits).
See Sec. 2.5 for an example of using this preprocessor definition in a Fortran program.
AC_FC_RECL_UNIT
When opening a file for direct access, you must specify the record length with the OPEN specifier RECL; however
in the case of unformatted direct access files, the units of this specifier are processor dependent, and may be
words or bytes. This macro determines the units and defines FC_RECL_UNIT to contain the number of bytes (1, 2,
4, 8, ...) in the processor’s unit of measurement.
Note that unformatted files are not themselves portable, and should only be used as either temporary files, or as data files which will be read by a program or library compiled with the same Fortran processor. With this macro, however, you can read and write such files in a portable way.
AC_PROG_FC([COMPILERS...], [DIALECT])
[COMPILERS...] is a list of specific compilers you want it to try, so you could give it [f77 g77] as an
argument. That’s useful if you have rather specific demands or need to more-or-less customize
this.
More useful is the DIALECT, which can be 77, 90, 95 or 2000. Thus if you give this as AC_PROG_FC([], 77) or
AC_PROG_FC([], 1977) then this will search only its internal list of Fortran 77 compilers (which happens to be
[g77 f77 xlf frt pgf77 fort77 fl32 af77] currently).
AC_PROG_FPP(required-features,[FPP-SRC-EXT=F])
required-features is a space-separated list of features that the Fortran preprocessor must have for the code to
compile. It is up to the package maintainer to properly set these requirements.
FPP-SRC-EXT is an optional specification of the file extension for preprocessable Fortran source files (without a
leading dot). It defaults to F: There would appear to be a problem, here, with case-insensitive filesystems, such
as the default HFS+ on MacOS X, and Windows filesystems, since the extension .F is indistinguishable from
plain .f. However there is no problem in practice, since the Fortran compilers you are likely to
encounter on these platforms are all capable of compiling preprocessable Fortran directly to object code,
without requiring the intermediate .f file (and there is a check in autoconf to double-check that this is
true).
The macro works out if the Fortran compiler discovered by macro AC_PROG_FC has the requested set of features.
If so, it arranges for the compilation to be done ‘directly’; if not, it arranges for ‘indirect’ compilation, where the
preprocessable Fortran code is converted to pure Fortran code and only subsequently passed to the Fortran
compiler.
The configure variables which this macro sets, and which are available for substitution, are as follows.
FPP FPPFLAGS FPP_SRC_EXT FPP_COMPILE_EXT FPP_SRC_EXT if the compiler itself can do preprocessing (‘direct’ compilation), or a dummy
value (not .f, since that would conflict with the pre-existing rule for compiling Fortran) if it cannot,
and the file must be preprocessed separately (‘indirect’).
FPP_PREPROCESS_EXT FPP_SRC_EXT for indirect compilation, or a dummy value for direct compilation, when the
corresponding separate-processing generated rule should be ignored.
FPP_MAKE_FLAGS cpp or fpp command if we compile directly, and leave
them out otherwise.
FPP_OUTPUT >$@
You do not generally need to know or care about the above variables, since if you have any preprocessable
source files in your source set, then automake will insert appropriate build rules in the generated Makefile.in
on your behalf. If, however, you need to run the preprocessor ‘by hand’ for some reason (perhaps because you
are using the preprocessor to do something other than compiling .F to .o, so that the .F file is not being
mentioned in a _SOURCES primary), then a suitable stanza in a Makefile.am or Makefile.in would
be:
where we have ensured that the input file has the extension $(FPP_SRC_EXT). You can add extra options such as
-I. if necessary (automake puts these in the variable $(DEFAULT_INCLUDES)).
NOTE: There are some features of this macro support which are arguably bad autoconf style, and it is very likely that this macro will change. The documentation below is only for completeness, and you are advised not to pay any attention to it. See Sec. C.
Supported features are:
#include directives and -I options
-D options
fpp is probably the only
preprocessor that does this.
-C option in cpp)
Features can be abbreviated: i, in, inc etc. are equivalent to include. Features can be deselected (feature not needed) by prepending "no", e.g. nodef (=nodefine), now (=nowrap).
Default for the feature list is [include define substitute nowrap nocstyle noCSTYLE]
Feature requirements corresponding to the defaults may be omitted
Note that "wrap" implies "substitute", and CSTYLE and cstyle cannot be requested at the same time. The macro adjusts this automatically.
STAR_CHECK_PROGS(progs-to-check-for, [package=”])
Note: The functionality of this macro is very likely to change.
For each of the programs in PROGS-TO-CHECK-FOR, define a variable whose name is the upcased version of the
program name, and whose value is the full path to that program, or the expected installation location of that
program if no absolute path can be found. Because of this default behaviour, this macro should only be used for
locating Starlink programs such as messgen or alink, and not as a general replacement for AC_CHECK_PROG. Any
characters in the program outside of the set of alphanumerics and underscores are normalised to
underscores.
The optional second argument gives the name of the package containing the program in question. Some packages install their binaries in package-specific directories, and this argument allows this macro to look there as well.
For example: STAR_CHECK_PROGS(messgen) would define the variable MESSGEN to have the full path to the
messgen application.
Calls AC_SUBST and AC_ARG_VAR on the generated variable name.
This is the analogue of AC_CHECK_PROG, except that: (1) the variable name defaults to the program
name, (2) if the program is not found, the variable value is the program’s name without any path at
all.
The current value of the PATH variable is augmented by the location of the binary installation directory, using the
current default value of the prefix (not ideal, since this may in principle change when the component being
configured is installed, but it’s the best we can do at configure time); and by the $STARLINK/bin,
$STARLINK/Perl/bin and $STARLINK/starjava/bin directories (so this is a suitable macro to use to locate the
distributed Perl binary).
If the program in question cannot be found, the the substitution variable is set to be the name of the program without any path, in the expectation or hope that the program will eventually end up in the path. This is not ideal, but it is the best that can be done in the important case where the program is being configured as part of bootstrapping build, and thus before any packages have been built and installed, so that there is in fact no installed program to be found. This heuristic will obviously fail when the program to be checked for is not in the path, and this will typically happen when the second ‘package’ argument is non-null. The pattern to use in this case is as follows.
Some components build their documentation using the (now deprecated) sst component. This uses the
per-package-dirs option, and so installs its applications in a package-specific directory. You would therefore
check for the prolat tool (for example) in configure.ac using STAR_CHECK_PROGS(prolat,sst). If
the sst component is in fact installed, this would substitute @PROLAT@ with the full path to the
application; but in a bootstrap build could do no more than subsitute it with the bare program name
prolat, as described above. In order to use this within a Makefile.am, you would have to use a rule
like
where the PATH is temporarily augmented with the installation location of the sst component. This is pretty
safe, because the STARLINK Makefile variable is always present and always substituted. Despite that, it is not
ideal, since it depends on undocumented (but unlikely to change in practice) knowledge of how the sst
component is installed, and it is possible to think of convoluted installation schemes which might trip this up.
Given that, the only time this is likely to matter is during a bootstrap build (at other times, prolat would be
installed already and so @PROLAT@ would be substituted with a full path), so it is unlikely to be a problem in
practice.
STAR_CNF_BLANK_COMMON
Determine the global symbol used for the Fortran blank common storage space. This is a specialist macro
probably only of use to the CNF package. Its only side-effect is to define the C macro BLANK_COMMON_SYMBOL.
STAR_CNF_COMPATIBLE_SYMBOLS
Work out what is required to have the Fortran compiler produce library symbols which are compatible with
those expected by the CNF package. If you are building a library which includes Fortran code, then you should
call this macro, which possibly adjusts the FCFLAGS variable.
At present, all this macro has to do is simply work out whether it needs to stop g77 adding a second underscore
to generated symbol names (it adds a single underscore to most Fortran symbols, but by default
adds two when the symbol name already contains an underscore); the other Fortran compilers we
use don’t need any extra options, as it happens. However this could potentially be much more
complicated. The autoconf AC_F77_WRAPPERS macro detects more possibilities, but probably not a
completely exhaustive set. In future it might be necessary to extend the CNF macros, by somehow
merging the results of AC_F77_WRAPPERS into it, and at that point it might be necessary to extend this
macro.
This macro is designed to work with CNF, however it does not require the cnf.h headers to be installed, because
it should remain callable at configuration time before anything has been installed. Instead we fake the
functionality of the definition F77_EXTERNAL_NAME in cnf.h, which appends an underscore (just one) to the end
of C symbols.
STAR_DECLARE_DEPENDENCIES(type, deplist, [option=”])
Declare dependencies of this component. The TYPE is one of ‘sourceset’, ‘build’, ‘link’, ‘configure’, ‘use’ or ‘test’,
and the DEPLIST is a space separated list of component names, which this component depends on in the
specified way.
This is less complicated than it seems. The only types you’re likely to have to specify are ‘build’ and ‘link’ dependencies.
configure.ac should contain
STAR_DECLARE_DEPENDENCIES(build,D).
STAR_DECLARE_DEPENDENCIES(link,D)
STAR_DECLARE_DEPENDENCIES(build,D,link).
In full, the types of dependencies are as follows:
These are the components which must be installed in order to build the complete set of
sources, either for building or for distribution. This includes building documentation, so it would
include star2html as well as messgen. These dependencies are generally added for you, by the
STAR_LATEX_DOCUMENTATION or STAR_MESSGEN macros.
These are the dependencies which are required in order to build this component. This is typically
because you require include files installed by the other component, but it might also be because
you require an executable built by it (such as the compifl tool within the parsecon component).
See also the discussion of ‘option’, below. You may not have two components which have a build
dependency on each other, since that would mean that each would have to be built before the
other, which is impossible.
These are the dependencies required to link against the libraries in a component. That means all the libraries that this component’s libraries use. These are not necessarily build dependencies, since if you are building a library X, which uses functions in library Y, the library Y does not have to be present in order to build library X, only when you subsequently want to actually link against it. Thus you can have two components which have mutual link dependencies. If you are building an application, however, all its link dependencies will actually be build dependencies and should be declared as such. In other words, the distinction between build and link dependencies is important only for library components.
make
configure-deps stage of the bootstrapping build process.
You should try hard to avoid declaring dependencies of this type, since they necessarily subvert the normal build order. Note that transitivity implies that any dependencies of a configure dependency are also configure dependencies, so that declaring a configure dependency on sst for example (an obvious but bad plan), results in half the software set being built before configuration. Which is crazy.
You can see the set of configure dependencies by looking at the configure-deps target in
Makefile.dependencies.
These are the dependencies required in order for the component to be used by something else,
after it has been built and installed. For example a library which called another application as part
of its functionality would have only a use dependency on the component which contained that
application. If no use dependencies are declared, we take the use dependencies to be the same as
the link dependencies. We expect that such use dependencies will become more important when
we start using this dependency information to build distribution packages, or to assemble .rpm or
.deb packages. You should add any use dependencies you are aware of, even though we cannot
really debug them until a distribution system is in place.
These are required in order to run any regression tests which come with the component. It’s generally a good idea to avoid making this a larger set than the use dependencies, but sometimes this is unavoidable. If no test dependencies are declared, we take the test dependencies to be the same as the use dependencies. Note that the system does not currently make any use of this information.
The point of all this is that different dependencies are required at different times. The set of dependencies in the master makefile is composed of all the ‘sourceset’ and ‘build’ dependencies, but not ‘link’ or ‘use’ dependencies, and since the core Starlink libraries are closely interdependent, the set of ‘build’ dependencies needs to be kept as small as possible in order to avoid circularities (that is, A depending on B, which depends, possibly indirectly, on A).
It is because of this intricacy that the dependencies scheme is so complicated. In general, it is safe to declare most things to have build dependencies, and only refine these into link or use dependencies when things won’t work otherwise.
All these relationships are transitive: if A has a build dependency on B, and B has one on C, then A has a build
dependency on C. You can augment this by using the final ‘option’ argument: if, in component A’s
configure.ac, you say STAR_DECLARE_DEPENDENCIES(build, B, link), then you declare that A has a
build-time dependency on B, but that (presumably because B is a component consisting entirely or mostly of
libraries) you need to link against B, so component A has a dependency on all of B’s link dependencies, not just
its build dependencies. An application component should generally declare such a dependency for each of the
libraries it depends on. This is (I believe) the only case where this ‘option’ attribute is useful, though it is legal
for each of the dependency types.
Because of the transitivity, you need only declare direct dependencies. If package A depends on package B, which depends in turn on package C, then package A need not declare a dependency on C.
The macro may be called more than once. The results of this macro are expressed in the file component.xml in
the component directory.
STAR_DEFAULTS([options=”])
Sets up the defaults for Starlink configure.ac files. The optional OPTIONS argument holds a space-separated list
of option keywords, of which the only ones defined at present are per-package-dirs and docs-only.
As part of its initialisation, this macro does the following:
STARLINK is defined, so that you can use it elsewhere in your
configure.ac file. The value of this variable depends on the STARCONF_DEFAULT_STARLINK
variable which is defined by the ./starconf.status script (see Sec. 2.2), and can be overridden
by a setting of STARLINK in the environment, though you are discouraged from doing that.
AM_FCFLAGS and AM_LDFLAGS (you shouldn’t have to care, as
the point of these prefixed variables is that they should be orthogonal to the unprefixed variables
with the similar names, but see Sec. 6.4 for a gotcha).
PACKAGE_VERSION_MAJOR, ..._MINOR, ..._RELEASE and
..._INTEGER. These are respectively the major, minor and release numbers extracted from
PACKAGE_VERSION, and an integer representation of these consisting of major * 1000000 + minor
* 1000 + release.
This macro also sets the prefix shell variable to its default value. Standard autoconf ./configure scripts also
do this, but at a slightly later stage, which prevents the variable being used safely within configure.ac scripts.
This is useful if you have to configure a thirdparty package in a subdirectory, by calling its ./configure script
with a suitable –prefix option.
The option per-package-dirs, has three consequences:
fac_*_err
files are regarded as being in a separate category, and still install in /star/help, without any
package-specific prefix);
bin_DATA is permitted: any files assigned to this variable are
installed in the (package-specific) binary directory as data, as opposed to executables;
version.dat is created (at make rather than install time). This holds the bare
PACKAGE_VERSION number, and is installed in the binary directory.
See also Sec. C.
The docs-dir option declares that this component contains only documentation (or at least, no
code). This triggers mild changes in the behaviour of the STAR_DEFAULTS macro which should
make configuration somewhat faster in this case. Certain other macros, such as STAR_MESSGEN, are
disabled.
STAR_INITIALISE_FORTRAN_RTL
Define a macro which can be used in a C or C++ main program to initialise the Fortran RTL, including, for
example, doing whatever work is required so that the Fortran getarg() function works. This defines the macro
STAR_INITIALISE_FORTRAN(argc,argv). If nothing is required or possible on a particular platform, then this
expands, harmlessly, to nothing.
You might use this as follows:
STAR_LARGEFILE_SUPPORT
Set macros for compiling C routines that want to make use of large file support. This is a joining of
AC_SYS_LARGEFILE and AC_FUNC_FSEEKO so defines the macros _FILE_OFFSET_BITS, _LARGEFILE_SOURCE and
_LARGE_FILES as needed , along with HAVE_FSEEKO when fseeko and ftello are available.
To use large file support you need to use fseeko and ftello, instead of fseek and ftell, when HAVE_FSEEKO is
defined (and use type off_t for offsets) and compile all C code with the other defines (many of the usual system
calls are replaced with large file supporting ones, when this is done).
Currently the AC_FUNC_FSEEKO macro does not define _LARGEFILE_SOURCE under Solaris, so this function makes
sure that this is done. It also gathers the values of _FILE_OFFSET_BITS, _LARGEFILE_SOURCE and _LARGE_FILES
and sets the STAR_LARGEFILE_CFLAGS variable so that it can be used as part of CFLAGS when compiling. This in
useful for passing to packages which are not directly part of the starconf system. Note that normally the
necessary defines are written to config.h or are already made part of the local CFLAGS, so this variable is not
needed.
STAR_LATEX_DOCUMENTATION(documentcode, [targets=”])
Generate the standard makefile targets to handle LATEX documentation source. The parameter documentcode
should be a space-separated list of codes like ‘sun123’ – they must not include any .tex extension. Each of the
documentcodes may optionally be followed by a slash, to indicate that the source file is not in the current
directory; see below.
The second, optional, argument gives an explicit list of the targets which are build. If this is not specified, then a
standard list is used (.tex, .ps and .tar_htx at present, though this is in principle subject to change) and
corresponding rules added to the generated makefile. If it is specified, it must be non-null, and its value is a list
of files which are to be added to the distribution, and no extra Makefile rules are added. Thus if users need
anything complicated done, they should use this second argument and provide rules for satisfying the given
targets.
In the latter case, the .tex -> htx_tar rule is still emitted, so you can use it, but it requires the substitution
variable @STAR2HTML@, and so if you do use it, you will have to make that available, either through
STAR_CHECK_PROGS(star2html) or otherwise (see Sec. A.14). If you need to tune the parameters
used when running the star2html command, then assign these to the STAR2HTML_FLAGS macro in
Makefile.am.
The default rule for compiling LATEX files simply runs LATEX twice. If you need to do more than this – for
example to run BibTeX or make an index – then you can override this by setting the variable LATEX2DVI in the
configure.ac file; it is already substituted with a default value, so you don’t have to call AC_SUBST on it. This
variable should refer to LATEX as $$LATEX, and use $$1 to refer to the root of the LATEX file to be compiled (that is,
the filename with any .tex extension removed). The doubled dollar signs are because this is evaluated within
the context of a ‘make’ rule. Thus if you needed to run BibTeX between the LATEX runs, you would
define:
This macro defines the substitution variable @STAR_LATEX_DOCUMENTATION@ to be the second macro argument if
that is present, or the default target list if not. This variable must therefore be used as a value for the
stardocs_DATA Makefile variable (see Sec. A.32).
If any documentcode is followed by a slash, then the default target list is assigned to
@STAR_LATEX_DOCUMENTATION_<DOCUMENTCODE>@ instead; you may not use this latter feature if the second
argument is non-null.
See Sec. 4.6 for more discussion of this feature, plus an example.
The configure option –without-stardocs suppresses building documentation.
It is occasionally necessary to add extra files to the .htx tarball – for example .gif images, or other files
referenced by the HTML version of the documentation. To request that extra files should be added to the
starnnn.htx_tar archive, you should create a file starnnn.htx_tar.extras listing the filenames which should
be included, separated by whitespace (spaces, tabs or newlines).
The STAR_MANIFEST_DIR substitution variable is slightly special. If it is defined in your configure.ac file, then
Starlink automake will include in the generated Makefile.in code to create and install a manifest of all the files
installed.
If you set this variable at installation time:
then this overrides the manifest location defaulted at configure time. If the variable is set to be null
(make STAR_MANIFEST_DIR= install) then you will suppress the creation and installation of the
manifest.
You define it as follows:
This sets the variable to be $(prefix)/manifests, but allows it to be overridden by a setting of the
variable in the environment. Note that is is set to be relative to the value of the $(prefix) makefile
variable.
You do not have to set this in general, as this is one of the things that the STAR_DEFAULTS macro (Sec. A.18) takes
care of. The only time you need to use this feature is when you are importing a third-party code set into the tree
(as described in Sec. 4.5). In that case, you do not want to specify STAR_DEFAULTS in the configure.ac, but you
do need to install a manifest. If there is more than one configure.ac file in the tree, you will have to add this for
each one.
See also Sec. A.29.
STAR_MESSGEN([msgfile-list])
Handle generating message, error, and facility files.
Declare that we will need to use the messgen utility. This macro does not by itself cause the messgen
rules to be included in the makefile – that is done by automake, when it sees a include_MESSAGES
variable.
In the Makefile.am you declare the include_MESSAGES or noinst_MESSAGES variable to have as value each of
the error files you require from the .msg file. For example, you might write:
to generate, install and distribute the C and Fortran error message files. You may include a _SOURCES declaration
to indicate the name of the .msg file, but the default value (ast_err.msg in this case) is usually correct. The files
thus listed are installed in the same include directory as other header files. You should not list a file in both
include_MESSAGES and include_HEADER.
If you need to work with an error file which is not public, you can declare it with
Such a file is generated but not installed. In order that it be distributed, you should include $(noinst_MESSAGES)
in the _SOURCES declaration of the program which includes it.
Although it’s difficult to see why you’d want to, you can include the nodist_ prefix with this primary.
You do not need to mention the fac_xxx_err file which messgen also generates – this is generated and installed
automatically.
The optional argument is a space-separated list of files, each of which has a set of message declarations in it, in
the format prescribed by the messgen utility. If this is present, then the named files are declared as
pre-distribution files (the macro calls STAR_PREDIST_SOURCES on them), and so the resulting configure script
should expect not to find them in an unpacked distribution. This is useful as documentation or as a shortcut for
calling the latter macro, but recall that it is the presence of the automake include_MESSAGES variable which does
the work.
The macro may be called more than once if you have more than one .msg file in the directory.
The files which this generates should be declared as sources in the Makefile.am if they are to be used in code, or are to be installed. For example:
If they are used in building the package, you will probably need to declare them additionally as
BUILT_SOURCES.
The macro also implicitly declares a ‘sourceset’ dependency on the messgen package.
STAR_MONOLITHS
Declare that we will be creating monoliths. This is conceptually similar to the various AC_PROG_FC declarations,
and does whatever configuration is necessary to handle these.
Note that the declarations done in the Makefile.am, declaring the name of the monolith and the names and
source files of the tasks, are slightly redundant inasmuch as some of that information could be implied.
However, this is required to be explicit for clarity and consistency, and so accomodate the (currently
unexploited) possibility that the tasks and .ifl files longer have the one-task-per-file relationship they have
now.
See Sec. 3.4 for discussion.
STAR_PATH_TCLTK([minversion=0], [options=”])
Finds a tclsh, and the associated libraries, optionally searching for Tk as well.
Sets substitution variable TCL_CFLAGS to the C compiler flags necessary to compile with Tcl, TCL_LIBS to the
required library flags, and variable TCLSH to the full path of the matching tclsh executable and TCL_VERSION to
the major.minor version number; if Tk is requested, it similarly sets TK_CFLAGS, TK_LIBS and WISH. Define the
cpp variable TCL_MISSING to 1 if the required programs and libraries are not available (that is, it is also set if Tcl
is available but a suitable version of Tk isn’t).
If argument minversion is present, it specifies the minimum Tcl/Tk version number required.
If the argument options is present, it is a space-separated list of the words tk and itcl. If one or both of these is
present, then the macro will find a Tcl location which also has Tk or itcl installed (note that the itcl test doesn’t
do anything at present).
The macro searches first in the path, and then in a selection of platform-specific standard locations. The
configure option –with-tcl allows you to provide a path to a tclsh binary, which is put at the head of the list of
locations to search. Option –without-tcl suppresses the search, and results in no variables being
substituted.
This is intended to be similar to macro AC_PATH_XTRA.
STAR_PLATFORM_SOURCES(target-file-list, platform-list)
Generate the given target-file for each of the files in the list TARGET-FILE-LIST, by selecting the appropriate
element of the PLATFORM-LIST based on the value of AC_CANONICAL_BUILD. Both lists are space-separated
lists.
For each of the platforms, <p>, in platform-list, there should be a file <target-file><p>. There should always
be a file <target-file>default, and if none of the platform-list strings matches, this is the file which is used. If
the ‘default’ file is listed in the ‘platform-list’, then it is matched in the normal run of things; if it is not listed, it
still matches, but a warning is issued.
If you wish no match not to be an error – perhaps because there is a platform-dependent file which is redundant
on unlisted platforms – then end the platform-list with NONE. In this case, if no file matches, then no link is made,
with no error or warning.
This macro uses the results of ./config.guess to determine the current platform. That returns a triple
consisting of cpu-vendor-os, such as ‘i686-pc-linux-gnu’ (OS=linux-gnu), ‘sparc-sun-solaris2.9’, or
‘alphaev6-dec-osf5.1’.
The extensions <p> in platform-list should all have the form ‘cpu_vendor[_os]’, where each of the components
‘cpu’, ‘vendor’ and ‘os’ may be blank. If not blank, they are matched as a prefix of the corresponding part of the
config.guess value. Thus ‘_sun_solaris’ would match ‘sparc-sun-solaris2.9’ but not ‘sparc-sun-sunos’,
and ‘_sun’ would match both. For a <target-file> file foo.c, this would result in ‘ln -s foo.c_sun
foo.c’.
Calls AC_LIBSOURCE for each of the implied platform-specific files.
STAR_PREDIST_SOURCES(source-files)
Give a (space-separated) list of files which should exist only in the pre-distribution (ie, repository checkout)
state. If one of these is found, then the substitution variable PREDIST is set to a blank rather than the comment
character #. This means that Makefile rules which are intended to work only in the pre-distribution state – for
example to generate distributed sources – should appear in Makefile.am with each line prefixed by @PREDIST@.
After configuration, these rules will be enabled or disabled depending on the presence or absence of the marker
files listed in this macro.
We should find either all of the marker files or none of them; if some but not all are found, this is probably an error of some type, so warn about it. This means, by the way, that it is the presence or absence of the first marker file which determines whether we are in the pre-distribution or post-distribution state, with the rest providing consistency checks.
The macro may be called more than once. Multiple calls are equivalent to a single call with all the marker files in the list. Automake checks that the files listed here are not in the list of distributed files, and issues a warning if they are.
If you use this @PREDIST@ variable, then it is important to refer to all the files thus protected in a
STAR_PREDIST_SOURCES call. The build will possibly still work if you forget to do this, but if so you are
discarding a potentially useful consistency check.
For examples of use, see Sec. 4.3
STAR_PRM_COMPATIBLE_SYMBOLS
This macro supports the use of the VAL__ constants that are defined in the include file PRM_PAR. If
checks if any special compiler flags are required to support PRM’s use of typeless BOZ (binary octal,
hexadecimal) constants, or if there’s no typeless BOZ support any special flags that are required for
that.
In fact this macro is only currently of use with the gfortran compiler which has no typeless BOZ support, so
requires that the -fno-range-check flag is set so that assigments to integers can silently overflow (BOZ
constants are replaced with their integer and floating point equivalents). In general this macro
should be used by all packages that include PRM_PAR, all monoliths are assumed to use this by
default.
Third-party sources will not come with a make install target which installs a manifest. It is reasonably easy to
add such support, however, as described in Sec. 4.5.3. The crucial feature is the one line installation
command declared in the macro STAR_SPECIAL_INSTALL_COMMAND. If this macro variable is present
in a configure.ac file, then Starlink automake will generate an install target which uses this
command to do the installation, in such a way that a manifest file can be generated automatically. The
argument to this macro is executed as the last command (or commands) in a subshell, the exit value
of which is tested for a success status. For this to work, the command must have the following
features:
$(MAKE) (as opposed to plain ‘make’), as part of some $(MAKE) ...
install command.
$DESTDIR. Recent versions of automake generate support for this variable automatically,
older versions appear to have had the same functionality, but used a variable $INSTALL_ROOT for it.
The example shown in Sec. 4.5.3 shows a use of this macro which satisfies these constraints.
The command may be as complicated as you like, but note that it is collapsed onto a single line by autoconf, so although you may spread the macro argument over several lines for readability, each command must be separated by a semicolon (or double-ampersand or double-bar).
See Sec. 4.5 for general discussion of importing third-party sources.
STAR_SUPPRESS_BUILD_IF(test, message)
Some components should be built only conditionally, if certain conditions apply. For example, the sgmlkit
component can be built only if the host system has jade installed on it, but the lack of this is not an
error, in the sense that it should cause a tree-wide ./configure to fail. This macro helps with this
situation.
If this macro is triggered, by the given condition being true, then ./configure, make and make installwill all
succeed without compiling anything, with the latter installing a correctly formed manifest file which does not list
any installed files.
The test in the first argument is a shell expression which should evaluate to true (ie, return a zero status) if the
build should be suppressed. In the case of the sgmlkit component, the configure.ac includes the
lines:
The test expression evaluates to true if either of the $JADE or $SGMLNORM variables has the special values given as
defaults in the AC_PATH_PROGS macros earlier.
If the test is true, the message is displayed during the ./configure run, but the configuration does not fail.
Instead, a stamp file STAR_SUPPRESS_BUILD is left in the build directory, with the consequence that if you
subsequently type make, that build will do nothing, emit the same message, and also not fail. If you
subsequently invoke make install, that will also succeed, but install no files, except a manifest without a
<files> element.
If you do any special installation work in your Makefile.am, remember to check for the existence of this stamp
file, and make sure that you do not actually install anything if the file is present.
The difference between this and the standard AC_FATAL macro is that the latter is for an error in the
configuration script – either a logic error there, or a serious problem like being unable to compile anything at all!
Alternatively, if a dependency should be present because it is listed in the configure.ac as such, but it isn’t,
that’s a case for a call to AC_FATAL. The STAR_SUPPRESS_BUILD_IF macro is for rather more well-mannered
interactions with the user, indicating that there is other work they might have to do to get this component
building.
You should use this macro rather sparingly. If a component depends on a component thus suppressed, there will likely be trouble.
STAR_XML_DOCUMENTATION(documentcode, [targets=”])
Generate the standard makefile targets to handle XML documentation source. The parameter documentcode
should be something like ‘sun123’ – it should not include any .xml extension.
For details, see the macro STAR_LATEX_DOCUMENTATION, which this macro closely matches, and which is more often used. The differences are as follows:
.texml_tar .htx_tar .ps .pdf, though using the second argument
(discouraged) requires you to specify values for the JADE, SGMLNORM and SGMLKIT_HOME
substitution variables (the .texml_tar tarball contains a .tex file plus any required figures).
@STAR_XML_DOCUMENTATION@ and
@STAR_XML_DOCUMENTATION_<DOCUMENTCODE>@.
LATEX2DVI is the same, and configure option –without-stardocs suppresses this
documenation, too.
There are several makefile variables which help you install files in special directories. These are the variables
stardocs_DATA, staretc_DATA, starexamples_DATA, starhelp_DATA and starnews_DATA (there is also
starfacs_DATA, for facility files, but this is handled for you, and you should not need to refer to this explicitly).
In the Makefile.am the variable has as value a list of files to be installed as data in the corresponding
place.
The list of documentation files is not necessarily known in advance, since the macro STAR_LATEX_DOCUMENTATION
has a default list of targets it will generate. You can give the value of the stardocs_DATA as a substitution
variable:
(plus any other documentation files you require). See Sec. 4.6 for more discussion.
AC_F77_HAVE_OPEN_READONLY
Obsolete: use AC_FC_OPEN_SPECIFIERS instead
Obsolete: The STAR_X_FILES macros (for X in DOCS, ETC, EXAMPLES and HELP) are now obsolete, and you should
use the corresponding makefile variables instead – see Sec. A.32.
STAR_FC_LIBRARY_LDFLAGS
Obsolete: use standard AC_FC_LIBRARY_LDFLAGS instead – the extra functionality which this macro added to the
standard one is now handled automatically.
STAR_HAVE_FC_OPEN_READONLY
Obsolete: use AC_FC_OPEN_SPECIFIERS(readonly) instead.