Documentation
¶
Overview ¶
cmd/pkg-config is a Go-centric and GOPATH-aware pkg-config replacement for use with the cgo tool.
** Using cmd/pkg-config with the cgo command **
To use cmd/pkg-config go install it and ensure it's in the PATH. A NOTE for Linux users: the cmd/pkg-config must be present before original /usr/bin/pkg-config in the PATH list; it is not advised to replace it, as cmd/pkg-config is not a full replacement for the pkg-config tool, e.g. it does not implement conflict and dependency resolving.
The cgo tool uses pkg-config for obtaining CFLAGS and LDFLAGS of C libraries. Example:
// #cgo pkg-config: libpng // #include <libpng12/png.h> import "C"
The "#cgo pkg-config: png" directive makes a cgo tool query a pkg-config for CFLAGS during generation of a C wrapper (--cflags flag) and for LDFLAGS during linking (--libs flag). The original pkg-config looks up a libpng.pc file in a directory list specified by the PKG_CONFIG_PATH environment variable plus a few other default ones. The libpng.pc file can have the following content:
prefix=/usr
exec_prefix=${prefix}
libdir=${prefix}/lib/x86_64-linux-gnu
includedir=${prefix}/include/libpng12
Name: libpng
Description: Loads and saves PNG files
Version: 1.2.46
Libs: -L${libdir} -lpng12
Libs.private: -lz -lm
Cflags: -I${includedir}
A .pc file is composed of two parts - variables and keywords. Keywords may reference pre-declared variables.
$ pkg-config --cflags libpng -I/usr/include/libpng12 $ pkg-config --libs libpng -L/usr/lib/x86_64-linux-gnu -lpng12 $ pkg-config --cflags --libs libpng -I/usr/include/libpng12 -L/usr/lib/x86_64-linux-gnu -lpng12
The cmd/pkg-config tool looks up for a PC file in two other places in addition do the original pkg-config: $GOPATH and github.com.
** The cmd/pkg-config tool and $GOPATH **
The cmd/pkg-config defines standard directory layout for C libraries:
- $GOPATH/lib contains both the .pc files and binaries
- $GOPATH/include contains package headers
The $GOPATH tree for the example may look like the following:
$GOPATH
├── include
│ └── libpng
│ └── libpng12
│ ├── pngconf.h
│ └── png.h
├── lib
│ ├── linux_amd64
│ │ └── libpng
│ │ ├── libpng12.so
│ │ └── libpng.pc
│ └── windows_amd64
│ └── libpng
│ ├── libpng12.dll
│ ├── libpng12.dll.a
│ └── libpng.pc
└── src
└── github.com
└── joe
└── png-wrapper
└── png-wrapper.go
The cmd/pkg-config reads the libpng.pc file from $GOPATH/lib/libpng/$GOOS_$GOARCH/libpng.pc. The .pc file written for cmd/pkg-config can use $GOPATH, $GOOS and $GOARCH builtin variables, which are expanded by the cmd/pkg-config during runtime. The rewritten .pc file for libpng may look like the following:
libdir=${GOPATH}/lib/${GOOS}_${GOARCH}/libpng
includedir=${GOPATH}/include/libpng
Name: libpng
Description: Loads and saves PNG files
Version: 1.2.46
Libs: -L${libdir} -lpng12
Libs.private: -lz -lm
Cflags: -I${includedir}
** The cmd/pkg-config tool and github.com **
Although it's advised to always use an official or self-compiled libraries for a production use, cmd/pkg-config can download a zip archive from project's github.com releases for a pkg-config tag and unpack it into $GOPATH. For example in order to make the above github.com/joe/png-wrapper package pkg-config-gettable, it's enough to zip include/ and lib/ directories:
$ zip -9 -r libpng.zip include dir
Create release, name a tag after pkg-config and attach libpng.zip do the file list. This would make the libpng.zip archive be accessible from the following link:
$ wget http://github.com/joe/png-wrapper/releases/download/pkg-config/libpng.zip
Which is the default location the cmd/pkg-config searches for libraries. Then go-getting a joe/png-wrapper package altogether with C dependencies is as easy as:
$ go get github.com/joe/png-wrapper
Default behavior of cmd/pkg-config
The cmd/pkg-config tool looks up a .pc file for a $LIBRARY in the following order:
- $GOPATH/lib/$GOOS_$GOARCH/$LIBRARY/$LIBRARY.pc
- if PKG_CONFIG_GITHUB=1 is exported, cmd/pkg-config tries to fetch library from http://github.com/$USER/$PROJECT/releases/download/pkg-config/$LIBRARY.zip
- $PKG_CONFIG_PATH and eventual pkg-config's default search locations (platform-specific)
- if no .pc file is found, pkg-config does its best to generate needed flags on-the-fly, assuming needed library files and headers are present in current $GOPATH as described above
Source Files