ariadne
/
pkgconf
3
6
Fork 4
Code Issues 6 Pull Requests 2 Projects Releases 2 Wiki Activity

libpkgconf: document client module

pull/100/head
William Pitcock 2016-12-10 18:35:17 -06:00
parent 9640592a1d
commit 91fbf683f1
3 changed files with 189 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

78
doc/libpkgconf-client.rst Normal file
View File

@ -0,0 +1,78 @@
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.
: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.
: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

5
doc/libpkgconf.rst
View File

@ -1,2 +1,7 @@
libpkgconf - an API for managing `pkg-config` modules
=====================================================
.. toctree::
:maxdepth: 2
libpkgconf-client

106
libpkgconf/client.c
View File

@ -15,6 +15,31 @@
#include <libpkgconf/libpkgconf.h>
/*
* !doc
*
* 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.
*/
/*
* !doc
*
* .. 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.
* :return: nothing
*/
void
pkgconf_client_init(pkgconf_client_t *client, pkgconf_error_handler_func_t error_handler)
{
@ -25,6 +50,17 @@ pkgconf_client_init(pkgconf_client_t *client, pkgconf_error_handler_func_t error
pkgconf_client_set_buildroot_dir(client, NULL);
}
/*
* !doc
*
* .. 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.
* :return: A pkgconf client object.
* :rtype: pkgconf_client_t*
*/
pkgconf_client_t *
pkgconf_client_new(pkgconf_error_handler_func_t error_handler)
{
@ -33,6 +69,16 @@ pkgconf_client_new(pkgconf_error_handler_func_t error_handler)
return out;
}
/*
* !doc
*
* .. 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
*/
void
pkgconf_client_deinit(pkgconf_client_t *client)
{
@ -47,6 +93,16 @@ pkgconf_client_deinit(pkgconf_client_t *client)
pkgconf_cache_free(client);
}
/*
* !doc
*
* .. 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
*/
void
pkgconf_client_free(pkgconf_client_t *client)
{
@ -54,12 +110,37 @@ pkgconf_client_free(pkgconf_client_t *client)
free(client);
}
/*
* !doc
*
* .. 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 *
*/
const char *
pkgconf_client_get_sysroot_dir(const pkgconf_client_t *client)
{
return client->sysroot_dir;
}
/*
* !doc
*
* .. 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
*/
void
pkgconf_client_set_sysroot_dir(pkgconf_client_t *client, const char *sysroot_dir)
{
@ -71,12 +152,37 @@ pkgconf_client_set_sysroot_dir(pkgconf_client_t *client, const char *sysroot_dir
pkgconf_tuple_add_global(client, "pc_sysrootdir", client->sysroot_dir != NULL ? client->sysroot_dir : "/");
}
/*
* !doc
*
* .. 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 *
*/
const char *
pkgconf_client_get_buildroot_dir(const pkgconf_client_t *client)
{
return client->buildroot_dir;
}
/*
* !doc
*
* .. 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
*/
void
pkgconf_client_set_buildroot_dir(pkgconf_client_t *client, const char *buildroot_dir)
{