pkg-config .pc file format
Guide to pkg-config
Introduction
When creating a package written in C or C++, it is possible to define compiling and link information using a .pc file. This file defines command line options such as -I and -L that are used to ensure proper compilation and link processes.
The file format is very similar to a control file, although in most cases variables are defined first, then fields and empty lines are allowed. Note that the standard also (as far as I know) requires a variable to already exist before being referenced. Our field loader loads everything first and then applies variable references so we do not have that requirement.
Variables
The variables are free form, although in most cases .pc files include the following few:
- prefix — a prefix used as the root for all the other files
- exec_prefix — a prefix used by executables (binaries)
- includedir — the path to header files for libraries (.h files)
- libdir — the path to libraries for linking (.so and .a files)
The wpkg implementation provides a set of variables as defined in the pkg-config support page. There is a brief list of those variables:
rootdir, admindir, instdir, name, version, description, homepage, install_prefix
These variables should be used instead of @VARNAME@ replacements at compile time. One main issue with wpkg packages is that they are installed in a target for which the path cannot be known at compile time. Because of that, the location of files on a target is and remains dynamic. The ${instdir} and ${install_prefix} must be used in combinaison to defined the main ${prefix} variable:
prefix=${instdir}${install_prefix}
It should then be possible to define all the other paths from the ${prefix} variable. For example, the headers are most often found in the include directory:
includedir=${prefix}/include
Other Variables
Note that all the variables defined by default in wpkg are also available here. For example, the ${NewLine} variable is still available and also all the C-like expressions can be used. Of course, it is unlikely that it will be useful at this point.
Fields
Then the file format accepts fields. These are defined very much the same way as the fields in a control file: a name, a colon, and a value. There can be spaces between the colon and the value.
The supported fields are defined below:
| Field Name | Expected Content | Comments |
|---|---|---|
|
|
The equivalent of ${name}, but it cannot use a variable defined by wpkg. | One project may define multiple modules. This field is used to reference the project itself from each module. For example, the libutf8 in wpkg has its own .pc file and it defines the Source-Project field with the name wpkg. |
| Name | The name of this module. This is most often set to ${name}. | If your project has just one library, then this is likely the contents of ${name} which is the same as the Package field. If you have multiple libraries, then this is the exact name of the library. |
| Cflags | List of compile time flags. Most often the -I flag is set with the ${includedir} variable. | This field most often defines C and C++ command line flags used to compile another project against your library. For instance, you may define the -I option to define the location of some header files. wpkg does just that as its libraries are defined under a wpkg directory: -I/usr/include/wpkg. |
| Libs | List of link time flags. Most often the -L flag is set with the ${libdir} variable | This field most often defines C and C++ command line flags used to link projects against your library. This includes the -L flag with special paths if necessary and the -l flag with the name of your library. For example the wpkg library uses the -ldebpackages to allow you to link against the main library of the project. |
| Libs.private | Not supported yet. | This field lists libraries used by this project but do not need to be linked against by the other packages. |
| Version | The version of the package. You should always use ${version} for this field. | This field does not seem to be marked as mandatory, although it certainly should be and it should be set to your package version which is defined in the ${version} variable which is taken from the Version field from the control file of the linked package. |
| Description | The description of the package. If this .pc file is the main one describing your project, then use ${description} | This field is expected to describe what this package is for. By default you should use the ${description} which is defined as the short Description of the package. However, if you define multiple .pc files for your project, as we have in wpkg with libexpr and libutf8, then specific descriptions should be used instead of the default. Note that this description should be short but there is no limit. |
| URL | The URI to a website about this project. Use ${homepage} for this field. | This is a valid URI to your project's website. It is expected to always be set to the ${homepage} variable. However, the ${homepage} variable is defined only if the main control file of the project includes a Homepage field. If so, however, it will be easier to define that URI in a single location instead of many, especially if it needs update from time to time. |
| Provides | Not supported yet. | This field is not yet supported. |
| Requires | Not supported yet. | This field lists dependencies. The list is defined as package names separated by spaces and optionally followed by an operator and a version. This is very similar to the Depends field without the parenthesis or the commas. |
| Requires.private | Not supported yet. | This field lists dependencies that are only necessary at compile time. |
| Conflicts | Not supported yet. | This field lists packages in conflict with this package. The list is defined as package names separated by spaces and optionally followed by an opeartor and a version. This is very similar to the Conflicts field without the parenthesis or the commas. |
Examples
The wpkg.pc file is defined as follow:
prefix=${instdir}${install_prefix}
exec_prefix=${prefix}
includedir=${prefix}/include
libdir=${exec_prefix}/lib
Name: ${name}
Cflags: -I${includedir}/wpkg -I${includedir}
Libs: -L${libdir} -ldebpackages
Version: ${version}
Description: ${description}
URL: ${homepage}
The libutf8.pc file is defined as follow:
prefix=${instdir}${install_prefix}
exec_prefix=${prefix}
includedir=${prefix}/include
libdir=${exec_prefix}/lib
Source-Project: wpkg
Name: libutf8
Cflags: -I${includedir}/wpkg -I${includedir}
Libs: -L${libdir} -lutf8
Version: ${version}
Description: Library used to convert UTF-8 to wide characters (UTF-16 or UCS-4)
URL: ${homepage}
The libexpr.pc file is defined as follow:
prefix=${instdir}${install_prefix}
exec_prefix=${prefix}
includedir=${prefix}/include
libdir=${exec_prefix}/lib
Source-Project: wpkg
Name: libexpr
Cflags: -I${includedir}/wpkg -I${includedir}
Libs: -L${libdir} -lexpr
Version: ${version}
Description: Library used to compute C-like expressions.
URL: ${homepage}
Notice how we use internally defined variables in most places so that way we do not have to use @VARNAME@ at compile time. This will even allow you to move your installation target on your hard drive and still have everything working.
