From 3e04a02fd1d845d4c72f63783fa980591a22b076 Mon Sep 17 00:00:00 2001
From: Andrew Shadura <andrew.shadura@collabora.co.uk>
Date: Sun, 25 Mar 2018 20:15:05 +0200
Subject: New upstream version 1.4.2

---
 doc/conf.py                   | 339 ++++++++++++++++++++++++++++++++++++++++++
 doc/extract.py                | 149 +++++++++++++++++++
 doc/index.rst                 |  14 ++
 doc/libpkgconf-argvsplit.rst  |  23 +++
 doc/libpkgconf-audit.rst      |  35 +++++
 doc/libpkgconf-cache.rst      |  45 ++++++
 doc/libpkgconf-client.rst     | 198 ++++++++++++++++++++++++
 doc/libpkgconf-dependency.rst |  56 +++++++
 doc/libpkgconf-fragment.rst   | 101 +++++++++++++
 doc/libpkgconf-path.rst       |  63 ++++++++
 doc/libpkgconf-pkg.rst        | 161 ++++++++++++++++++++
 doc/libpkgconf-queue.rst      |  57 +++++++
 doc/libpkgconf-tuple.rst      |  91 ++++++++++++
 doc/libpkgconf.rst            |  16 ++
 14 files changed, 1348 insertions(+)
 create mode 100644 doc/conf.py
 create mode 100644 doc/extract.py
 create mode 100644 doc/index.rst
 create mode 100644 doc/libpkgconf-argvsplit.rst
 create mode 100644 doc/libpkgconf-audit.rst
 create mode 100644 doc/libpkgconf-cache.rst
 create mode 100644 doc/libpkgconf-client.rst
 create mode 100644 doc/libpkgconf-dependency.rst
 create mode 100644 doc/libpkgconf-fragment.rst
 create mode 100644 doc/libpkgconf-path.rst
 create mode 100644 doc/libpkgconf-pkg.rst
 create mode 100644 doc/libpkgconf-queue.rst
 create mode 100644 doc/libpkgconf-tuple.rst
 create mode 100644 doc/libpkgconf.rst

(limited to 'doc')

