-
Notifications
You must be signed in to change notification settings - Fork 14
Home
This is a copy of the README.txt file included in the source.
pykg-config
==================
A pkg-config replacement.
pykg-config is an input- and output-compatible implementation of pkg-config
written in Python for greater ease of portability. It is designed to be a
drop-in replacement: command lines that work for pkg-config should produce
identical output from pykg-config.
Requirements
-————-
pykg-config uses the new string formatting operations that were introduced in
Python 2.6. It will not function with an earlier version of Python. It has not
been tested with Python 3 and it is likely that several changes will be
necessary to make it function using this version of Python.
Installation
-————-
There are several methods of installation available:
1. Download the source (either from the repository or a source archive),
extract it somewhere, and run pykg-config from that directory.
2. Download the source (either from the repository or a source archive),
extract it somewhere, and use distutils to install it into your Python
distribution:
3. Use the Windows installer. This will perform the same job as running
setup.py (see #2), but saves opening a command prompt. You may still need to
add paths to your environment variables
Under Unix-like operating systems, if you do not already have the original
pkg-config available, you should create a symbolic link to pykg-config. This
allows build system scripts that look for pkg-config to find pykg-config
without modification. Place this link somewhere in your path. For example,
assuming pykg-config was installed to /usr/local:
$ ln -s /usr/local/bin/pykg-config.py /usr/local/bin/pkg-config
On Windows, a batch file, pkg-config.bat, is installed along with pykg-config
into the Scripts directory. This should function as a drop-in replacement for
pkg-config in build system scripts, such as CMake’s UsePkgConfig.cmake module,
provided that this directory is in your PATH environment variable.
Package paths
-—————
Paths are searched in this order:
1. All paths listed in the PKG_CONFIG_PATH environment variable.
2. All paths listed in the PKG_CONFIG_LIBDIR environment variable, if set.
Otherwise, all paths in ${prefix}/lib64/pkgconfig/ and
${prefix}/share/pkgconfig/, where ${prefix} is a system prefix (typically
this will be /usr/).
3. On Windows, the registry keys
HKEY_CURRENT_USER\Software\pkg-config\PKG_CONFIG_PATH and
HKEY_LOCAL_MACHINE\Software\pkg-config\PKG_CONFIG_PATH. For both of these,
paths should be set as values of the key. The value name has no meaning to
pkg-config; use it for your own reference. The value type must be REG_SZ (a
string), and the data should be a single path.
If you are using Windows, I recommend you add paths to PKG_CONFIG_PATH. This is
the easiest place to add paths to and the easiest to check for errors. Google
can tell you how to add an environment variable in Windows. Unfortunately,
because Windows does not have a centralised directory structure, you will
probably have to add every package you install to this variable. If you are
lucky, some nice packages will do it when they are installed, but I haven’t
yet seen one that does this.
pkg-config (.pc) file things-to-watch-out-for
-—————————————————————
The pkg-config format does not deal with spaces in values very well. If you
have an include or lib path with a space in it (common on Windows), pkg-config
will cheerfully treat up to the first space as an include or lib path, and
then ignore all remaining words. This is despite correctly parsing the file
with escaped spaces (the final value processing step is where it drops the
rest).
By contrast, pykg-config uses Python’s shlex module to split values,
preserving things like escaped spaces. This is an advantage on Windows
(provided your .pc files properly escape their spaces), but does mean output
is incompatible with pkg-config.
In the interest of user-friendliness, on Windows, full compatibility is
disabled by default (i.e. paths with escaped spaces are handled correctly).
On other platforms, full compatibility is enabled by default. You can
manually turn it on or off using the —full-compatibility and
—less-compatibility switches.
The standard Windows path format (using \) does not play well with some build
systems, such as CMake. Fortunately, CMake correctly handles paths specified
using Unix-style separators (/), so if your .pc files specify their paths using
that format you shouldn’t have any problems.
Miscellaneous notes
-————————
1. Default target compiler
The CMake pkg-config module does not handle Microsoft Visual C++ style libdir
specifications (/libpath:). For this reason, even on Windows, the output
defaults to the standard non-MSVC-compatible format. You can change which style
is used with the —msvc-syntax and —no-msvc-syntax options.
2. Testing compatibility
The test script, test_compatibility.py, performs a set of unit tests in an
attempt to maintain compatibility with the version of pkg-config mentioned in
CORRESPONDING_VERSION in pykg-config.py. Executing it will run through all the
tests. If they all pass, pykg-config.py is producing the same output as the
pkg-config installed on your system.
3. Search prefix and system directories
pkg-config searchers in directories below a prefix that is defined at compile
time. Typically, this prefix will be /usr/lib/ or /usr/lib64/, depending on the
toolchain used to compile pkg-config. This path is then hard-coded into the
binary and cannot be changed at run-time. The only way to change it is by
recompiling pkg-config and forcing a different value for the system libpath
onto it.
This presents a problem for pykg-config. Checking the Python system prefix (via
sys.prefix) is not a guaranteed solution, as it is often different from the
libpath used by the compiler that builds pkg-config. While not much of a
problem for pykg-config’s main target (Windows), in order to ensure
compatiblity it is best to try and meet this problem.
A nasty hack is used to try and fix this in the majority of cases. At startup,
pykg-config looks at the value of sys.path. It finds the first entry containing
‘pythonxy.zip’ (where x and y are the major and minor version numbers). If the
end of the containing directory name is ‘64’, it assumes that the system is
running 64-bit libraries as the primary toolchain. This will cause paths such
as /usr/lib/ (which are created from the sys.prefix value) to turn into
/usr/lib64/.
You can test if the result is accurate for your system by ensuring that the
‘test_print_errors_with_error’ test will have an error caused by a package in
/usr/lib64 (see the comments for that test), then running
test_compatibility.py. If the error messages are the same (i.e. the test
passes), then the hack has worked.
5. Why?
Because building pkg-config for Windows in an easy-to-distribute, easy-to-use
way is a pain. The core functionality of pkg-config is simple and easy to
provide using Python (which provides several modules useful for such things as
parsing text files, which is what .pc files are).
It was also fun.