pkgconf/man/pkg.m4.7

.\" Copyright (c) 2017 pkgconf authors (see AUTHORS).
.\"
.\" Permission to use, copy, modify, and/or distribute this software for any
.\" purpose with or without fee is hereby granted, provided that the above
.\" copyright notice and this permission notice appear in all copies.
.\"
.\" This software is provided 'as is' and without any warranty, express or
.\" implied.  In no event shall the authors be liable for any damages arising
.\" from the use of this software.
.Dd December 5, 2017
.Dt PKG.M4 7
.Os
.Sh NAME
.Nm pkg.m4
.Nd autoconf macros for using pkgconf
.Sh SYNOPSIS
.Nm PKG_PREREQ
.Nm PKG_PROG_PKG_CONFIG
.Nm PKG_CHECK_MODULES
.Nm PKG_CHECK_MODULES_STATIC
.Nm PKG_INSTALLDIR
.Nm PKG_NOARCH_INSTALLDIR
.Nm PKG_CHECK_VAR
.Nm PKG_WITH_MODULES
.Nm PKG_HAVE_WITH_MODULES
.Nm PKG_HAVE_DEFINE_WITH_MODULES
.Sh DESCRIPTION
.Nm
is a collection of autoconf macros which help to configure compiler and linker
flags for development libraries.
This allows build systems to detect other dependencies and use them with the
system toolchain.
.Sh "AUTOCONF MACROS"
.Ss "PKG_PREREQ(MIN-VERSION)"
Checks that the version of the
.Nm
autoconf macros in use is at least MIN-VERSION.
This can be used to ensure a particular
.Nm
macro will be available.
.Ss "PKG_PROG_PKG_CONFIG([MIN-VERSION])"
Checks for an implementation of
.Nm pkg-config
which is at least MIN-VERSION or newer.
.Ss "PKG_CHECK_MODULES(VARIABLE-PREFIX, MODULES [,ACTION-IF-FOUND [,ACTION-IF-NOT-FOUND]])"
.Ss "PKG_CHECK_MODULES_STATIC(VARIABLE-PREFIX, MODULES [,ACTION-IF-FOUND [,ACTION-IF-NOT-FOUND]])"
Checks whether a given module set exists, and if so, defines
.Nm CFLAGS
and
.Nm LIBS
variables prefixed by
.Nm VARIABLE-PREFIX
with the output from
.Fl -cflags
and
.Fl -libs
respectively.
.Pp
The optional
.Nm ACTION-IF-FOUND
and
.Nm ACTION-IF-NOT-FOUND
arguments are shell fragments that should be executed if the module set is
found or not found.
.Pp
If
.Nm $PKG_CONFIG
is not defined, the
.Nm PKG_PROG_PKG_CONFIG
macro will be executed to locate a
.Nm pkg-config
implementation.
.Pp
The
.Nm PKG_CHECK_MODULES_STATIC
macro provides the same behaviour as
.Nm PKG_CHECK_MODULES
with static linking enabled via the
.Fl -static
flag.
.Ss "PKG_INSTALLDIR(DIRECTORY)"
Defines the variable $pkgconfigdir as the location where a package
should install pkg-config .pc files.
.Pp
By default the directory is $libdir/pkgconfig, but the default can
be changed by passing the
.Nm DIRECTORY
parameter.
.Pp
This value can be overridden with the
.Fl -with-pkgconfigdir
configure parameter.
.Ss "PKG_NOARCH_INSTALLDIR(DIRECTORY)"
Defines the variable $noarch_pkgconfigdir as the location where a package
should install pkg-config .pc files.
.Pp
By default the directory is $datadir/pkgconfig, but the default can
be changed by passing the
.Nm DIRECTORY
parameter.
.Pp
This value can be overridden with the
.Fl -with-noarch-pkgconfigdir
configure parameter.
.Ss "PKG_CHECK_VAR(VARIABLE, MODULE, CONFIG-VARIABLE, [ACTION-IF-FOUND], [ACTION-IF-NOT-FOUND])"
Retrieves the value of the
.Nm pkg-config
variable
.Nm CONFIG-VARIABLE
from
.Nm MODULE
and stores it in the
.Nm VARIABLE
variable.
.Pp
Note that repeated usage of
.Nm VARIABLE
is not recommended as the check will be skipped if the variable is
already set.
.Ss "PKG_WITH_MODULES(VARIABLE-PREFIX, MODULES, [ACTION-IF-FOUND],[ACTION-IF-NOT-FOUND], [DESCRIPTION], [DEFAULT])"
Prepares a "--with-" configure option using the lowercase
.Nm VARIABLE-PREFIX
name, merging the behaviour of
.Nm AC_ARG_WITH
and
.Nm PKG_CHECK_MODULES
in a single macro.
.Ss "PKG_HAVE_WITH_MODULES(VARIABLE-PREFIX, MODULES, [DESCRIPTION], [DEFAULT])"
Convenience macro to trigger
.Nm AM_CONDITIONAL
after a
.Nm PKG_WITH_MODULES check.\&
.Nm VARIABLE-PREFIX
is exported as a make variable.
.Ss "PKG_HAVE_DEFINE_WITH_MODULES(VARIABLE-PREFIX, MODULES, [DESCRIPTION], [DEFAULT])"
Convenience macro to trigger
.Nm AM_CONDITIONAL
and
.Nm AC_DEFINE
after a
.Nm PKG_WITH_MODULES check.\&
.Nm VARIABLE-PREFIX
is exported as a make variable.