diff --git a/doc/conf.py b/doc/conf.py
new file mode 100644
index 0000000..ca608c7
--- /dev/null
+++ b/doc/conf.py
@@ -0,0 +1,339 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+#
+# pkgconf documentation build configuration file, created by
+# sphinx-quickstart on Sat Dec 10 16:54:40 2016.
+#
+# This file is execfile()d with the current directory set to its
+# containing dir.
+#
+# Note that not all possible configuration values are present in this
+# autogenerated file.
+#
+# All configuration values have a default; values that are commented out
+# serve to show the default.
+
+# If extensions (or modules to document with autodoc) are in another directory,
+# add these directories to sys.path here. If the directory is relative to the
+# documentation root, use os.path.abspath to make it absolute, like shown here.
+#
+# import os
+# import sys
+# sys.path.insert(0, os.path.abspath('.'))
+
+# -- General configuration ------------------------------------------------
+
+# If your documentation needs a minimal Sphinx version, state it here.
+#
+# needs_sphinx = '1.0'
+
+# Add any Sphinx extension module names here, as strings. They can be
+# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
+# ones.
+extensions = []
+
+# Add any paths that contain templates here, relative to this directory.
+templates_path = ['_templates']
+
+# The suffix(es) of source filenames.
+# You can specify multiple suffix as a list of string:
+#
+# source_suffix = ['.rst', '.md']
+source_suffix = '.rst'
+
+# The encoding of source files.
+#
+# source_encoding = 'utf-8-sig'
+
+# The master toctree document.
+master_doc = 'index'
+
+# General information about the project.
+project = 'pkgconf'
+copyright = '2016, pkgconf authors'
+author = 'pkgconf authors'
+
+# The version info for the project you're documenting, acts as replacement for
+# |version| and |release|, also used in various other places throughout the
+# built documents.
+#
+# The short X.Y version.
+version = '1.1.0'
+# The full version, including alpha/beta/rc tags.
+release = '1.1.0'
+
+# The language for content autogenerated by Sphinx. Refer to documentation
+# for a list of supported languages.
+#
+# This is also used if you do content translation via gettext catalogs.
+# Usually you set "language" from the command line for these cases.
+language = 'en'
+
+# There are two options for replacing |today|: either, you set today to some
+# non-false value, then it is used:
+#
+# today = ''
+#
+# Else, today_fmt is used as the format for a strftime call.
+#
+# today_fmt = '%B %d, %Y'
+
+# List of patterns, relative to source directory, that match files and
+# directories to ignore when looking for source files.
+# This patterns also effect to html_static_path and html_extra_path
+exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']
+
+# The reST default role (used for this markup: `text`) to use for all
+# documents.
+#
+# default_role = None
+
+# If true, '()' will be appended to :func: etc. cross-reference text.
+#
+# add_function_parentheses = True
+
+# If true, the current module name will be prepended to all description
+# unit titles (such as .. function::).
+#
+# add_module_names = True
+
+# If true, sectionauthor and moduleauthor directives will be shown in the
+# output. They are ignored by default.
+#
+# show_authors = False
+
+# The name of the Pygments (syntax highlighting) style to use.
+pygments_style = 'sphinx'
+
+# A list of ignored prefixes for module index sorting.
+# modindex_common_prefix = []
+
+# If true, keep warnings as "system message" paragraphs in the built documents.
+# keep_warnings = False
+
+# If true, `todo` and `todoList` produce output, else they produce nothing.
+todo_include_todos = False
+
+
+# -- Options for HTML output ----------------------------------------------
+
+# The theme to use for HTML and HTML Help pages.  See the documentation for
+# a list of builtin themes.
+#
+html_theme = 'default'
+
+# Theme options are theme-specific and customize the look and feel of a theme
+# further.  For a list of options available for each theme, see the
+# documentation.
+#
+# html_theme_options = {}
+
+# Add any paths that contain custom themes here, relative to this directory.
+# html_theme_path = []
+
+# The name for this set of Sphinx documents.
+# "<project> v<release> documentation" by default.
+#
+# html_title = 'pkgconf v1.1.0'
+
+# A shorter title for the navigation bar.  Default is the same as html_title.
+#
+# html_short_title = None
+
+# The name of an image file (relative to this directory) to place at the top
+# of the sidebar.
+#
+# html_logo = None
+
+# The name of an image file (relative to this directory) to use as a favicon of
+# the docs.  This file should be a Windows icon file (.ico) being 16x16 or 32x32
+# pixels large.
+#
+# html_favicon = None
+
+# Add any paths that contain custom static files (such as style sheets) here,
+# relative to this directory. They are copied after the builtin static files,
+# so a file named "default.css" will overwrite the builtin "default.css".
+html_static_path = ['_static']
+
+# Add any extra paths that contain custom files (such as robots.txt or
+# .htaccess) here, relative to this directory. These files are copied
+# directly to the root of the documentation.
+#
+# html_extra_path = []
+
+# If not None, a 'Last updated on:' timestamp is inserted at every page
+# bottom, using the given strftime format.
+# The empty string is equivalent to '%b %d, %Y'.
+#
+# html_last_updated_fmt = None
+
+# If true, SmartyPants will be used to convert quotes and dashes to
+# typographically correct entities.
+#
+# html_use_smartypants = True
+
+# Custom sidebar templates, maps document names to template names.
+#
+# html_sidebars = {}
+
+# Additional templates that should be rendered to pages, maps page names to
+# template names.
+#
+# html_additional_pages = {}
+
+# If false, no module index is generated.
+#
+# html_domain_indices = True
+
+# If false, no index is generated.
+#
+# html_use_index = True
+
+# If true, the index is split into individual pages for each letter.
+#
+# html_split_index = False
+
+# If true, links to the reST sources are added to the pages.
+#
+# html_show_sourcelink = True
+
+# If true, "Created using Sphinx" is shown in the HTML footer. Default is True.
+#
+# html_show_sphinx = True
+
+# If true, "(C) Copyright ..." is shown in the HTML footer. Default is True.
+#
+# html_show_copyright = True
+
+# If true, an OpenSearch description file will be output, and all pages will
+# contain a <link> tag referring to it.  The value of this option must be the
+# base URL from which the finished HTML is served.
+#
+# html_use_opensearch = ''
+
+# This is the file name suffix for HTML files (e.g. ".xhtml").
+# html_file_suffix = None
+
+# Language to be used for generating the HTML full-text search index.
+# Sphinx supports the following languages:
+#   'da', 'de', 'en', 'es', 'fi', 'fr', 'h', 'it', 'ja'
+#   'nl', 'no', 'pt', 'ro', 'r', 'sv', 'tr', 'zh'
+#
+# html_search_language = 'en'
+
+# A dictionary with options for the search language support, empty by default.
+# 'ja' uses this config value.
+# 'zh' user can custom change `jieba` dictionary path.
+#
+# html_search_options = {'type': 'default'}
+
+# The name of a javascript file (relative to the configuration directory) that
+# implements a search results scorer. If empty, the default will be used.
+#
+# html_search_scorer = 'scorer.js'
+
+# Output file base name for HTML help builder.
+htmlhelp_basename = 'pkgconfdoc'
+
+# -- Options for LaTeX output ---------------------------------------------
+
+latex_elements = {
+     # The paper size ('letterpaper' or 'a4paper').
+     #
+     # 'papersize': 'letterpaper',
+
+     # The font size ('10pt', '11pt' or '12pt').
+     #
+     # 'pointsize': '10pt',
+
+     # Additional stuff for the LaTeX preamble.
+     #
+     # 'preamble': '',
+
+     # Latex figure (float) alignment
+     #
+     # 'figure_align': 'htbp',
+}
+
+# Grouping the document tree into LaTeX files. List of tuples
+# (source start file, target name, title,
+#  author, documentclass [howto, manual, or own class]).
+latex_documents = [
+    (master_doc, 'pkgconf.tex', 'pkgconf Documentation',
+     'pkgconf authors', 'manual'),
+]
+
+# The name of an image file (relative to this directory) to place at the top of
+# the title page.
+#
+# latex_logo = None
+
+# For "manual" documents, if this is true, then toplevel headings are parts,
+# not chapters.
+#
+# latex_use_parts = False
+
+# If true, show page references after internal links.
+#
+# latex_show_pagerefs = False
+
+# If true, show URL addresses after external links.
+#
+# latex_show_urls = False
+
+# Documents to append as an appendix to all manuals.
+#
+# latex_appendices = []
+
+# It false, will not define \strong, \code, 	itleref, \crossref ... but only
+# \sphinxstrong, ..., \sphinxtitleref, ... To help avoid clash with user added
+# packages.
+#
+# latex_keep_old_macro_names = True
+
+# If false, no module index is generated.
+#
+# latex_domain_indices = True
+
+
+# -- Options for manual page output ---------------------------------------
+
+# One entry per manual page. List of tuples
+# (source start file, name, description, authors, manual section).
+man_pages = [
+    (master_doc, 'pkgconf', 'pkgconf Documentation',
+     [author], 1)
+]
+
+# If true, show URL addresses after external links.
+#
+# man_show_urls = False
+
+
+# -- Options for Texinfo output -------------------------------------------
+
+# Grouping the document tree into Texinfo files. List of tuples
+# (source start file, target name, title, author,
+#  dir menu entry, description, category)
+texinfo_documents = [
+    (master_doc, 'pkgconf', 'pkgconf Documentation',
+     author, 'pkgconf', 'One line description of project.',
+     'Miscellaneous'),
+]
+
+# Documents to append as an appendix to all manuals.
+#
+# texinfo_appendices = []
+
+# If false, no module index is generated.
+#
+# texinfo_domain_indices = True
+
+# How to display URL addresses: 'footnote', 'no', or 'inline'.
+#
+# texinfo_show_urls = 'footnote'
+
+# If true, do not generate a @detailmenu in the "Top" node's menu.
+#
+# texinfo_no_detailmenu = False
diff --git a/doc/extract.py b/doc/extract.py
new file mode 100644
index 0000000..5f97208
--- /dev/null
+++ b/doc/extract.py
@@ -0,0 +1,149 @@
+# derived from https://github.com/jeanralphaviles/comment_parser/blob/master/comment_parser/parsers/c_parser.py
+# MIT license - https://github.com/jeanralphaviles/comment_parser/blob/master/LICENSE
+
+
+class Comment:
+    def __init__(self, comment, line, multiline):
+        self.comment = comment
+        self.line = line
+        self.multiline = multiline
+
+    def __repr__(self):
+        return "Comment(comment=%r, line=%r, multiline=%r)" % (self.comment, self.line, self.multiline)
+
+    @property
+    def clean_text(self):
+        if not self.multiline:
+            return self.comment.strip()
+
+        lines = self.comment.splitlines()
+        cleanlines = []
+        for line in lines:
+            if line[0:3] == ' * ':
+                cleanlines.append(line[3:])
+            elif len(line) == 2:
+                cleanlines.append('')
+        return '\n'.join(cleanlines)
+
+    @property
+    def doc_text(self):
+        text = self.clean_text
+        if '!doc' in text[0:4]:
+            return text[5:]
+        return None
+
+
+class FileError(Exception):
+    pass
+
+
+class UnterminatedCommentError(Exception):
+    pass
+
+
+def extract_comments(filename):
+    """Extracts a list of comments from the given C family source file.
+    Comments are represented with the Comment class found in the common module.
+    C family comments come in two forms, single and multi-line comments.
+        - Single-line comments begin with '//' and continue to the end of line.
+        - Multi-line comments begin with '/*' and end with '*/' and can span
+            multiple lines of code. If a multi-line comment does not terminate
+            before EOF is reached, then an exception is raised.
+    Note that this doesn't take language-specific preprocessor directives into
+    consideration.
+    Args:
+        filename: String name of the file to extract comments from.
+    Returns:
+        Python list of Comment objects in the order that they appear in the file.
+    Raises:
+        FileError: File was unable to be open or read.
+        UnterminatedCommentError: Encountered an unterminated multi-line
+            comment.
+    """
+    try:
+        with open(filename, 'r') as source_file:
+            state = 0
+            current_comment = ''
+            comments = []
+            line_counter = 1
+            comment_start = 1
+            while True:
+                char = source_file.read(1)
+                if not char:
+                    if state is 3 or state is 4:
+                        raise UnterminatedCommentError()
+                    if state is 2:
+                        # Was in single line comment. Create comment.
+                        comment = Comment(current_comment, line_counter, False)
+                        comments.append(comment)
+                    return comments
+                if state is 0:
+                    # Waiting for comment start character or beginning of
+                    # string.
+                    if char == '/':
+                        state = 1
+                    elif char == '"':
+                        state = 5
+                elif state is 1:
+                    # Found comment start character, classify next character and
+                    # determine if single or multiline comment.
+                    if char == '/':
+                        state = 2
+                    elif char == '*':
+                        comment_start = line_counter
+                        state = 3
+                    else:
+                        state = 0
+                elif state is 2:
+                    # In single line comment, read characters until EOL.
+                    if char == '\n':
+                        comment = Comment(current_comment, line_counter, False)
+                        comments.append(comment)
+                        current_comment = ''
+                        state = 0
+                    else:
+                        current_comment += char
+                elif state is 3:
+                    # In multi-line comment, add characters until '*'
+                    # encountered.
+                    if char == '*':
+                        state = 4
+                    else:
+                        current_comment += char
+                elif state is 4:
+                    # In multi-line comment with asterisk found. Determine if
+                    # comment is ending.
+                    if char == '/':
+                        comment = Comment(
+                            current_comment, comment_start, True)
+                        comments.append(comment)
+                        current_comment = ''
+                        state = 0
+                    else:
+                        current_comment += '*'
+                        # Care for multiple '*' in a row
+                        if char != '*':
+                            current_comment += char
+                            state = 3
+                elif state is 5:
+                    # In string literal, expect literal end or escape char.
+                    if char == '"':
+                        state = 0
+                    elif char == '\\':
+                        state = 6
+                elif state is 6:
+                    # In string literal, escaping current char.
+                    state = 5
+                if char == '\n':
+                    line_counter += 1
+    except OSError as exception:
+        raise FileError(str(exception))
+
+
+if __name__ == '__main__':
+    import sys
+    from pprint import pprint
+
+    comments = [comment for comment in extract_comments(sys.argv[1]) if comment.doc_text]
+    for comment in comments:
+        print(comment.doc_text)
diff --git a/doc/index.rst b/doc/index.rst
new file mode 100644
index 0000000..b0c7c4b
--- /dev/null
+++ b/doc/index.rst
@@ -0,0 +1,14 @@
+pkgconf
+=======
+
+.. toctree::
+   :maxdepth: 2
+
+   libpkgconf
+
+Indices and tables
+==================
+
+* :ref:`genindex`
+* :ref:`search`
+
diff --git a/doc/libpkgconf-argvsplit.rst b/doc/libpkgconf-argvsplit.rst
new file mode 100644
index 0000000..94ec6d9
--- /dev/null
+++ b/doc/libpkgconf-argvsplit.rst
@@ -0,0 +1,23 @@
+
+libpkgconf `argvsplit` module
+=============================
+
+This is a lowlevel module which provides parsing of strings into argument vectors,
+similar to what a shell would do.
+
+.. c:function:: void pkgconf_argv_free(char **argv)
+
+   Frees an argument vector.
+
+   :param char** argv: The argument vector to free.
+   :return: nothing
+
+.. c:function:: int pkgconf_argv_split(const char *src, int *argc, char ***argv)
+
+   Splits a string into an argument vector.
+
+   :param char*   src: The string to split.
+   :param int*    argc: A pointer to an integer to store the argument count.
+   :param char*** argv: A pointer to a pointer for an argument vector.
+   :return: 0 on success, -1 on error.
+   :rtype: int
diff --git a/doc/libpkgconf-audit.rst b/doc/libpkgconf-audit.rst
new file mode 100644
index 0000000..0baaba3
--- /dev/null
+++ b/doc/libpkgconf-audit.rst
@@ -0,0 +1,35 @@
+
+libpkgconf `audit` module
+=========================
+
+The libpkgconf `audit` module contains the functions related to attaching an audit log file
+to a ``pkgconf_client_t`` object.
+
+The audit log format is the same as the output generated by the ``PKG_CONFIG_LOG`` environment
+variable.
+
+.. c:function:: void pkgconf_audit_set_log(pkgconf_client_t *client, FILE *auditf)
+
+   Sets the audit log file pointer on `client` to `auditf`.
+   The callee is responsible for closing any previous log files.
+
+   :param pkgconf_client_t* client: The client object to modify.
+   :param FILE* auditf: The file pointer for the already open log file.
+   :return: nothing
+
+.. c:function:: void pkgconf_audit_log(pkgconf_client_t *client, const char *format, ...)
+
+   Logs a message to the opened audit log (if any).
+
+   :param pkgconf_client_t* client: The client object the log message is for.
+   :param char* format: The format string to use for the log messages.
+   :return: nothing
+
+.. c:function:: void pkgconf_audit_log_dependency(pkgconf_client_t *client, const pkgconf_pkg_t *dep, const pkgconf_dependency_t *depnode)
+
+   Convenience function which logs a dependency node to the opened audit log (if any).
+
+   :param pkgconf_client_t* client: The client object the log message is for.
+   :param pkgconf_pkg_t* dep: The dependency package object being logged.
+   :param pkgconf_dependency_t* depnode: The dependency object itself being logged.
+   :return: nothing
diff --git a/doc/libpkgconf-cache.rst b/doc/libpkgconf-cache.rst
new file mode 100644
index 0000000..adfa79d
--- /dev/null
+++ b/doc/libpkgconf-cache.rst
@@ -0,0 +1,45 @@
+
+libpkgconf `cache` module
+=========================
+
+The libpkgconf `cache` module manages a package/module object cache, allowing it to
+avoid loading duplicate copies of a package/module.
+
+A cache is tied to a specific pkgconf client object, so package objects should not
+be shared across threads.
+
+.. c:function:: pkgconf_pkg_t *pkgconf_cache_lookup(const pkgconf_client_t *client, const char *id)
+
+   Looks up a package in the cache given an `id` atom,
+   such as ``gtk+-3.0`` and returns the already loaded version
+   if present.
+
+   :param pkgconf_client_t* client: The client object to access.
+   :param char* id: The package atom to look up in the client object's cache.
+   :return: A package object if present, else ``NULL``.
+   :rtype: pkgconf_pkg_t *
+
+.. c:function:: void pkgconf_cache_add(pkgconf_client_t *client, pkgconf_pkg_t *pkg)
+
+   Adds an entry for the package to the package cache.
+   The cache entry must be removed if the package is freed.
+
+   :param pkgconf_client_t* client: The client object to modify.
+   :param pkgconf_pkg_t* pkg: The package object to add to the client object's cache.
+   :return: nothing
+
+.. c:function:: void pkgconf_cache_remove(pkgconf_client_t *client, pkgconf_pkg_t *pkg)
+
+   Deletes a package from the client object's package cache.
+
+   :param pkgconf_client_t* client: The client object to modify.
+   :param pkgconf_pkg_t* pkg: The package object to remove from the client object's cache.
+   :return: nothing
+
+.. c:function:: void pkgconf_cache_free(pkgconf_client_t *client)
+
+   Releases all resources related to a client object's package cache.
+   This function should only be called to clear a client object's package cache,
+   as it may release any package in the cache.
+
+   :param pkgconf_client_t* client: The client object to modify.
diff --git a/doc/libpkgconf-client.rst b/doc/libpkgconf-client.rst
new file mode 100644
index 0000000..d75df35
--- /dev/null
+++ b/doc/libpkgconf-client.rst
@@ -0,0 +1,198 @@
+
+libpkgconf `client` module
+==========================
+
+The libpkgconf `client` module implements the `pkgconf_client_t` "client" object.
+Client objects store all necessary state for libpkgconf allowing for multiple instances to run
+in parallel.
+
+Client objects are not thread safe, in other words, a client object should not be shared across
+thread boundaries.
+
+.. c:function:: void pkgconf_client_init(pkgconf_client_t *client, pkgconf_error_handler_func_t error_handler)
+
+   Initialise a pkgconf client object.
+
+   :param pkgconf_client_t* client: The client to initialise.
+   :param pkgconf_error_handler_func_t error_handler: An optional error handler to use for logging errors.
+   :param void* error_handler_data: user data passed to optional error handler
+   :return: nothing
+
+.. c:function:: pkgconf_client_t* pkgconf_client_new(pkgconf_error_handler_func_t error_handler)
+
+   Allocate and initialise a pkgconf client object.
+
+   :param pkgconf_error_handler_func_t error_handler: An optional error handler to use for logging errors.
+   :param void* error_handler_data: user data passed to optional error handler
+   :return: A pkgconf client object.
+   :rtype: pkgconf_client_t*
+
+.. c:function:: void pkgconf_client_deinit(pkgconf_client_t *client)
+
+   Release resources belonging to a pkgconf client object.
+
+   :param pkgconf_client_t* client: The client to deinitialise.
+   :return: nothing
+
+.. c:function:: void pkgconf_client_free(pkgconf_client_t *client)
+
+   Release resources belonging to a pkgconf client object and then free the client object itself.
+
+   :param pkgconf_client_t* client: The client to deinitialise and free.
+   :return: nothing
+
+.. c:function:: const char *pkgconf_client_get_sysroot_dir(const pkgconf_client_t *client)
+
+   Retrieves the client's sysroot directory (if any).
+
+   :param pkgconf_client_t* client: The client object being accessed.
+   :return: A string containing the sysroot directory or NULL.
+   :rtype: const char *
+
+.. c:function:: void pkgconf_client_set_sysroot_dir(pkgconf_client_t *client, const char *sysroot_dir)
+
+   Sets or clears the sysroot directory on a client object.  Any previous sysroot directory setting is
+   automatically released if one was previously set.
+
+   Additionally, the global tuple ``$(pc_sysrootdir)`` is set as appropriate based on the new setting.
+
+   :param pkgconf_client_t* client: The client object being modified.
+   :param char* sysroot_dir: The sysroot directory to set or NULL to unset.
+   :return: nothing
+
+.. c:function:: const char *pkgconf_client_get_buildroot_dir(const pkgconf_client_t *client)
+
+   Retrieves the client's buildroot directory (if any).
+
+   :param pkgconf_client_t* client: The client object being accessed.
+   :return: A string containing the buildroot directory or NULL.
+   :rtype: const char *
+
+.. c:function:: void pkgconf_client_set_buildroot_dir(pkgconf_client_t *client, const char *buildroot_dir)
+
+   Sets or clears the buildroot directory on a client object.  Any previous buildroot directory setting is
+   automatically released if one was previously set.
+
+   Additionally, the global tuple ``$(pc_top_builddir)`` is set as appropriate based on the new setting.
+
+   :param pkgconf_client_t* client: The client object being modified.
+   :param char* buildroot_dir: The buildroot directory to set or NULL to unset.
+   :return: nothing
+
+.. c:function:: bool pkgconf_error(const pkgconf_client_t *client, const char *format, ...)
+
+   Report an error to a client-registered error handler.
+
+   :param pkgconf_client_t* client: The pkgconf client object to report the error to.
+   :param char* format: A printf-style format string to use for formatting the error message.
+   :return: true if the error handler processed the message, else false.
+   :rtype: bool
+
+.. c:function:: bool pkgconf_warn(const pkgconf_client_t *client, const char *format, ...)
+
+   Report an error to a client-registered warn handler.
+
+   :param pkgconf_client_t* client: The pkgconf client object to report the error to.
+   :param char* format: A printf-style format string to use for formatting the warning message.
+   :return: true if the warn handler processed the message, else false.
+   :rtype: bool
+
+.. c:function:: bool pkgconf_trace(const pkgconf_client_t *client, const char *format, ...)
+
+   Report a message to a client-registered trace handler.
+
+   :param pkgconf_client_t* client: The pkgconf client object to report the trace message to.
+   :param char* format: A printf-style format string to use for formatting the trace message.
+   :return: true if the trace handler processed the message, else false.
+   :rtype: bool
+
+.. c:function:: bool pkgconf_default_error_handler(const char *msg, const pkgconf_client_t *client, const void *data)
+
+   The default pkgconf error handler.
+
+   :param char* msg: The error message to handle.
+   :param pkgconf_client_t* client: The client object the error originated from.
+   :param void* data: An opaque pointer to extra data associated with the client for error handling.
+   :return: true (the function does nothing to process the message)
+   :rtype: bool
+
+.. c:function:: unsigned int pkgconf_client_get_flags(const pkgconf_client_t *client)
+
+   Retrieves resolver-specific flags associated with a client object.
+
+   :param pkgconf_client_t* client: The client object to retrieve the resolver-specific flags from.
+   :return: a bitfield of resolver-specific flags
+   :rtype: uint
+
+.. c:function:: void pkgconf_client_set_flags(pkgconf_client_t *client, unsigned int flags)
+
+   Sets resolver-specific flags associated with a client object.
+
+   :param pkgconf_client_t* client: The client object to set the resolver-specific flags on.
+   :return: nothing
+
+.. c:function:: const char *pkgconf_client_get_prefix_varname(const pkgconf_client_t *client)
+
+   Retrieves the name of the variable that should contain a module's prefix.
+   In some cases, it is necessary to override this variable to allow proper path relocation.
+
+   :param pkgconf_client_t* client: The client object to retrieve the prefix variable name from.
+   :return: the prefix variable name as a string
+   :rtype: const char *
+
+.. c:function:: void pkgconf_client_set_prefix_varname(pkgconf_client_t *client, const char *prefix_varname)
+
+   Sets the name of the variable that should contain a module's prefix.
+   If the variable name is ``NULL``, then the default variable name (``prefix``) is used.
+
+   :param pkgconf_client_t* client: The client object to set the prefix variable name on.
+   :param char* prefix_varname: The prefix variable name to set.
+   :return: nothing
+
+.. c:function:: pkgconf_client_get_warn_handler(const pkgconf_client_t *client)
+
+   Returns the warning handler if one is set, else ``NULL``.
+
+   :param pkgconf_client_t* client: The client object to get the warn handler from.
+   :return: a function pointer to the warn handler or ``NULL``
+
+.. c:function:: pkgconf_client_set_warn_handler(pkgconf_client_t *client, pkgconf_error_handler_func_t warn_handler, void *warn_handler_data)
+
+   Sets a warn handler on a client object or uninstalls one if set to ``NULL``.
+
+   :param pkgconf_client_t* client: The client object to set the warn handler on.
+   :param pkgconf_error_handler_func_t warn_handler: The warn handler to set.
+   :param void* warn_handler_data: Optional data to associate with the warn handler.
+   :return: nothing
+
+.. c:function:: pkgconf_client_get_error_handler(const pkgconf_client_t *client)
+
+   Returns the error handler if one is set, else ``NULL``.
+
+   :param pkgconf_client_t* client: The client object to get the error handler from.
+   :return: a function pointer to the error handler or ``NULL``
+
+.. c:function:: pkgconf_client_set_error_handler(pkgconf_client_t *client, pkgconf_error_handler_func_t error_handler, void *error_handler_data)
+
+   Sets a warn handler on a client object or uninstalls one if set to ``NULL``.
+
+   :param pkgconf_client_t* client: The client object to set the error handler on.
+   :param pkgconf_error_handler_func_t error_handler: The error handler to set.
+   :param void* error_handler_data: Optional data to associate with the error handler.
+   :return: nothing
+
+.. c:function:: pkgconf_client_get_trace_handler(const pkgconf_client_t *client)
+
+   Returns the error handler if one is set, else ``NULL``.
+
+   :param pkgconf_client_t* client: The client object to get the error handler from.
+   :return: a function pointer to the error handler or ``NULL``
+
+.. c:function:: pkgconf_client_set_trace_handler(pkgconf_client_t *client, pkgconf_error_handler_func_t trace_handler, void *trace_handler_data)
+
+   Sets a warn handler on a client object or uninstalls one if set to ``NULL``.
+
+   :param pkgconf_client_t* client: The client object to set the error handler on.
+   :param pkgconf_error_handler_func_t trace_handler: The error handler to set.
+   :param void* trace_handler_data: Optional data to associate with the error handler.
+   :return: nothing
diff --git a/doc/libpkgconf-dependency.rst b/doc/libpkgconf-dependency.rst
new file mode 100644
index 0000000..1ee3e09
--- /dev/null
+++ b/doc/libpkgconf-dependency.rst
@@ -0,0 +1,56 @@
+
+libpkgconf `dependency` module
+==============================
+
+The `dependency` module provides support for building `dependency lists` (the basic component of the overall `dependency graph`) and
+`dependency nodes` which store dependency information.
+
+.. c:function:: pkgconf_dependency_t *pkgconf_dependency_add(pkgconf_list_t *list, const char *package, const char *version, pkgconf_pkg_comparator_t compare)
+
+   Adds a parsed dependency to a dependency list as a dependency node.
+
+   :param pkgconf_client_t* client: The client object that owns the package this dependency list belongs to.
+   :param pkgconf_list_t* list: The dependency list to add a dependency node to.
+   :param char* package: The package `atom` to set on the dependency node.
+   :param char* version: The package `version` to set on the dependency node.
+   :param pkgconf_pkg_comparator_t compare: The comparison operator to set on the dependency node.
+   :return: A dependency node.
+   :rtype: pkgconf_dependency_t *
+
+.. c:function:: void pkgconf_dependency_append(pkgconf_list_t *list, pkgconf_dependency_t *tail)
+
+   Adds a dependency node to a pre-existing dependency list.
+
+   :param pkgconf_list_t* list: The dependency list to add a dependency node to.
+   :param pkgconf_dependency_t* tail: The dependency node to add to the tail of the dependency list.
+   :return: nothing
+
+.. c:function:: void pkgconf_dependency_free(pkgconf_list_t *list)
+
+   Release a dependency list and it's child dependency nodes.
+
+   :param pkgconf_list_t* list: The dependency list to release.
+   :return: nothing
+
+.. c:function:: void pkgconf_dependency_parse_str(pkgconf_list_t *deplist_head, const char *depends)
+
+   Parse a dependency declaration into a dependency list.
+   Commas are counted as whitespace to allow for constructs such as ``@SUBSTVAR@, zlib`` being processed
+   into ``, zlib``.
+
+   :param pkgconf_client_t* client: The client object that owns the package this dependency list belongs to.
+   :param pkgconf_list_t* deplist_head: The dependency list to populate with dependency nodes.
+   :param char* depends: The dependency data to parse.
+   :return: nothing
+
+.. c:function:: void pkgconf_dependency_parse(const pkgconf_client_t *client, pkgconf_pkg_t *pkg, pkgconf_list_t *deplist, const char *depends)
+
+   Preprocess dependency data and then process that dependency declaration into a dependency list.
+   Commas are counted as whitespace to allow for constructs such as ``@SUBSTVAR@, zlib`` being processed
+   into ``, zlib``.
+
+   :param pkgconf_client_t* client: The client object that owns the package this dependency list belongs to.
+   :param pkgconf_pkg_t* pkg: The package object that owns this dependency list.
+   :param pkgconf_list_t* deplist: The dependency list to populate with dependency nodes.
+   :param char* depends: The dependency data to parse.
+   :return: nothing
diff --git a/doc/libpkgconf-fragment.rst b/doc/libpkgconf-fragment.rst
new file mode 100644
index 0000000..a6f64cf
--- /dev/null
+++ b/doc/libpkgconf-fragment.rst
@@ -0,0 +1,101 @@
+
+libpkgconf `fragment` module
+============================
+
+The `fragment` module provides low-level management and rendering of fragment lists.  A
+`fragment list` contains various `fragments` of text (such as ``-I /usr/include``) in a matter
+which is composable, mergeable and reorderable.
+
+.. c:function:: void pkgconf_fragment_add(const pkgconf_client_t *client, pkgconf_list_t *list, const char *string)
+
+   Adds a `fragment` of text to a `fragment list`, possibly modifying the fragment if a sysroot is set.
+
+   :param pkgconf_client_t* client: The pkgconf client being accessed.
+   :param pkgconf_list_t* list: The fragment list.
+   :param char* string: The string of text to add as a fragment to the fragment list.
+   :return: nothing
+
+.. c:function:: bool pkgconf_fragment_has_system_dir(const pkgconf_client_t *client, const pkgconf_fragment_t *frag)
+
+   Checks if a `fragment` contains a `system path`.  System paths are detected at compile time and optionally overridden by
+   the ``PKG_CONFIG_SYSTEM_INCLUDE_PATH`` and ``PKG_CONFIG_SYSTEM_LIBRARY_PATH`` environment variables.
+
+   :param pkgconf_client_t* client: The pkgconf client object the fragment belongs to.
+   :param pkgconf_fragment_t* frag: The fragment being checked.
+   :return: true if the fragment contains a system path, else false
+   :rtype: bool
+
+.. c:function:: void pkgconf_fragment_copy(const pkgconf_client_t *client, pkgconf_list_t *list, const pkgconf_fragment_t *base, bool is_private)
+
+   Copies a `fragment` to another `fragment list`, possibly removing a previous copy of the `fragment`
+   in a process known as `mergeback`.
+
+   :param pkgconf_client_t* client: The pkgconf client being accessed.
+   :param pkgconf_list_t* list: The list the fragment is being added to.
+   :param pkgconf_fragment_t* base: The fragment being copied.
+   :param bool is_private: Whether the fragment list is a `private` fragment list (static linking).
+   :return: nothing
+
+.. c:function:: void pkgconf_fragment_filter(const pkgconf_client_t *client, pkgconf_list_t *dest, pkgconf_list_t *src, pkgconf_fragment_filter_func_t filter_func)
+
+   Copies a `fragment list` to another `fragment list` which match a user-specified filtering function.
+
+   :param pkgconf_client_t* client: The pkgconf client being accessed.
+   :param pkgconf_list_t* dest: The destination list.
+   :param pkgconf_list_t* src: The source list.
+   :param pkgconf_fragment_filter_func_t filter_func: The filter function to use.
+   :param void* data: Optional data to pass to the filter function.
+   :return: nothing
+
+.. c:function:: size_t pkgconf_fragment_render_len(const pkgconf_list_t *list)
+
+   Calculates the required memory to store a `fragment list` when rendered as a string.
+
+   :param pkgconf_list_t* list: The `fragment list` being rendered.
+   :param bool escape: Whether or not to escape special shell characters.
+   :return: the amount of bytes required to represent the `fragment list` when rendered
+   :rtype: size_t
+
+.. c:function:: void pkgconf_fragment_render_buf(const pkgconf_list_t *list, char *buf, size_t buflen)
+
+   Renders a `fragment list` into a buffer.
+
+   :param pkgconf_list_t* list: The `fragment list` being rendered.
+   :param char* buf: The buffer to render the fragment list into.
+   :param size_t buflen: The length of the buffer.
+   :param bool escape: Whether or not to escape special shell characters.
+   :return: nothing
+
+.. c:function:: char *pkgconf_fragment_render(const pkgconf_list_t *list)
+
+   Allocate memory and render a `fragment list` into it.
+
+   :param pkgconf_list_t* list: The `fragment list` being rendered.
+   :param bool escape: Whether or not to escape special shell characters.
+   :return: An allocated string containing the rendered `fragment list`.
+   :rtype: char *
+
+.. c:function:: void pkgconf_fragment_delete(pkgconf_list_t *list, pkgconf_fragment_t *node)
+
+   Delete a `fragment node` from a `fragment list`.
+
+   :param pkgconf_list_t* list: The `fragment list` to delete from.
+   :param pkgconf_fragment_t* node: The `fragment node` to delete.
+   :return: nothing
+
+.. c:function:: void pkgconf_fragment_free(pkgconf_list_t *list)
+
+   Delete an entire `fragment list`.
+
+   :param pkgconf_list_t* list: The `fragment list` to delete.
+   :return: nothing
+
+.. c:function:: bool pkgconf_fragment_parse(const pkgconf_client_t *client, pkgconf_list_t *list, pkgconf_list_t *vars, const char *value)
+
+   Parse a string into a `fragment list`.
+
+   :param pkgconf_client_t* client: The pkgconf client being accessed.
+   :param pkgconf_list_t* list: The `fragment list` to add the fragment entries to.
+   :param pkgconf_list_t* vars: A list of variables to use for variable substitution.
+   :param char* value: The string to parse into fragments.
+   :return: true on success, false on parse error
diff --git a/doc/libpkgconf-path.rst b/doc/libpkgconf-path.rst
new file mode 100644
index 0000000..6d39b3a
--- /dev/null
+++ b/doc/libpkgconf-path.rst
@@ -0,0 +1,63 @@
+
+libpkgconf `path` module
+========================
+
+The `path` module provides functions for manipulating lists of paths in a cross-platform manner.  Notably,
+it is used by the `pkgconf client` to parse the ``PKG_CONFIG_PATH``, ``PKG_CONFIG_LIBDIR`` and related environment
+variables.
+
+.. c:function:: void pkgconf_path_add(const char *text, pkgconf_list_t *dirlist)
+
+   Adds a path node to a path list.  If the path is already in the list, do nothing.
+
+   :param char* text: The path text to add as a path node.
+   :param pkgconf_list_t* dirlist: The path list to add the path node to.
+   :param bool filter: Whether to perform duplicate filtering.
+   :return: nothing
+
+.. c:function:: size_t pkgconf_path_split(const char *text, pkgconf_list_t *dirlist)
+
+   Splits a given text input and inserts paths into a path list.
+
+   :param char* text: The path text to split and add as path nodes.
+   :param pkgconf_list_t* dirlist: The path list to have the path nodes added to.
+   :param bool filter: Whether to perform duplicate filtering.
+   :return: number of path nodes added to the path list
+   :rtype: size_t
+
+.. c:function:: size_t pkgconf_path_build_from_environ(const char *environ, const char *fallback, pkgconf_list_t *dirlist)
+
+   Adds the paths specified in an environment variable to a path list.  If the environment variable is not set,
+   an optional default set of paths is added.
+
+   :param char* environ: The environment variable to look up.
+   :param char* fallback: The fallback paths to use if the environment variable is not set.
+   :param pkgconf_list_t* dirlist: The path list to add the path nodes to.
+   :param bool filter: Whether to perform duplicate filtering.
+   :return: number of path nodes added to the path list
+   :rtype: size_t
+
+.. c:function:: bool pkgconf_path_match_list(const char *path, const pkgconf_list_t *dirlist)
+
+   Checks whether a path has a matching prefix in a path list.
+
+   :param char* path: The path to check against a path list.
+   :param pkgconf_list_t* dirlist: The path list to check the path against.
+   :return: true if the path list has a matching prefix, otherwise false
+   :rtype: bool
+
+.. c:function:: void pkgconf_path_free(pkgconf_list_t *dirlist)
+
+   Releases any path nodes attached to the given path list.
+
+   :param pkgconf_list_t* dirlist: The path list to clean up.
+   :return: nothing
+
+.. c:function:: bool pkgconf_path_relocate(char *buf, size_t buflen)
+
+   Relocates a path, possibly calling normpath() or cygwin_conv_path() on it.
+
+   :param char* buf: The path to relocate.
+   :param size_t buflen: The buffer length the path is contained in.
+   :return: true on success, false on error
+   :rtype: bool
diff --git a/doc/libpkgconf-pkg.rst b/doc/libpkgconf-pkg.rst
new file mode 100644
index 0000000..0117df9
--- /dev/null
+++ b/doc/libpkgconf-pkg.rst
@@ -0,0 +1,161 @@
+
+libpkgconf `pkg` module
+=======================
+
+The `pkg` module provides dependency resolution services and the overall `.pc` file parsing
+routines.
+
+.. c:function:: void pkgconf_pkg_dir_list_build(pkgconf_client_t *client)
+
+   Bootstraps the package search paths.  If the ``PKGCONF_PKG_PKGF_ENV_ONLY`` `flag` is set on the client,
+   then only the ``PKG_CONFIG_PATH`` environment variable will be used, otherwise both the
+   ``PKG_CONFIG_PATH`` and ``PKG_CONFIG_LIBDIR`` environment variables will be used.
+
+   :param pkgconf_client_t* client: The pkgconf client object to bootstrap.
+   :return: nothing
+
+.. c:function:: pkgconf_pkg_t *pkgconf_pkg_new_from_file(const pkgconf_client_t *client, const char *filename, FILE *f)
+
+   Parse a .pc file into a pkgconf_pkg_t object structure.
+
+   :param pkgconf_client_t* client: The pkgconf client object to use for dependency resolution.
+   :param char* filename: The filename of the package file (including full path).
+   :param FILE* f: The file object to read from.
+   :returns: A ``pkgconf_pkg_t`` object which contains the package data.
+   :rtype: pkgconf_pkg_t *
+
+.. c:function:: void pkgconf_pkg_free(pkgconf_client_t *client, pkgconf_pkg_t *pkg)
+
+   Releases all releases for a given ``pkgconf_pkg_t`` object.
+
+   :param pkgconf_client_t* client: The client which owns the ``pkgconf_pkg_t`` object, `pkg`.
+   :param pkgconf_pkg_t* pkg: The package to free.
+   :return: nothing
+
+.. c:function:: pkgconf_pkg_t *pkgconf_pkg_ref(const pkgconf_client_t *client, pkgconf_pkg_t *pkg)
+
+   Adds an additional reference to the package object.
+
+   :param pkgconf_client_t* client: The pkgconf client object which owns the package being referenced.
+   :param pkgconf_pkg_t* pkg: The package object being referenced.
+   :return: The package itself with an incremented reference count.
+   :rtype: pkgconf_pkg_t *
+
+.. c:function:: void pkgconf_pkg_unref(pkgconf_client_t *client, pkgconf_pkg_t *pkg)
+
+   Releases a reference on the package object.  If the reference count is 0, then also free the package.
+
+   :param pkgconf_client_t* client: The pkgconf client object which owns the package being dereferenced.
+   :param pkgconf_pkg_t* pkg: The package object being dereferenced.
+   :return: nothing
+
+.. c:function:: pkgconf_pkg_t *pkgconf_scan_all(pkgconf_client_t *client, void *data, pkgconf_pkg_iteration_func_t func)
+
+   Iterates over all packages found in the `package directory list`, running ``func`` on them.  If ``func`` returns true,
+   then stop iteration and return the last iterated package.
+
+   :param pkgconf_client_t* client: The pkgconf client object to use for dependency resolution.
+   :param void* data: An opaque pointer to data to provide the iteration function with.
+   :param pkgconf_pkg_iteration_func_t func: A function which is called for each package to determine if the package matches,
+       always return ``false`` to iterate over all packages.
+   :return: A package object reference if one is found by the scan function, else ``NULL``.
+   :rtype: pkgconf_pkg_t *
+
+.. c:function:: pkgconf_pkg_t *pkgconf_pkg_find(pkgconf_client_t *client, const char *name)
+
+   Search for a package.
+
+   :param pkgconf_client_t* client: The pkgconf client object to use for dependency resolution.
+   :param char* name: The name of the package `atom` to use for searching.
+   :return: A package object reference if the package was found, else ``NULL``.
+   :rtype: pkgconf_pkg_t *
+
+.. c:function:: int pkgconf_compare_version(const char *a, const char *b)
+
+   Compare versions using RPM version comparison rules as described in the LSB.
+
+   :param char* a: The first version to compare in the pair.
+   :param char* b: The second version to compare in the pair.
+   :return: -1 if the first version is greater, 0 if both versions are equal, 1 if the second version is greater.
+   :rtype: int
+
+.. c:function:: pkgconf_pkg_t *pkgconf_builtin_pkg_get(const char *name)
+
+   Looks up a built-in package.  The package should not be freed or dereferenced.
+
+   :param char* name: An atom corresponding to a built-in package to search for.
+   :return: the built-in package if present, else ``NULL``.
+   :rtype: pkgconf_pkg_t *
+
+.. c:function:: const char *pkgconf_pkg_get_comparator(const pkgconf_dependency_t *pkgdep)
+
+   Returns the comparator used in a depgraph dependency node as a string.
+
+   :param pkgconf_dependency_t* pkgdep: The depgraph dependency node to return the comparator for.
+   :return: A string matching the comparator or ``"???"``.
+   :rtype: char *
+
+.. c:function:: pkgconf_pkg_comparator_t pkgconf_pkg_comparator_lookup_by_name(const char *name)
+
+   Look up the appropriate comparator bytecode in the comparator set (defined
+   in ``pkg.c``, see ``pkgconf_pkg_comparator_names`` and ``pkgconf_pkg_comparator_impls``).
+
+   :param char* name: The comparator to look up by `name`.
+   :return: The comparator bytecode if found, else ``PKGCONF_CMP_ANY``.
+   :rtype: pkgconf_pkg_comparator_t
+
+.. c:function:: pkgconf_pkg_t *pkgconf_pkg_verify_dependency(pkgconf_client_t *client, pkgconf_dependency_t *pkgdep, unsigned int *eflags)
+
+   Verify a pkgconf_dependency_t node in the depgraph.  If the dependency is solvable,
+   return the appropriate ``pkgconf_pkg_t`` object, else ``NULL``.
+
+   :param pkgconf_client_t* client: The pkgconf client object to use for dependency resolution.
+   :param pkgconf_dependency_t* pkgdep: The dependency graph node to solve.
+   :param uint* eflags: An optional pointer that, if set, will be populated with an error code from the resolver.
+   :return: On success, the appropriate ``pkgconf_pkg_t`` object to solve the dependency, else ``NULL``.
+   :rtype: pkgconf_pkg_t *
+
+.. c:function:: unsigned int pkgconf_pkg_verify_graph(pkgconf_client_t *client, pkgconf_pkg_t *root, int depth)
+
+   Verify the graph dependency nodes are satisfiable by walking the tree using
+   ``pkgconf_pkg_traverse()``.
+
+   :param pkgconf_client_t* client: The pkgconf client object to use for dependency resolution.
+   :param pkgconf_pkg_t* root: The root entry in the package dependency graph which should contain the top-level dependencies to resolve.
+   :param int depth: The maximum allowed depth for dependency resolution.
+   :return: On success, ``PKGCONF_PKG_ERRF_OK`` (0), else an error code.
+   :rtype: unsigned int
+
+.. c:function:: unsigned int pkgconf_pkg_traverse(pkgconf_client_t *client, pkgconf_pkg_t *root, pkgconf_pkg_traverse_func_t func, void *data, int maxdepth)
+
+   Walk and resolve the dependency graph up to `maxdepth` levels.
+
+   :param pkgconf_client_t* client: The pkgconf client object to use for dependency resolution.
+   :param pkgconf_pkg_t* root: The root of the dependency graph.
+   :param pkgconf_pkg_traverse_func_t func: A traversal function to call for each resolved node in the dependency graph.
+   :param void* data: An opaque pointer to data to be passed to the traversal function.
+   :param int maxdepth: The maximum depth to walk the dependency graph for.  -1 means infinite recursion.
+   :return: ``PKGCONF_PKG_ERRF_OK`` on success, else an error code.
+   :rtype: unsigned int
+
+.. c:function:: int pkgconf_pkg_cflags(pkgconf_client_t *client, pkgconf_pkg_t *root, pkgconf_list_t *list, int maxdepth)
+
+   Walks a dependency graph and extracts relevant ``CFLAGS`` fragments.
+
+   :param pkgconf_client_t* client: The pkgconf client object to use for dependency resolution.
+   :param pkgconf_pkg_t* root: The root of the dependency graph.
+   :param pkgconf_list_t* list: The fragment list to add the extracted ``CFLAGS`` fragments to.
+   :param int maxdepth: The maximum allowed depth for dependency resolution.  -1 means infinite recursion.
+   :return: ``PKGCONF_PKG_ERRF_OK`` if successful, otherwise an error code.
+   :rtype: unsigned int
+
+.. c:function:: int pkgconf_pkg_libs(pkgconf_client_t *client, pkgconf_pkg_t *root, pkgconf_list_t *list, int maxdepth)
+
+   Walks a dependency graph and extracts relevant ``LIBS`` fragments.
+
+   :param pkgconf_client_t* client: The pkgconf client object to use for dependency resolution.
+   :param pkgconf_pkg_t* root: The root of the dependency graph.
+   :param pkgconf_list_t* list: The fragment list to add the extracted ``LIBS`` fragments to.
+   :param int maxdepth: The maximum allowed depth for dependency resolution.  -1 means infinite recursion.
+   :return: ``PKGCONF_PKG_ERRF_OK`` if successful, otherwise an error code.
+   :rtype: unsigned int
diff --git a/doc/libpkgconf-queue.rst b/doc/libpkgconf-queue.rst
new file mode 100644
index 0000000..a8e7572
--- /dev/null
+++ b/doc/libpkgconf-queue.rst
@@ -0,0 +1,57 @@
+
+libpkgconf `queue` module
+=========================
+
+The `queue` module provides an interface that allows easily building a dependency graph from an
+arbitrary set of dependencies.  It also provides support for doing "preflight" checks on the entire
+dependency graph prior to working with it.
+
+Using the `queue` module functions is the recommended way of working with dependency graphs.
+
+.. c:function:: void pkgconf_queue_push(pkgconf_list_t *list, const char *package)
+
+   Pushes a requested dependency onto the dependency resolver's queue.
+
+   :param pkgconf_list_t* list: the dependency resolution queue to add the package request to.
+   :param char* package: the dependency atom requested
+   :return: nothing
+
+.. c:function:: bool pkgconf_queue_compile(pkgconf_client_t *client, pkgconf_pkg_t *world, pkgconf_list_t *list)
+
+   Compile a dependency resolution queue into a dependency resolution problem if possible, otherwise report an error.
+
+   :param pkgconf_client_t* client: The pkgconf client object to use for dependency resolution.
+   :param pkgconf_pkg_t* world: The designated root of the dependency graph.
+   :param pkgconf_list_t* list: The list of dependency requests to consider.
+   :return: true if the built dependency resolution problem is consistent, else false
+   :rtype: bool
+
+.. c:function:: void pkgconf_queue_free(pkgconf_list_t *list)
+
+   Release any memory related to a dependency resolution queue.
+
+   :param pkgconf_list_t* list: The dependency resolution queue to release.
+   :return: nothing
+
+.. c:function:: void pkgconf_queue_apply(pkgconf_client_t *client, pkgconf_list_t *list, pkgconf_queue_apply_func_t func, int maxdepth, void *data)
+
+   Attempt to compile a dependency resolution queue into a dependency resolution problem, then attempt to solve the problem and
+   feed the solution to a callback function if a complete dependency graph is found.
+
+   :param pkgconf_client_t* client: The pkgconf client object to use for dependency resolution.
+   :param pkgconf_list_t* list: The list of dependency requests to consider.
+   :param pkgconf_queue_apply_func_t func: The callback function to call if a solution is found by the dependency resolver.
+   :param int maxdepth: The maximum allowed depth for the dependency resolver.  A depth of -1 means unlimited.
+   :param void* data: An opaque pointer which is passed to the callback function.
+   :returns: true if the dependency resolver found a solution, otherwise false.
+   :rtype: bool
+
+.. c:function:: void pkgconf_queue_validate(pkgconf_client_t *client, pkgconf_list_t *list, pkgconf_queue_apply_func_t func, int maxdepth, void *data)
+
+   Attempt to compile a dependency resolution queue into a dependency resolution problem, then attempt to solve the problem.
+
+   :param pkgconf_client_t* client: The pkgconf client object to use for dependency resolution.
+   :param pkgconf_list_t* list: The list of dependency requests to consider.
+   :param int maxdepth: The maximum allowed depth for the dependency resolver.  A depth of -1 means unlimited.
+   :returns: true if the dependency resolver found a solution, otherwise false.
+   :rtype: bool
diff --git a/doc/libpkgconf-tuple.rst b/doc/libpkgconf-tuple.rst
new file mode 100644
index 0000000..b87751d
--- /dev/null
+++ b/doc/libpkgconf-tuple.rst
@@ -0,0 +1,91 @@
+
+libpkgconf `tuple` module
+=========================
+
+The `tuple` module provides key-value mappings backed by a linked list.  The key-value
+mapping is mainly used for variable substitution when parsing .pc files.
+
+There are two sets of mappings: a ``pkgconf_pkg_t`` specific mapping, and a `global` mapping.
+The `tuple` module provides convenience wrappers for managing the `global` mapping, which is
+attached to a given client object.
+
+.. c:function:: void pkgconf_tuple_add_global(pkgconf_client_t *client, const char *key, const char *value)
+
+   Defines a global variable, replacing the previous declaration if one was set.
+
+   :param pkgconf_client_t* client: The pkgconf client object to modify.
+   :param char* key: The key for the mapping (variable name).
+   :param char* value: The value for the mapped entry.
+   :return: nothing
+
+.. c:function:: void pkgconf_tuple_find_global(const pkgconf_client_t *client, const char *key)
+
+   Looks up a global variable.
+
+   :param pkgconf_client_t* client: The pkgconf client object to access.
+   :param char* key: The key or variable name to look up.
+   :return: the contents of the variable or ``NULL``
+   :rtype: char *
+
+.. c:function:: void pkgconf_tuple_free_global(pkgconf_client_t *client)
+
+   Delete all global variables associated with a pkgconf client object.
+
+   :param pkgconf_client_t* client: The pkgconf client object to modify.
+   :return: nothing
+
+.. c:function:: void pkgconf_tuple_define_global(pkgconf_client_t *client, const char *kv)
+
+   Parse and define a global variable.
+
+   :param pkgconf_client_t* client: The pkgconf client object to modify.
+   :param char* kv: The variable in the form of ``key=value``.
+   :return: nothing
+
+.. c:function:: pkgconf_tuple_t *pkgconf_tuple_add(const pkgconf_client_t *client, pkgconf_list_t *list, const char *key, const char *value, bool parse)
+
+   Optionally parse and then define a variable.
+
+   :param pkgconf_client_t* client: The pkgconf client object to access.
+   :param pkgconf_list_t* list: The variable list to add the new variable to.
+   :param char* key: The name of the variable being added.
+   :param char* value: The value of the variable being added.
+   :param bool parse: Whether or not to parse the value for variable substitution.
+   :return: a variable object
+   :rtype: pkgconf_tuple_t *
+
+.. c:function:: char *pkgconf_tuple_find(const pkgconf_client_t *client, pkgconf_list_t *list, const char *key)
+
+   Look up a variable in a variable list.
+
+   :param pkgconf_client_t* client: The pkgconf client object to access.
+   :param pkgconf_list_t* list: The variable list to search.
+   :param char* key: The variable name to search for.
+   :return: the value of the variable or ``NULL``
+   :rtype: char *
+
+.. c:function:: char *pkgconf_tuple_parse(const pkgconf_client_t *client, pkgconf_list_t *vars, const char *value)
+
+   Parse an expression for variable substitution.
+
+   :param pkgconf_client_t* client: The pkgconf client object to access.
+   :param pkgconf_list_t* list: The variable list to search for variables (along side the global variable list).
+   :param char* value: The ``key=value`` string to parse.
+   :return: the variable data with any variables substituted
+   :rtype: char *
+
+.. c:function:: void pkgconf_tuple_free_entry(pkgconf_tuple_t *tuple, pkgconf_list_t *list)
+
+   Deletes a variable object, removing it from any variable lists and releasing any memory associated
+   with it.
+
+   :param pkgconf_tuple_t* tuple: The variable object to release.
+   :param pkgconf_list_t* list: The variable list the variable object is attached to.
+   :return: nothing
+
+.. c:function:: void pkgconf_tuple_free(pkgconf_list_t *list)
+
+   Deletes a variable list and any variables attached to it.
+
+   :param pkgconf_list_t* list: The variable list to delete.
+   :return: nothing
diff --git a/doc/libpkgconf.rst b/doc/libpkgconf.rst
new file mode 100644
index 0000000..e95bb13
--- /dev/null
+++ b/doc/libpkgconf.rst
@@ -0,0 +1,16 @@
+libpkgconf - an API for managing `pkg-config` modules
+=====================================================
+
+.. toctree::
+   :maxdepth: 2
+
+   libpkgconf-argvsplit
+   libpkgconf-audit
+   libpkgconf-cache
+   libpkgconf-client
+   libpkgconf-dependency
+   libpkgconf-fragment
+   libpkgconf-path
+   libpkgconf-pkg
+   libpkgconf-queue
+   libpkgconf-tuple
-- 
cgit v1.2.3