Changes between Version 2 and Version 3 of pm-pcfile


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

document .pc files and how they are used and setup in COIN-OR

Legend:

Unmodified
Added
Removed
Modified
  • pm-pcfile

    v2 v3  
    33= The pkg-config configuration files of a project =
    44
    5 This page need to be filled with content about
    6 * what are .pc files
    7 * how can they be used
    8 * how are prjct.pc files of a COIN-OR project created
    9 * how are prjct-uninstalled.pc files of a COIN-OR project created
     5COIN-OR uses [http://en.wikipedia.org/wiki/Pkg-config pkg-config] to '''check for dependencies''' of COIN-OR projects, to '''communicate compiler and linker flags''' that are required to build and link against other projects, and to provide an easy way for users to build and link against COIN-OR projects.
     6
     7== Introduction ==
     8
     9The way it works is that each project provides one or several pkg-config configuration files (so called '''{{{.pc}}} files''') which contain all necessary information to build and link against a particular library, especially compiler flags that specify the location of header files, linker flags that specify location and names of libraries, and a list of dependencies of that this library depends on.
     10
     11For example, the {{{clp.pc}}} file of the Clp library may look like this:
     12{{{
     13prefix=/home/johndoe/Coin-Clp/build
     14exec_prefix=${prefix}
     15libdir=${exec_prefix}/lib
     16includedir=${prefix}/include/coin
     17
     18Name: CLP
     19Description: COIN-OR Linear Programming Solver
     20URL: https://projects.coin-or.org/Clp
     21Version: 1.14.0
     22Libs: -L${libdir} -lClp
     23Cflags: -I${includedir}
     24Requires: coinutils
     25}}}
     26
     27The variable specifications at the top are only used inside the {{{.pc}}} file to simplify the specifications in the {{{Libs}}} and {{{Cflags}}} fields.
     28The '''{{{Requires}}} field''' gives a list of projects by their {{{.pc}}} file name which the Clp library depends on. Here, this is only !CoinUtils, which, of course, may have several further dependencies by its own.
     29
     30The information from a {{{.pc}}} file can be accessed via the tool {{{pkg-config}}}.
     31The tool searches the paths given in the '''environment variable {{{PKG_CONFIG_PATH}}}''' for the {{{.pc}}} files that correspond to given package name.[[BR]]
     32For example, the command
     33{{{
     34pkg-config --exists clp >= 1.13
     35}}}
     36checks whether a Clp library with version at least 1.13 is available. The specification of version number(s) is optional.[[BR]]
     37The command
     38{{{
     39pkg-config --cflags clp
     40}}}
     41returns the C/C++ compiler flags that are necessary to build against the Clp library ''and it's dependencies'', i.e., the location of the !CoinUtils and Clp header files.[[BR]]
     42The command
     43{{{
     44pkg-config --libs clp
     45}}}
     46returns the linker flags that are necessary to link against the Clp library ''and it's dependencies'', i.e., the location of the !CoinUtils and Clp library, their names, and the linker flags of the !CoinUtils dependencies, e.g., Blas, Lapack, Glpk.
     47
     48The COIN-OR autoconf macro {{{AC_COIN_CHECK_PACKAGE}}} uses these commands (if pkg-config is available) to retrieve information which packages are available and how to build and link against them.
     49
     50== The .pc file of an installed COIN-OR project library ==
     51
     52If a COIN-OR project provides a library {{{xyz}}} that is also installed, then it should also provide a file {{{xyz.pc.in}}} file that can be transformed into a {{{.pc}}} file by configure and contains information on how to compile and link against the ''installed version'' of the library.
     53
     54A typical {{{xyz.pc.in}}} file may be
     55{{{
     56prefix=@prefix@
     57exec_prefix=@exec_prefix@
     58libdir=@libdir@
     59includedir=@includedir@/coin
     60
     61Name: Xyz
     62Description: COIN-OR Xyz
     63URL: https://projects.coin-or.org/Xyz
     64Version: @PACKAGE_VERSION@
     65Libs: -L${libdir} -lXyz @XYZ_PCLIBS@
     66Cflags: -I${includedir}
     67Requires: @XYZ_PCREQUIRES@
     68}}}
     69The variables {{{prefix}}}, {{{exec_prefix}}}, {{{libdir}}}, and {{{includedir}}} are setup from default configure variables.
     70The {{{Version}}} field is setup to contain the value of {{{@PACKAGE_VERSION@}}}. This variable holds the value of the second parameter of the {{{AC_INIT}}} macro in the [wiki:pm-structure-config#Beginningofaconfigure.acfile beginning of the configure.ac file].
     71The {{{Libs}}} and {{{Requires}}} fields make use of the variables {{{@XYZ_PCLIBS@}}} and {{{@XYZ_PCREQUIRES@}}} variables as they are setup by the [wiki:pm-project-config#CheckforotherCOIN-ORComponents AC_COIN_CHECK_* macros] in the configure.ac file. They contain an accumulated list of dependencies in form of linker flags and names of {{{.pc}}} files, respectively.
     72
     73The {{{xyz.pc.in}}} file is translated into a {{{xyz.pc}}} file by replacing all {{{@...@}}} variables by their value as computed by configure, if the {{{xyz.pc.in}}} file is listed in the {{{AC_CONFIG_FILES}}} macro at
     74[wiki:pm-structure-config#TheEndoftheconfigure.acFile the end of the configure.ac file].
     75When "{{{make install}}}" is executed, it should be installed together with the {{{Xyz}}} library into the directory {{{$(libdir)/pkgconfig}}} as described [wiki:pm-project-make#TheProjectMainDirectoryMakefile.amFile here].
     76
     77== The .pc file an uninstalled COIN-OR project library ==
     78
     79In the classical setup, a user checks out a COIN-OR base directory of a project with the source of that project ''and all dependencies'', then configures all projects, builds them, and finally installs them.
     80Thus, at the time configure is executed for a project, its dependencies have been configured, but not yet been build and installed.
     81Therefore, one needs to '''build against an ''uninstalled'' version of a dependency'''.
     82
     83Using pkg-config and .pc files, the distinction between building against installed or uninstalled versions of a dependency can be done mostly transparent for the project.
     84All it requires is that each dependency {{{xzy}}} '''additionally provides a file {{{xyz-uninstalled.pc.in}}}''' that contains information on how to compile and link against the uninstalled version of {{{xyz}}}.
     85
     86When pkg-config is asked about information about a project {{{xyz}}}, it checks for both files {{{xyz-uninstalled.pc}}} and {{{xyz.pc}}} (in this order), so that from the user-side there is no distinction between the build against an uninstalled or an installed library.
     87
     88A typical {{{xyz-uninstalled.pc.in}}} file has the form
     89{{{
     90prefix=@prefix@
     91libdir=@ABSBUILDDIR@/src
     92
     93Name: Xyz
     94Description: COIN-OR Xyz
     95URL: https://projects.coin-or.org/Xyz
     96Version: @PACKAGE_VERSION@
     97Libs: ${libdir}/libXyz.la @XYZLIB_PCLIBS@
     98Cflags: -I@abs_source_dir@/src -I@ABSBUILDDIR@/inc
     99Requires: @XYZLIB_PCREQUIRES@
     100}}}
     101In difference to the {{{xyz.pc.in}}} file, the {{{libdir}}} is now not set to the library installation directory {{{@libdir@}}}, but the '''directory where the library is build''': {{{@ABSBUILDDIR@/src}}}. The variable @ABSBUILDDIR@ is automatically setup by configure (in the AC_COIN_FINALIZE macro) to contain the absolute path to the project's build directory.
     102
     103In the '''{{{Libs}}} field''', we now do not use {{{-L/-l}}} notation to specify the library path and name, but provide the name of the libraries libtool auxiliary file ({{{.la}}}) with full (absolute) path.
     104The reason is that this way the value in the {{{Libs}}} field can be used to setup the {{{_DEPENDENCIES}}} variable of a binary in a {{{Makefile.am}}}, see [wiki:pm-source-make#SpecifyingLinkingFlags here].
     105Since the location of a build library depends on whether a shared or static library is build and since the {{{xyz-uninstalled.pc}}} files are not meant for use outside of COIN-OR, it is ok to specify an {{{.la}}} file here.
     106
     107In the '''{{{Cflags}}} field''', we specify the location of header files before the project is installed.
     108The variable {{{@abs_source_dir@}}} is thereby setup by configure to contain the absolute path of the projects main directory.
     109Note that next to the {{{src}}} subdirectory, we also specify the {{{inc}}} directory which contains the {{{config_xyz.h}}} file. (This is likely to change in the future.)
     110
     111The {{{xyz-uninstalled.pc.in}}} file is translated into a {{{xyz-uninstalled.pc}}} file by replacing all {{{@...@}}} variables by their value as computed by configure, if the {{{xyz-uninstalled.pc.in}}} file is listed in the {{{AC_CONFIG_FILES}}} macro at
     112[wiki:pm-structure-config#TheEndoftheconfigure.acFile the end of the configure.ac file].
     113In order to allow other projects to find this file, it is assumed that it is put into the main build directory of the project.
     114It should not be installed.
     115
     116As an example, the {{{clp-uninstalled.pc}}} file as generated by configure may be
     117{{{
     118prefix=/home/johndoe/Coin-Clp/build
     119libdir=/home/johndoe/Coin-Clp/build/Clp/src
     120
     121Name: CLP
     122Description: COIN-OR Linear Programming Solver
     123URL: https://projects.coin-or.org/Clp
     124Version: 1.14.0
     125Libs: ${libdir}/libClp.la
     126Cflags: -I/home/johndoe/Coin-Clp/build/Clp/src -I/home/johndoe/Coin-Clp/build/Clp/inc
     127Requires: coinutils
     128}}}
     129
     130== The NO pkg-config case ==
     131
     132One requirement when upgrading the build system to use {{{.pc files}}} was that it should still be usable with a basic set of unix tools as before.
     133I.e., the basic setup where one checks out and builds a project with all its dependencies from source needed to be kept working also if pkg-config is not available or it's use has been disabled by the user ({{{configure --disable-pkg-config}}}).
     134
     135Therefore, the COIN-OR build system contains some '''fallback macros which parse {{{.pc}}} files by simple shell scripting'''.
     136Of course, this comes with '''limitations''', which are:
     137* It is not possible to build against installed versions of other projects, i.e., the macro ignores {{{PKG_CONFIG_PATH}}} and searches only in the configure directories setup by a [wiki:pm-base-config project's base configure file].
     138
     139* The syntax in the {{{xyz-uninstalled.pc}}} file that can be processed by the macro may be limited. When the macro wants to retrieve compiler and linker flags, it replaces the string {{{Cflags: }}} and {{{Libs: }}} by an {{{echo}}} command, then eliminates all remaining lines that start with a string of the form {{{[A-Za-z]*:}}}, and finally execute the resulting file as shell script.
     140
     141* The Makefiles for examples require the flags to compile and link against the ''installed'' version of a package.
     142  While in a setup with pkg-config, the .pc files can be processed by pkg-config at the time an example is build, this is not possible in a no-pkg-config setup.
     143  However, since the fallback macro already process {{{xyz-uninstalled.pc}}} files, it has been extended to process also {{{xyz.pc}}} files ''before'' there are installed. This requires that configure writes the {{{xyz.pc}}} files also into the main directory of project xyz.