Changes between Version 19 and Version 20 of pm-switch


Ignore:
Timestamp:
Feb 20, 2011 2:14:36 PM (9 years ago)
Author:
stefan
Comment:

rename Xxx to Xyz for google; add TOC; less subsections

Legend:

Unmodified
Added
Removed
Modified
  • pm-switch

    v19 v20  
    1 = Brief Tutorial on Switching to the New Buildtools =
    2 
    3 This 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-OR 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-OR 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.
     1[[TOC(depth=2,pm-autotools,pm-autotools-intro,pm-structure-config,pm-base-config,pm-project-config,pm-automake-intro,pm-base-make,pm-project-make,pm-source-make,pm-test-make,pm-get-autotools,pm-switch,pm-comments)]]
     2
     3= Brief Tutorial on Switching from !BuildTools 0.5 to 0.7 =
     4
     5With !BuildTools 0.6, major changes have been made to the COIN-OR build system.
     6This tutorial attempts to explain how to change the existing build system of a project to use the new build system.
     7
     8The major changes are:
     9
     10 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.
     11 1. All dependent projects are treated more or less as "third-party", so that it is now easy to '''link against installed versions of COIN-OR 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-OR 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.
     12 1. The generation of '''doxygen''' documentation has been revised and improved. '''Doxygen tag files''' are now used to create links between the documentation of several projects. The steps to use this new doxygen system are detailed [https://projects.coin-or.org/BuildTools/wiki/pm-doxygen at this page].
    713
    814== What Needs to be Edited ==
    915
    10 For 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:
     16For the purposes of illustration, we shall assume that the project to be switched is Xyz. The project has been checked out with externals in the directory {{{Root/}}} with project source code residing in the directory {{{Root/Xyz}}}. To make the switch, the following files need to be edited:
    1117 * {{{Root/configure.ac}}}
    1218 * {{{Root/Makefile.am}}}
    13  * {{{Root/Xxx/configure.ac}}}
    14  * {{{Root/Xxx/Makefile.am}}}
    15  * {{{Root/Xxx/src/Makefile.am}}}
    16  * {{{Root/Xxx/test/Makefile.am}}}
    17  * {{{Root/Xxx/examples/Makefile.in}}}
     19 * {{{Root/Xyz/configure.ac}}}
     20 * {{{Root/Xyz/Makefile.am}}}
     21 * {{{Root/Xyz/src/Makefile.am}}}
     22 * {{{Root/Xyz/test/Makefile.am}}}
     23 * {{{Root/Xyz/examples/Makefile.in}}}
    1824 * {{{Root/Externals}}}
    1925the following files need to be created:
    20  * {{{Root/Xxx/xxx.pc.in}}}
    21  * {{{Root/Xxx/xxx-uninstalled.pc.in}}}
     26 * {{{Root/Xyz/xyz.pc.in}}}
     27 * {{{Root/Xyz/xyz-uninstalled.pc.in}}}
    2228 * {{{Root/Dependencies}}}
    2329and the following files need to be deleted:
    24  * {{{Root/Xxx/xxx_addlibs.txt.in}}}
     30 * {{{Root/Xyz/xyz_addlibs.txt.in}}}
    2531
    2632For using the new doxygen setup, additionally the files
    2733 * {{{Root/doxydoc/doxygen.conf.in}}}
    28  * {{{Root/Xxx/doxydoc/doxygen.conf.in}}}
     34 * {{{Root/Xyz/doxydoc/doxygen.conf.in}}}
    2935need to be created and the file
    3036 * {{{Root/doxydoc/doxygen.conf}}}
    3137need to be deleted.
    3238
    33 == Externals ==
     39== Externals to Dependencies ==
    3440
    3541Another change with the new setup is that it is now highly recommended to use release versions in your externals. To make this easy, there is a script called {{{set_externals}}} that is part of the build tools that will automatically set your externals. To use it, you maintain a "dependencies" file (usually called {{{Root/Dependencies}}}) as opposed to an "externals" file. The dependencies files will usually contain the stable versions on which a project depends in the same format as the current {{{Externals}}} file. When you run the command {{{set_externals Dependencies}}}, the dependencies files will be parsed and externals set to latest release versions automatically. Note that if your dependencies files contains trunk or specific release versions, these will be used instead, overriding the mechanism for using the latest release version. For example:
     
    5965== Changes to Installation Directories ==
    6066
    61 This is a list where things get installed.
     67This is a list where '''things get installed'''.
    6268
    6369- pkgconfig files (.pc) go to {{{<libdir>/pkgconfig}}}
     
    7783- headers of coin build third party projects go to {{{<includedir>/coin/ThirdParty}}}  [was not installed before]
    7884
    79 Defaults for the above variables are:
     85'''Defaults''' for the above variables are:
    8086
    8187- <prefix> = build directory (the directory where configure is called)
     
    9197- <datadir> = <prefix>/share
    9298
    93 == {{{Root/configure.ac}}} ==
     99== Changes to autotools files ==
     100
     101=== {{{Root/configure.ac}}} ===
    94102
    95103In the {{{Root/configure.ac}}} file, the changes are as follows:
     
    99107 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.
    100108
    101 == {{{Root/Makefile.am}}} ==
     109=== {{{Root/Makefile.am}}} ===
    102110
    103111In the {{{Root/Makefile.am}}} file, the changes are as follows:
     
    106114 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.
    107115
    108 == {{{Root/Xxx/configure.ac}}} ==
    109 
    110  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)}}}.
     116=== {{{Root/Xyz/configure.ac}}} ===
     117
     118 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(Xyz)}}}.
    111119 1. Calls to {{{AC_COIN_HAS_PROJECT()}}} should be replaced with calls to {{{AC_COIN_CHECK_PACKAGE()}}}. There are also three arguments now.
    112120   * The first argument is the name of the "package", which can consist of multiple COIN-OR 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.
     
    116124 1. Calls to the function {{{AC_COIN_HAS_USER_LIBRARY()}}} can generally be replaced with calls to {{{AC_COIN_CHECK_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_CHECK_PACKAGE(Cpx,  [osi-cplex],  [DipLib])}}}.
    117125  Other uses of the macros {{{AC_COIN_HAS_USER_LIBRARY}}} should be renamed to {{{AC_COIN_CHECK_USER_LIBRARY}}}.
    118  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).
    119 
    120 == {{{Root/Xxx/Makefile.am}}} ==
    121 
    122 The 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).[[BR]]
     126 1. The list of files to be created by the configure script (listed as arguments to the {{{AC_CONFIG_FILES}}} command must now include {{{xyz.pc}}} and {{{xyz-uninstalled.pc}}} (see below for a description of the corresponding .in files).
     127
     128=== {{{Root/Xyz/Makefile.am}}} ===
     129
     130The main change here is that we are now replacing the old {{{xyz_addlibs.txt}}} file with {{{xyz.pc}}} and {{{xyz-uninstalled.pc}}} files (see below).[[BR]]
    123131If the pkg-config command is present, an addlibs file can be created in from the {{{.pc}}} files.[[BR]]
    124132If the pkg-config command is not present, then the AC_COIN_CHECK_PACKAGE macro in configure has setup variables that contain the flags for linking against installed dependency libraries.
     
    126134So we have the following changes:
    127135{{{
    128 addlibsfile = xxx_addlibs.txt
     136addlibsfile = xyz_addlibs.txt
    129137addlibsdir = $(prefix)/share/doc/coin/$(PACKAGE_NAME)
    130138}}}
     
    132140{{{
    133141pkgconfiglibdir = $(libdir)/pkgconfig
    134 pkgconfiglib_DATA = xxx.pc
     142pkgconfiglib_DATA = xyz.pc
    135143}}}
    136144The block
     
    144152should be replaced with
    145153{{{
    146 addlibsdir = $(DESTDIR)$(datadir)/coin/doc/Xxx
     154addlibsdir = $(DESTDIR)$(datadir)/coin/doc/Xyz
    147155
    148156install-data-hook:
     
    150158if COIN_HAS_PKGCONFIG
    151159       PKG_CONFIG_PATH=@COIN_PKG_CONFIG_PATH@ \
    152        $(PKG_CONFIG) --libs xxx > $(addlibsdir)/xxx_addlibs.txt
     160       $(PKG_CONFIG) --libs xyz > $(addlibsdir)/xyz_addlibs.txt
    153161else
    154162if COIN_CXX_IS_CL
    155        echo "/libpath:`$(CYGPATH_W) @abs_lib_dir@` libxxx.lib @XXXLIB_LIBS_INSTALLED@" > $(addlibsdir)/xxx_addlibs.txt
     163       echo "/libpath:`$(CYGPATH_W) @abs_lib_dir@` libxyz.lib @XYZLIB_LIBS_INSTALLED@" > $(addlibsdir)/xyz_addlibs.txt
    156164else
    157        echo -L@abs_lib_dir@ -lxxx @XXXLIB_LIBS_INSTALLED@ > $(addlibsdir)/xxx_addlibs.txt
     165       echo -L@abs_lib_dir@ -lxyz @XYZLIB_LIBS_INSTALLED@ > $(addlibsdir)/xyz_addlibs.txt
    158166endif
    159167endif
    160168
    161169uninstall-hook:
    162         rm -f $(addlibsdir)/xxx_addlibs.txt
    163 }}}
    164 
    165 == {{{Root/Xxx/xxx.pc.in}}}==
     170        rm -f $(addlibsdir)/xyz_addlibs.txt
     171}}}
     172
     173=== {{{Root/Xyz/xyz.pc.in}}} ===
    166174
    167175This is the template for the pkg-config file that will be produced at configure time. It has a very simple form something like the following.
     
    172180includedir=@includedir@/coin
    173181
    174 Name: Xxx
    175 Description: Xxx does nothing useful
     182Name: Xyz
     183Description: Xyz does nothing useful
    176184Version: @PACKAGE_VERSION@
    177 Libs: -L${libdir} -lXxx @XXXLIB_PCLIBS@
     185Libs: -L${libdir} -lXyz @XYZLIB_PCLIBS@
    178186Cflags: -I${includedir}
    179 Requires: @XXXLIB_PCREQUIRES@
    180 }}}
    181 
    182 == {{{Root/Xxx/xxx-uninstalled.pc.in}}}==
     187Requires: @XYZLIB_PCREQUIRES@
     188}}}
     189
     190=== {{{Root/Xyz/xyz-uninstalled.pc.in}}} ===
    183191
    184192This the pkg-config file for finding uninstalled versions of a given library built from source.
    185193In difference to above, we use here path's in the build directory.
    186194Further, instead of specifying linker flags via -L and -l, we list here the .la file with full path explicitly.
    187 This is necessary to setup the DEPENDENCIES variable in the Makefile's that use project Xxx.
     195This is necessary to setup the DEPENDENCIES variable in the Makefile's that use project Xyz.
    188196{{{
    189197prefix=@prefix@
     
    191199includedir=@includedir@/coin
    192200
    193 Name: Xxx
    194 Description: Xxx does nothing useful
     201Name: Xyz
     202Description: Xyz does nothing useful
    195203Version: @PACKAGE_VERSION@
    196 Libs: ${libdir}/libXxx.la @XXXLIB_PCLIBS@
     204Libs: ${libdir}/libXyz.la @XYZLIB_PCLIBS@
    197205Cflags: -I@abs_source_dir@/src -I@ABSBUILDDIR@/inc
    198 Requires: @XXXLIB_PCREQUIRES@
    199 }}}
    200 
    201 == {{{Root/Xxx/src/Makefile.am}}} ==
     206Requires: @XYZLIB_PCREQUIRES@
     207}}}
     208
     209=== {{{Root/Xyz/src/Makefile.am}}} ===
    202210
    203211The main difference in the construction of the various {{{Makefile.am}}} files is that not so much work has to be done now to build up the command lines and lists of dependent libraries. This is all done automatically. For each package Yyy defined in {{{configure.ac}}}, there are now four variables: {{{YYY_CFLAGS}}}, {{{YYY_LIBS}}}, {{{YYY_DEPENDENCIES}}}, and {{{YYY_DATA}}} that hold the flags for compiling individual C and C++ files (i.e., the include paths, etc.), the linker flags for linking to dependent libraries, a list of dependent libraries (not using -l or -L syntax), and the directory where a project may store data, respectively. The situation will be slightly different for each project, but for the most part, we can replace blocks like
     
    222230myprog_DEPENDENCIES = $(COINDEPEND_DEPENDENCIES)
    223231}}}
    224 Note that the names of the variables correspond exactly to the names given to the libraries and binaries in the third argument {{{AC_COIN_CHECK_PACKAGE()}}}, as described in the section on the {{{Root/Xxx/configure.ac}}} file above. Hence, the command {{{AC_COIN_CHECK_PACKAGE(CoinDepend, [coinutils >= 2.7 osi >= 0.104 alps >= 1.2], [XxxLib])}}} will result in the libraries and flags for each of those dependencies being put into variables called {{{XXXLIB_LIBS}}} and {{{XXXLIB_CFLAGS}}} respectively.
     232Note that the names of the variables correspond exactly to the names given to the libraries and binaries in the third argument {{{AC_COIN_CHECK_PACKAGE()}}}, as described in the section on the {{{Root/Xyz/configure.ac}}} file above. Hence, the command {{{AC_COIN_CHECK_PACKAGE(CoinDepend, [coinutils >= 2.7 osi >= 0.104 alps >= 1.2], [XyzLib])}}} will result in the libraries and flags for each of those dependencies being put into variables called {{{XYZLIB_LIBS}}} and {{{XYZLIB_CFLAGS}}} respectively.
    225233
    226234Further, there is no longer any {{{ADDLIBS}}} variable defined, as the additional libraries are all included as dependencies when the lists of libraries are built up.
    227235
    228 == {{{Root/Xxx/test/Makefile.am}}} ==
     236=== {{{Root/Xyz/test/Makefile.am}}} ===
    229237
    230238The changes here are similar to those described above.
    231239
    232 == {{{Root/Xxx/examples/Makefile.in}}} ==
     240=== {{{Root/Xyz/examples/Makefile.in}}} ===
    233241
    234242The changes to the examples Makefile's are more involved, since compiler and linker flags are assembled differently, depending on whether pkg-config is available or not. Supporting a build under cygwin with cl messes up the Makefile additionally.[[BR]]
     
    337345Next we setup the include-flags.
    338346Again, we distinguish between a setup where pkg-config is available (and thus is used to check for compiler flags) and where it is not available.
    339 In the latter case, the AC_COIN_CHECK_PACKAGE macro should have setup a variable XXXLIB_CFLAGS_INSTALLED.
     347In the latter case, the AC_COIN_CHECK_PACKAGE macro should have setup a variable XYZLIB_CFLAGS_INSTALLED.
    340348{{{
    341349ifeq ($(COIN_HAS_PKGCONFIG), TRUE)
    342   INCL = `PKG_CONFIG_PATH=@COIN_PKG_CONFIG_PATH@ @PKG_CONFIG@ --cflags xxx`
     350  INCL = `PKG_CONFIG_PATH=@COIN_PKG_CONFIG_PATH@ @PKG_CONFIG@ --cflags xyz`
    343351else
    344   INCL = @XXXLIB_CFLAGS_INSTALLED@
     352  INCL = @XYZLIB_CFLAGS_INSTALLED@
    345353endif
    346354INCL += $(ADDINCFLAGS)
     
    349357Finally, the linker flags containing all library dependencies.
    350358If pkg-config is available, then we use it to request the dependencies.
    351 If it is not available, then AC_COIN_CHECK_PACKAGE has setup a variable XXXLIB_LIBS_INSTALLED that contains all dependencies of our project.
     359If it is not available, then AC_COIN_CHECK_PACKAGE has setup a variable XYZLIB_LIBS_INSTALLED that contains all dependencies of our project.
    352360Additionally, we need to list the library of our project.
    353361Since the cl and icl compiler use a different syntax, we have to distinguish here between which type of compiler is used.
    354 For the XXXLIB_LIBS_INSTALLED variable, configure has already done this.
     362For the XYZLIB_LIBS_INSTALLED variable, configure has already done this.
    355363{{{
    356364# Linker flags
    357365ifeq ($(COIN_HAS_PKGCONFIG), TRUE)
    358   LIBS = `PKG_CONFIG_PATH=@COIN_PKG_CONFIG_PATH@ @PKG_CONFIG@ --libs xxx`
     366  LIBS = `PKG_CONFIG_PATH=@COIN_PKG_CONFIG_PATH@ @PKG_CONFIG@ --libs xyz`
    359367else
    360368  ifeq ($(COIN_CXX_IS_CL), TRUE)
    361     LIBS = /link /libpath:`$(CYGPATH_W) @abs_lib_dir@` libXxx.lib @XXXLIB_LIBS_INSTALLED@
     369    LIBS = /link /libpath:`$(CYGPATH_W) @abs_lib_dir@` libXyz.lib @XYZLIB_LIBS_INSTALLED@
    362370  else
    363     LIBS = -L@abs_lib_dir@ -lXxx @XXXLIB_LIBS_INSTALLED@
     371    LIBS = -L@abs_lib_dir@ -lXyz @XYZLIB_LIBS_INSTALLED@
    364372  endif
    365373endif
     
    402410        $(CC) $(CFLAGS) $(INCL) -c -o $@ `if test -f '$<'; then $(CYGPATH_W) '$<'; else $(CYGPATH_W) '$(SRCDIR)/$<'; fi`
    403411}}}
    404 
    405 == Doxygen documentation ==
    406 
    407 See [https://projects.coin-or.org/BuildTools/wiki/pm-doxygen here].