NAME
localmake - build subsections of the Antelope-contrib code base
SYNOPSIS
localmake [-c] [-v] [-l] [-p pfname] [-s src_subdir] [-t] module
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
The
localmake program is designed to build and install coherent
subsections of the Antelope contributed-code software base, usually to
support the installation of one particular Antelope-contrib program or
one particular Antelope-contrib software library or interface.
If the
localmake program is given a
module name, it will
recompile all the parts of the specified
module (as detailed in
the
localmake parameter file) on which a particular software
component depends. If the
-t option is used,
localmake will
further assemble the resulting compiled components into a platform-specific
tar file which may be distributed for use on identically configured
machines elsewhere. Depending on the components being compiled and how
their makefiles are structured, the location into which results are
installed may be $ANTELOPE/local rather than $ANTELOPE.
When running in GUI mode, the log of a particular compilation run, as shown in
the main
localmake window, may be saved to a file with the
File->Save compile log as... button. This may be useful if compilation problems
occur which one needs to share with the author of the code in question for help with resolution.
When the
localmake GUI is launched in configuration mode, it presents a
notebook-tabbed panel for each potentially available
capability.
The most important button on each panel is the one to
Enable
or
Disable the
capability in question. After a
capability is enabled, the next step is to fill in the required
macro values to support that
capability. These are presented
as labelled entry-boxes, one entry-box for each necessary macro
value. Balloon help is available for each entry box with a basic
description of what the value describes. For more detailed help,
an
Explain button to the right of each entry box describes
in more detail how the entry should be filled.
When a
capability is enabled,
localmake runs
tests (as configured in
localmake.pf) to ensure the
macro values are OK and other necessary components are in place.
Generally these tests are fairly rudimentary, however important to
check as they determine whether
localmake will allow
software elements to compile during the build process when they
depend on the
capability in question. When macro values are
changed, the tests are re-run. The bottom of the GUI panel for
each
capability shows the status of the tests for the given
capability.
OPTIONS
-
-c
Launch in configure mode instead of compile mode.
-
-l
Print a list of available modules and exit.
-
-s subdirectory
This parameter overrides the src_subdir parameter in the parameter file. For further details,
see the PARAMETER FILE section below.
-
-v
Run in verbose mode.
-
-p pfname
Specify an alternate parameter file.
-
-t
Create a tarball of the compiled module and files on which it depends.
PARAMETER FILE
Parameter explanations
-
tarball_time_format
This parameter specifies the time format (in the format of epoch2str(3))
to be used in naming tar files with compiled code after it has been built.
-
tar_command
This parameter specifies the name of the command to be used to create tar files
-
make_command
This parameter specifies the make command to use in building targets. The environment variable
named MAKE will take precedence over this if defined.
-
<module_name>
The parameter file should contain one parameter-file array (see pf(5)) for each software
module to be built. The array for a given module describes how to build the module and if
desired how to package it (e.g. in a tarball with the -t option). The name of
each array should be a unique, descriptive name for the software module. The values
are arrays with the parameters for how to build and package each module. [Note that the
angle brackets are used here just to indicate that this parameter's actual name is
chosen by the user or programmer for the given software module; these angle brackets should
not appear in localmake.pf itself].
-
<module_name>{product}
This parameter file entry specifies the top-level directory to which the modules being
built are being directed. For example, for the Antelope contributed-code, the product
parameter will be the same as the $ANTELOPE environment variable.
-
<module_name>{capabilities_required}
This parameter file entry specifies the localmake capabilities which need to be
enabled in order to compile this module.
-
<module_name>{src_subdir}
This parameter specifies the top-level sub-directory in which to
find source-code for the entire software distribution out of which
the module comes. Usually it is a path relative to the destination
(e.g. $ANTELOPE) in which the results will be installed. For
example, for the Antelope contributed-code repository, a common
value for src_subdir would be src/contrib to indicate
source-code stored in the directory $ANTELOPE/src/contrib.
In this normal case, the destination directory ($ANTELOPE)
will be prepended to the src_subdir value in order to find
the necessary source-code during compilation. If the src_subdir
parameter is an absolute path, it is treated as such and no other
absolute path is prepended. The src_subdir assignment may be
overridden on the command-line with the -s option.
-
<module_name>{build}
This parameter is a table of directories relative to $ANTELOPE containing the
source code for the software module and all of its dependencies (although
if any of the directory names begins with a '/' character it is assumed to be
an absolute path, and $ANTELOPE is not prepended). When
localmake is told to build a given software package, it enters each of
these directories in turn and executes 'make install'.
-
<module_name>{package}
This parameter is a table of files relative to $ANTELOPE containing
all pieces of compiled code and supporting files comprising a given software
module.
-
antelope
This is a convenient plain reference (see pf(5)) in the parameter file used
to record the current Antelope version.
-
capabilities
Each distinct external dependency controlled by localmake is given
a unique capability name, and configured in the capabilities
Array of the localmake parameter file. The key into this array is the
name of the capability. Each named capability has its own sub-array
with the following values:
-
capabilities{enable}
This is an array with booleans for each platform (Darwin, Linux,
and SunOS), specifying whether or not to attempt compilation (contingent on
successfully passing tests) assuming the existence of this capability. Generally, the
enable values in localmake.pf should be left set to 0, with the actual values for a
given platform configured in localmake.pf. Due to coding limitations, the
booleans should be given explicitly as 0 or 1 (rather than "yes", "no", "true", etc.) so they are parsed
correctly.
-
capabilities{required_macros}
This Table lists the macros required to be defined for this capability.
-
capabilities{tests}
This Table contains one or more parameter-file &Literal values
(as documented in pf(5)), containing perl code to execute a test
to make sure the capability is properly configured. The perl code must
evaluate to a perl true value for the test to be
considered successful. Each test should also define two strings called
$failure_msg and $success_msg containing short
messages to the user explaining the results of the test.
-
capabilities{Description}
This parameter is a short text description of what the capability entails.
-
capabilities{Detail}
This parameter is a longer, detailed text description of what the capability entails.
-
dest
The dest parameter specifies the directory into which the automatically generated
makefile rules will be placed.
-
extra_rules
In addition to locally configured macros, there may be extra rules necessary for
local compilation (such as dot rules for script extensions that invoke template(1),
for example). These extra make rules are listed in the extra_rules
&Literal parameter.
-
header
This parameter-file &Literal contains the message to put at the top of the local
make rules file. Usually, this is a warning about not modifying the file by hand, rather
using localmake.
-
macros
Each makefile macro that may be of use in compiling Antelope-contrib code
against external utilities is described
in the macros Array of the localmake parameter file.
The key into the macros array is the name of the macro. Generally, these values
should be left blank in localmake.pf, unless the locations are so standard on a given
platform that leaving non-blank values proves a convenience rather than an inconvenience to
all users. The actual values for these macros will be configured in localmake.pf
for each system. Each named macro has its own sub-array with the following values:
-
macros{Darwin}
The Darwin sub-parameter gives the configured value of the macro
on Macintosh systems.
-
macros{Linux}
The Linux sub-parameter gives the configured value of the macro
on Linux systems.
-
macros{SunOS}
The SunOS sub-parameter gives the configured value of the macro
on Solaris systems.
-
macros{Description}
This parameter gives a one-line text description of the macro
-
macros{Detail}
This parameter gives a longer text paragraph explaining the macro and
examples of some possible values on different systems.
-
output_file
The output_file parameter gives the filename (without directory path)
of the local Antelope make rules automatically generated
based on localmake.pf.
-
platform_rules
In addition to the globally applicable extra_rules, there may be platform-
specific rules necessary for local compilation (such as overrides to DLDFLAGS
necessary to compile PHP extensions for example). These platform-specific make
rules are listed in this array, with a literal value corresponding to each
platform (Darwin, Linux, and SunOS).
Parameter File Example
tarball_time_format %Y_%m_%d
tar_command tar
make_command make
contrib_src_subdir src/contrib
dbxcor &Arr{
dest &env(ANTELOPE)
src_subdir &contrib_src_subdir
capabilities_required &Tbl{
xmotif
}
build &Tbl{
lib/graphics/seisw
lib/seismic/libseispp
lib/utility/libgclgrid
lib/perf
bin/db/dbxcor
}
package &Tbl{
static/libsciplot.a
bin/dbxcor
data/pf/dbxcor.pf
data/schemas/css3.0.ext/evlink
data/schemas/css3.0.ext/sclink
data/schemas/css3.0.ext/wfprocess
data/schemas/css3.0.ext/xcorarrival
data/schemas/css3.0.ext/xcorbeam
man/man1/dbxcor.1
bin/smartpick_classic
bin/smartpick
data/pf/smartpick_classic.pf
data/pf/smartpick.pf
man/man1/smartpick_classic.1
man/man1/smartpick.1
static/libseispp.a
static/libseisw.a
doc/seispp/gclgrid/ccdoc.GCLgrid.GCLgrid.BasicGCLgrid.cls.html
doc/seispp/gclgrid/ccdoc.GCLgrid.GCLgrid.Cartesian_point.tyv.html
doc/seispp/gclgrid/ccdoc.GCLgrid.GCLgrid.GCLgrid.cls.html
doc/seispp/gclgrid/ccdoc.GCLgrid.GCLgrid.GCLgrid3d.cls.html
doc/seispp/gclgrid/ccdoc.GCLgrid.GCLgrid.GCLgrid_error.cls.html
doc/seispp/gclgrid/ccdoc.GCLgrid.GCLgrid.GCLscalarfield.cls.html
doc/seispp/gclgrid/ccdoc.GCLgrid.GCLgrid.GCLscalarfield3d.cls.html
doc/seispp/gclgrid/ccdoc.GCLgrid.GCLgrid.GCLvectorfield.cls.html
doc/seispp/gclgrid/ccdoc.GCLgrid.GCLgrid.GCLvectorfield3d.cls.html
doc/seispp/gclgrid/ccdoc.GCLgrid.GCLgrid.Geographic_point.tyv.html
doc/seispp/gclgrid/ccdoc.GCLgrid.GCLgrid.create_3dgrid_contiguous.checksum.880250e9.fct.html
doc/seispp/gclgrid/ccdoc.GCLgrid.GCLgrid.create_4dgrid_contiguous.checksum.30144256.fct.html
doc/seispp/gclgrid/ccdoc.GCLgrid.GCLgrid.extract_gridline.checksum.d8861568.fct.html
doc/seispp/gclgrid/ccdoc.GCLgrid.GCLgrid.fme_weights_.checksum.ee6cf964.fct.html
doc/seispp/gclgrid/ccdoc.GCLgrid.GCLgrid.free_3dgrid_contiguous.checksum.9cd6ef36.fct.html
doc/seispp/gclgrid/ccdoc.GCLgrid.GCLgrid.free_4dgrid_contiguous.checksum.970b2485.fct.html
doc/seispp/gclgrid/ccdoc.GCLgrid.GCLgrid.initialize_1Dscalar.checksum.9756fa5d.fct.html
doc/seispp/gclgrid/ccdoc.GCLgrid.GCLgrid.initialize_1Dscalar.checksum.d3dde98f.fct.html
doc/seispp/gclgrid/ccdoc.GCLgrid.GCLgrid.pathintegral.checksum.18f3459b.fct.html
doc/seispp/gclgrid/ccdoc.GCLgrid.GCLgrid.pkg.html
doc/seispp/gclgrid/ccdoc.GCLgrid.GCLgrid.r0_ellipse.double.r0_ellipse.-28.double.-29.fct.html
doc/seispp/gclgrid/ccdoc.GCLgrid.GCLgrid.remap_path.checksum.9d7961f7.fct.html
doc/seispp/gclgrid/ccdoc.GCLgrid.dmatrix.dmatrix.cls.html
doc/seispp/gclgrid/ccdoc.GCLgrid.dmatrix.dmatrix_error.cls.html
doc/seispp/gclgrid/ccdoc.GCLgrid.dmatrix.dmatrix_index_error.cls.html
doc/seispp/gclgrid/ccdoc.GCLgrid.dmatrix.dmatrix_size_error.cls.html
doc/seispp/gclgrid/ccdoc.GCLgrid.dmatrix.pkg.html
doc/seispp/gclgrid/ccdoc.GCLgrid.GCLgrid.flatvel.double.flatvel.-28.double.v.-2c.double.z.-29.fct.html
doc/seispp/gclgrid/ccdoc.GCLgrid.GCLgrid.flatz.double.flatz.-28.double.z.-29.fct.html
doc/seispp/gclgrid/ccdoc.GCLgrid.GCLgrid.uflatvel.double.uflatvel.-28.double.v.-2c.double.z.-29.fct.html
doc/seispp/gclgrid/ccdoc.GCLgrid.GCLgrid.uflatz.double.uflatz.-28.double.z.-29.fct.html
doc/seispp/gclgrid/ccdoc.class_summary.html
doc/seispp/gclgrid/gclgrid.db
doc/seispp/gclgrid/index.html
include/gclgrid.h
include/dmatrix.h
static/libgclgrid.a
man/man3/gclgrid.3
man/man3/dmatrix.3
man/man3/pathintegral.3
man/man3/ustrans.3
man/man3/extract_gridline.3
include/glputil.h
lib/libglputil.dylib
static/libglputil.a
man/man3/check_required_pf.3
man/man3/ftest.3
man/man3/dbform_working_view.3
man/man3/glp_matrix_utils.3
}
}
antelope_php &Arr{
product &env(ANTELOPE)
src_subdir &contrib_src_subdir
capabilities_required &Tbl{
php
}
build &Tbl{
data/php
}
}
capabilities &Arr{
php &Arr{
Description Antelope PHP Interface and PHP-based Antelope tools
Detail &Literal{
The 'php' capability provides linkage to the PHP interpreter on the
local machine (if there are several PHP interpreters, this capability
identifies which one has been chosen to be used with Antelope). This
capability is used within Antelope-contrib primarily for compilation of
the Antelope PHP interface, though it also controls whether other
PHP-dependent Antelope-contrib tools get installed (e.g. webdlmon(3H)
and webdbe(3H)).
}
enable &Arr{
Darwin 0
Linux 0
SunOS 0
}
required_macros &Tbl{
PHP_INC
PHP_EXECUTABLE
}
tests &Tbl{
&Literal{
$failure_msg = "Couldn't find header-file directory '$PHP_INC/Zend' " .
"implied by currently configured value '$PHP_INC' of PHP_INC macro";
$success_msg = "PHP include files are available within '$PHP_INC'";
-d "$PHP_INC/Zend"
}
&Literal{
$failure_msg = "File '$PHP_EXECUTABLE' specified by the " .
"PHP_EXECUTABLE macro is not present or not executable'";
$success_msg = "PHP executable is available as '$PHP_EXECUTABLE'";
-f "$PHP_EXECUTABLE" && -x "$PHP_EXECUTABLE"
}
}
}
xmotif &Arr{
Description X/Motif Graphics toolkit links
Detail &Literal{
The 'xmotif' capability provides linkage to the X/Motif include files and
link libraries on the local machine. These are used within Antelope-contrib
for the dbxcor(1) application as well as supporting libraries such as
libseisw.
}
enable &Arr{
Darwin 0
Linux 0
SunOS 0
}
required_macros &Tbl{
XMOTIFINCLUDE
XMOTIFLIB
}
tests &Tbl{
&Literal{
$failure_msg = "Couldn't find header-file directory '$XMOTIFINCLUDE/Xm' " .
"implied by currently configured value '$XMOTIFINCLUDE' of XMOTIFINCLUDE macro";
$success_msg = "Xmotif include files are available within '$XMOTIFINCLUDE'";
-d "$XMOTIFINCLUDE/Xm"
}
&Literal{
$failure_msg = "Couldn't find library-file directory '$XMOTIFLIB' " .
"implied by currently configured value '$XMOTIFLIB' of XMOTIFLIB macro";
$success_msg = "Xmotif library files are available within '$XMOTIFLIB'";
-d "$XMOTIFLIB"
}
}
}
}
antelope &env(ANTELOPE)
dest &antelope/local/include
extra_rules &Literal{
.SUFFIXES: .SUFFIXES .py .pyc .xpy .xphp .wwwphp
% : %.xpy $(ANTELOPE)/local/data/templates/xpy
$(RM) $@
cat $(ANTELOPE)/local/data/templates/xpy $< > $@
chmod a+x $@
% : %.xphp $(ANTELOPE)/local/data/templates/xphp
$(RM) $@
cat $(ANTELOPE)/local/data/templates/xphp $< > $@
chmod a+x $@
.wwwphp.php : $(ANTELOPE)/local/data/templates/wwwphp
$(RM) $@
cat $(ANTELOPE)/local/data/templates/wwwphp $*.wwwphp > $@
.py.pyc :
$(RM) $@
$(PYTHON_EXECUTABLE) -c 'import py_compile; py_compile.compile("$<")'
}
header &Literal{
# DO NOT MODIFY -- Automatically generated file -- DO NOT MODIFY
#
# This file has been automatically generated by the localmake_config(1) program.
# Run localmake_config(1) to regenerate if necessary.
# See the localmake_config(1) man page for further details.
}
macros &Arr{
PHP_EXECUTABLE &Arr{
Darwin
Description Absolute pathname of PHP interpreter
Detail &Literal{
The PHP_EXECUTABLE macro specifies the absolute
pathname of the PHP interpreter to be used for
the Antelope PHP interface. The PHP_INC
and PHP_EXECUTABLE macros must be set consistent
with each other, i.e. referring to PHP header files
and PHP executable that belong together. An example
value for the PHP_EXECUTABLE macro might be '/usr/bin/php', although
this of course depends on local system configuration.
}
Linux
SunOS
}
PHP_INC &Arr{
Darwin
Description Location of PHP header files
Detail &Literal{
The PHP_INC macro specifies the location of
the include files (header files) for the PHP
interpreter to be used with Antelope (and against which
the Antelope interface to PHP will compile locally).
The directory specified by this macro should contain,
among other things, the sub-directories Zend/, TSRM/, and include/
(at least for versions of PHP current at the time of this writing).
For the Antelope PHP toolbox to work correctly, the include files
specified by the PHP_INC macro must be consistent
with the PHP executable specified by the
PHP_EXECUTABLE macro. An example value for the
PYTHONINCLUDE macro might be '/usr/include/php', although this
of course depends on local system configuration.
}
Linux
SunOS
}
XMOTIFINCLUDE &Arr{
Darwin
Description Location of X-Motif header files
Detail &Literal{
The XMOTIFINCLUDE macro specifies the location
of the include files (header files) for the
X/Motif graphics toolkit. The directory specified
by this macro should contain a subdirectory called Xm/
which has the actual toolkit header files. This macro must
be set to a value which is consistent with the location
given in the XMOTIFLIB macro, i.e. the header files and the
library files pointed to by these two macros must
correspond to each other. An example value for XMOTIFINCLUDE
might be '/usr/openwin/include' on Solaris; sometimes
'/usr/X11R6/include' on Linux; and perhaps '/sw/include' on
Macintosh, if the 'Fink' distribution of X/Motif has been
installed there.
}
Linux /usr/X11R6/include
SunOS /usr/openwin/include
}
XMOTIFLIB &Arr{
Darwin
Description Location of X-Motif link libraries
Detail &Literal{
The XMOTIFLIB macro specifies the location
of the link libraries for the X/Motif graphics toolkit.
This macro must be set to a value which is consistent with
the location given in the XMOTIFINCLUDE macro, i.e. the header
files and the library files pointed to by these two macros must
correspond to each other. An example value for XMOTIFLIB
might be '/usr/openwin/lib' on Solaris; sometimes
'/usr/X11R6/lib' on Linux; and perhaps '/sw/lib' on
Macintosh, if the 'Fink' distribution of X/Motif has been
installed there.
}
Linux /usr/X11R6/lib
SunOS /usr/openwin/lib
}
}
output_file antelopemake.local
EXAMPLE
% localmake -v -t dbxcor
...
localmake: Created package file '2008_03_08_dbxcor_i386_Darwin_tarball.tar.bz2'
%
SEE ALSO
localmake_config(1), antelopemake(5), antelopemakelocal(5)
BUGS AND CAVEATS
The package contents are actually a bit platform-specific, which is not
yet accounted for. For example, dynamic libraries are named differently
on Darwin than on Linux and Solaris.
Inter-package conflicts and dependencies are not accounted for.
The
localmake.pf contents are highly detailed and contingent on insider
knowledge of the piece of software being built. It is intended that these
package descriptions be written by the author of the relevant piece
of code.
The
localmake GUI will restart itself after compiling a module named
bootstrap. The
bootstrap module allows the
localmake
and
localmake_config compilation facility easily updatable between
official Antelope releases.
localmake will sometimes report success in compilation even though it
has failed somewhere along the line. This is due to an internal weakness in the
way it spawns subsidiary make commands, a weakness which could be fixed but at a cost
not yet allocated. Make sure to scan compilation output for evidence of errors (these
should be fairly prominent in the colored-output when running
localmake
as a GUI).
Note that the
product parameter does not control the actual compilation target of
the files in a module. The
product parameter is meant to describe the context in which the
module belongs, to aid software packaging if the
-t option is used, and,
if
src_subdir is a relative path, as an aid to finding the correct source-code files.
The actual install directory for the software is controlled by the Makefiles for the source-code.
The array name for a given module must not contain the string
src_subdir. All top-level parameters
containing
src_subdir in their parameter names are ignored, allowing sophisticated users to use
several of them as parameter-file
bare references (see
pf(5)) when managing multiple repositories
and source-code trees.
The tarball creation code has not been tested after extensive changes, and may no longer work as
advertised.
If a module has elements with paths that start with
nobuild/,
localmake will warn the
user of potential conflicts with Antelope before installing.
AUTHOR
Kent Lindquist
Lindquist Consulting, Inc.
Antelope User Group Contributed Software