Changes between Version 1 and Version 2 of pm-switch


Ignore:
Timestamp:
Oct 26, 2010 7:09:56 PM (9 years ago)
Author:
tkr
Comment:

--

Legend:

Unmodified
Added
Removed
Modified
  • pm-switch

    v1 v2  
    11= Brief Tutorial on Switching to the New Buildtools =
    22
    3 This tutorial attempts to explain how to make the switch to the new stable version of the build tools. It is necessarily incomplete and
     3This tutorial attempts to explain how to make the switch to the new stable version of the build tools. The major changes with this release of build tools are:
     4
     5 1. Support for the {{{pkg-config}}} command to build lists of dependencies and command line options. Configuration files associated with pkg-config are used when the {{{pkg-config}}} command is present.
     6 1. All dependent projects are treated more or less as "third-party," so that it is now easy to link against installed version of COIN projects (using pkg-config if it is available). This also means that What were truly "third-party" projects are now treated more or less the same as COIN projects. We provide build, pkg-config, and install support for these projects if source is available and otherwise provide a mechanism for linking to installed libraries, as before.
    47
    58== What Needs to be Edited ==
     
    710For the purposes of illustration, we shall assume that the project to be switched is Xxx. The project has been checked out with externals in the directory {{{Root/}}} with project source code residing in the directory {{{Root/Xxx}}}. To make the switch, the following files need to be edited:
    811 * {{{Root/configure.ac}}}
     12 * {{{Root/Makefile.am}}}
    913 * {{{Root/Xxx/configure.ac}}}
    1014 * {{{Root/Xxx/Makefile.am}}}
    1115 * {{{Root/Xxx/src/Makefile.am}}}
     16 * {{{Root/Xxx/test/Makefile.am}}}
    1217 * {{{Root/Externals}}}
    1318and the following files need to be created:
     
    6267== {{{Root/configure.ac}}} ==
    6368
     69In the {{{Root/configure.ac}}} file, the changes are as follows:
     70
     71 1. Calls to {{{AC_COIN_MAIN_SUBDIRS()}}} should generally be changed to {{{AC_COIN_MAIN_PACKAGEDIR()}}}. For example, {{{AC_COIN_MAIN_SUBDIRS(CoinUtils)}}} => {{{AC_COIN_MAIN_PACKAGEDIR(CoinUtils)}}}
     72 1. Calls to {{{AC_COIN_THIRDPARTY_SUBDIRS()}}} should '''also''' be changed to {{{AC_COIN_MAIN_PACKAGEDIR()}}} (these packages are treated more or less the same way as COIN packages now). One difference between COIN projects and third part projects is that the source is that the source is typically checked out into a subdirectory {{{ThirdParty}} to make the separation clear. There is also a mechanism for checking to make sure that the project source is actually present (since this has to be downloaded separately by the user using the {{{getYyy}}} script. These capabilities are implemented using the optional second, third, and fourth arguments of {{{AC_COIN_MAIN_PACKAGEDIR()}}}, similar to the arguments of {{{AC_COIN_THIRDPARTY_SUBDIRS()}}} previously. The second argument denotes the subdirectory in which the project is to be found, the third argument is a file to check for to make sure that the source is present, and the fourth argument is the name of the pkg-config package associated with the installed library. So for BLAS, the call would be {{{AC_COIN_MAIN_PACKAGEDIR(Blas,ThirdParty,[daxpy.f],coinblas)}}}.
     73 1. Note also that most calls to {{{AC_COIN_HAS_USER_LIBRARY()}}} for libraries like CPLEX are not needed in the {{{configure.ac}}} files in the root directory of higher-level projects, as these checks are made in the configure script of {{{Osi}}} and the list of libraries needed on the link line is automatically constructed and passed on to the higher-level project.
     74
     75== {{{Root/Makefile.am}}} ==
     76
     77In the {{{Root/Makefile.am}}} file, the changes are as follows:
     78
     79 1. The {{{SUBDIRS}}} variables dos not need to set to an explicit list of dependencies, the available subdirectories are determined automatically according to which projects are present in source form. So the command {{{SUBDIRS = $(subdirs)}}} replaces any command setting the value of {{{SUBDIRS}}} that was previously present.
     80 1. The command {{{DISTCLEANFILES = coin_subdirs.txt}}} should be set to clean up the file in which the list of subdirectories was written. Previously, this variable was set to the empty string.
     81
     82== {{{Root/Xxx/configure.ac}}} ==
     83
     84 1. The function {{{AC_COIN_PROJECTDIR_INIT}}} now takes as an argument the name of the project, so the call would now be {{{AC_COIN_PROJECTDIR_INIT(Xxx)}}}.
     85 1. Calls to {{{AC_COIN_HAS_PROJECT()}}} should be replaced with calls to {{{AC_COIN_HAS_PACKAGE()}}}. There are also three arguments now.
     86   * The first argument is the name of the "package", which can consist of multiple COIN projects. For example, one can defined a "package" consisting of both CoinUtils and Clp, called {{{CoinDepend}}} and make the configuration bail out when any component of the package is not present. This mechanism is meant for cases in which a project is not useful by itself, but only in combination with others.
     87   * The second argument are the names the pkg-config files associated with the projects that make up the package, with the optional ability to specify specific required versions (see example below).
     88   * The third argument can be used to specify a particular library or binary to which the particular dependency applies. This is for cases where the project exports both a library and a binary executable and these have different dependencies. In this case, different command lines are built up for each of them separately.
     89   * An example of how this comes together is the call {{{AC_COIN_HAS_PACKAGE(CoinDepend, [coinutils = trunk osi = trunk alps = trunk], [DipLib])}}}, which defines a package called {{{CoinDepend}}} that consists of the trunk versions of !CoinUtils, Osi, and Alps. The dependency applies to the Dip library. We'll see below how this specification comes to play in the Makefiles.
     90 1. Calls to the function {{{AC_COIN_HAS_USER_LIBRARY()}}} can generally be replaced with calls to {{{AC_COIN_HAS_PACKAGE()}}} if they apply to solvers to be used through Osi. This is because the {{{OsiYyy}}} packages now have pkg-config support. So the call to check for the presence of CPLEX, for example, is now {{{AC_COIN_HAS_PACKAGE(Cpx,  [osi-cplex],  [DipLib])}}}.
     91 1. The list of files to be created by the configure script (listed as arguments to the {{{AC_CONFIG_FILES}}} command must now include {{{Xxx.pc}}} and {{{Xxx-uninstalled.pc}}} (see below for a description of the corresponding .in files).
     92
     93== {{{Root/Makefile.am}}} ==
     94
     95The main change here is that we are now replacing the old {{{xxx_addlibs.txt}}} file with {{{xxx.pc}}} and {{{xxx-uninstalled.pc}}} files (see below). If the pkg-config command is present, an addlibs file can be created in the old style from the {{{.pc}}} files. So we have the following changes:
     96{{{
     97addlibsfile = xxx_addlibs.txt
     98addlibsdir = $(prefix)/share/doc/coin/$(PACKAGE_NAME)
     99}}}
     100should be replaced with
     101{{{
     102pkgconfiglibdir = $(libdir)/pkgconfig
     103pkgconfiglib_DATA = xxx.pc
     104}}}
     105The block
     106{{{
     107install-exec-local: install-doc
     108        $(install_sh_DATA) $(addlibsfile) $(DESTDIR)$(addlibsdir)/$(addlibsfile)
     109
     110uninstall-local: uninstall-doc
     111        rm -f $(addlibsdir)/$(addlibsfile)
     112}}}
     113should be replaced with
     114{{{
     115if COIN_HAS_PKGCONFIG
     116addlibsdir = $(DESTDIR)$(datadir)/coin/doc/Xxx
     117
     118install-data-hook:
     119       @$(mkdir_p) "$(addlibsdir)"
     120       PKG_CONFIG_PATH=@COIN_PKG_CONFIG_PATH@ \
     121       $(PKG_CONFIG) --libs dip > $(addlibsdir)/dip_addlibs.txt
     122
     123uninstall-hook:
     124        rm -f $(addlibsdir)/dip_addlibs.txt
     125endif
     126}}}
     127