• Antelope Release 5.5 Mac OS X 10.8.5 2015-04-21

 

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

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

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
Printer icon