NAME
localmake_config - Manage connections between Antelope-contrib code and software external to Antelope
SYNOPSIS
localmake_config [-ilvf] [capability [, capability...]]
SUPPORT
Contributed code: NO BRTT support.
THIS PIECE OF SOFTWARE WAS CONTRIBUTED BY THE ANTELOPE USER COMMUNITY. BRTT DISCLAIMS ALL OWNERSHIP, LIABILITY, AND SUPPORT FOR THIS PIECE OF SOFTWARE.
FOR HELP WITH THIS PIECE OF SOFTWARE, PLEASE CONTACT THE CONTRIBUTING AUTHOR.
DESCRIPTION
Most source-code in the Antelope contributed-code repository compiles without any dependencies
on software outside of the self-contained Antelope directory hierarchy. Such code is thus able to
use the standard Antelope make-rules and build mechanisms documented in
antelopemake(5) and
antelopemakefile(5). Occasionally, however, tools in the Antelope contributed-code repository have been
written to link against and use tools that are not part of the self-contained Antelope distribution.
Classic examples are the Antelope Toolbox for Matlab, which uses Matlab from Mathworks, Inc.; the PHP
and Python interfaces to Antelope; and the dbxcor(1) cross-correlation processor, which uses the X-Motif
libraries. The
localmake_config program represents an attempt to standardize how such external
dependencies are configured and linked within the Antelope contributed-code distribution.
Basically,
localmake_config manages two kinds of entities:
capabilities (such as
php,
python, or
matlab), which may be enabled or disabled; and
macros (such
as
MATLAB,
PYTHONINCLUDE, etc.), which may be either blank or filled-in with pathnames
for the local system.
localmake_config does not compile anything. All it does is set up the
necessary conditions for external links to succeed. (In order to compile desired software
elements, either execute
make install in the appropriate source-code directories, or alternatively
use the
localmake(1) program, after you finish running
localmake_config).
When
localmake_config is run without any
capability arguments on the command-line, it
launches the
localmake program in
-c i.e. configuration mode. This allows the normal user
to specify which externally-dependent capabilities to enable, and where to find the necessary
supporting components on their system.
The local configuration of external components (as well as the behaviour of the
localmake_config
program itself), is controlled by a parameter file on the local system which is kept in
$ANTELOPE/local/data/pf/localmake_config.pf
If this does not exist,
localmake_config makes an initial version of the file when it first runs.
Once configured,
localmake_config creates a set of local make-rules to handle all configured
dependencies. By default, these local make-rules are stored in
$ANTELOPE/local/include/antelopemake.local
Do not edit the above file of make rules directly, as it will be automatically overwritten upon
any changes to the
localmake_config.pf parameter file and re-run of
localmake_config.
All changes by the user must be made to the file
localmake_config.pf, either by hand or by using
the
localmake GUI.
An alternative to running the
localmake GUI to configure the local system would be
to edit by hand the configuration file
$ANTELOPE/local/data/pf/localmake_config.pf
For example the edits to the above file
in support of the
matlab capability would be changing
capabilities &Arr{
matlab 0
}
to
capabilities &Arr{
matlab 1
}
And, for the platform on which you're running (
Darwin,
SunOS, or
Linux),
filling in the MATLAB macro, e.g. changing
macros &Arr{
MATLAB
}
to
macros &Arr{
MATLAB /Applications/MATLAB_R2009b.app
}
'Verify' mode
N.B. This man-page section is for people developing Antelope-contrib
software that depends on external utilities and for those curious
about all underlying technical details. If you're just configuring
and compiling software to use on your own system, not writing any,
the explanations above should suffice.
In addition to allowing the user to configure external software
linkages to the Antelope-contrib code base,
localmake_config
functions as part of the automated software compilation process.
When
localmake_config is run with one or more
capability
arguments on the command-line, it starts in
verify mode. This
is used within some Antelope-contrib make files to manage compilation
against external dependencies. In
verify mode,
localmake_config
tests the listed
capabilities to see whether they 1) are
enabled for use; 2) are properly supported by non-blank values for
all the macros they require; and 3) pass all the tests listed in
localmake_config.pf for the given
capability. If all
of these indicate that whatever depends on the
capability
should be compiled,
localmake_config exits with exit-code of
0. Otherwise,
localmake_config exits with an exit code of -1,
which is intended to stop compilation in the current directory.
The way this is used in the Antelope-contrib compilation structure
(based on
antelopemake(5)) is as follows. First, instead of
implementing one
Makefile in the style of
antelopemake(5),
the developer implements two separate files:
makefile and
Makefile2. The former executes
localmake_config, naming
the desired capability on the command-line, and determining whether
or not to proceed with compilation. For example, in a directory
that depends on the
python capability,
makefile would
look like this:
all Include install installMAN pf relink tags test :: FORCED
@-if localmake_config python ; then \
$(MAKE) -f Makefile2 $@ ; \
fi
clean uninstall :: FORCED
$(MAKE) -f Makefile2 $@
FORCED:
The
Makefile2 rules would then follow the format documented
in
antelopemakefile(5), though with the line
include $(ANTELOPEMAKE)
expanded to say
ANTELOPEMAKELOCAL = $(ANTELOPE)/local/include/antelopemake.local
include $(ANTELOPEMAKE) include $(ANTELOPEMAKELOCAL)
SUBDIR= /local
Note that the assignment of
SUBDIR to
/local may be
appropriate only in some situations. With this structure, the macros
supporting the
python capability (as configured in
localmake_config.pf, currently
PYTHONINCLUDE and
PYTHON_EXECUTABLE) will now be available for use in
Makefile2.
OPTIONS
-
-i
Install make rules and exit.
-
-l
List available capabilities and whether they're enabled or disabled, then exit.
-
-v
Verbose
-
-f
Force make rules to be generated regardless of input file age
FILES
The master parameter-file controlling the behavior of
localmake_config, and hence all the compilation tasks it
governs, is
$ANTELOPE/local/data/pf/localmake_config.pf
A starting draft of this file may be obtained from
$ANTELOPE/data/pf/localmake_config_proto.pf
When
localmake_config runs, it checks and updates the automated set of make rules currently in
$ANTELOPE/local/include/antelopemake.local
ENVIRONMENT
localmake_config depends on the environment variables
ANTELOPE,
PFPATH, and
ANTELOPEMAKE as documented
in the man-page
antelopeenv(5).
PARAMETER FILE
This section describes the parameter-file for
localmake_config. Generally this parameter-file
is created automatically by
localmake_config and/or the
localmake GUI in
configure
mode. It may, however, be hand-edited or created by system administrators for each platform. In that
case to configure a system one needs only to A) mark each capability with a
0 or
1 value in
the
enable sub-parameter; and B) Fill in the desired macro values in the
macros array.
Note that due to coding limitations, the booleans for enabling individual capabilities should be
explicitly 0 or 1 (i.e. not any of the string boolean values such as "yes", "no", "true", "ok" etc.).
Parameter Explanations
-
capabilities
This array is a simplified version of the capabilities array in localmake.pf,
with one key for each capability and a value for each capability which is a boolean specifying
whether the capability is enabled on this operating system.
-
macros
This array is a simplified version of the macros array in localmake.pf,
with one key for each macro and a value for each capability which is a string specifying
the value of the macro (possibly empty) on this operating system.
Parameter File Example
capabilities &Arr{
boost 0
matlab 0
perl_DBI 0
php 0
python 0
python_amqplib 0
python_matplotlib 0
python_pygraphviz 0
vtk 0
xmotif 0
}
macros &Arr{
BOOSTINCLUDE
BOOSTLIB
MATLAB
PHP_EXECUTABLE /usr/bin/php
PHP_INC /usr/include/php
PYTHONINCLUDE /usr/include/python2.6
PYTHON_EXECUTABLE /usr/bin/python
VTKINCLUDE
VTKLIB
VTKROOT
XMOTIFINCLUDE
XMOTIFLIB
}
EXAMPLE
To run
localmake_config in
configure mode, enter its name on the command line with no arguments:
% localmake_config
RETURN VALUES
localmake_config exits with a status of 0 if compilation based on the named capabilities is
approved to proceed, or with a non-zero status if compilation should not proceed (
capability
is disabled or failed one or more of its tests).
SEE ALSO
localmake(1), antelopemakelocal(5), antelopemake(5), antelopemakefile(5)
BUGS AND CAVEATS
This program has undergone multiple restructurings to get the design right. Hopefully the
current version has succeeded. In particular, the
localmake_config_proto.pf file
has been eliminated.
localmake_config internally sets and uses
PFPATH to include
$ANTELOPE/local/data/pf.
localmake_config always rebuilds the make rules in
$ANTELOPE/local/include/antelopemake.local if that file has
a timestamp older than the master parameter file
$ANTELOPE/local/data/pf/localmake_config.pf. If an automated
or other process (e.g. directory copy etc.) changes the timestamp
on the former file to be later than that on the master parameter
file,
localmake_config will not know to update the latter.
Changes made to the user's configuration via the
localmake_config
Graphical User Interface must be saved to disk using the yellow
save configuration button (enabled and visible when there are
changes to be saved) or the
File->Save and Quit menu item,
in order for the changes to take effect.
Because
localmake_config automatically keeps the local make
rules up to date, it requires write permission to
$ANTELOPE/local/data/pf/localmake_config.pf and
$ANTELOPE/local/include/antelopemake.local. This is considered
reasonable since compilation and installation requires write
permission in
$ANTELOPE anyways.
AUTHOR
Kent Lindquist
Lindquist Consulting, Inc.
Antelope User Group Contributed Software