diff --git a/doc/libpkgconf-client.rst b/doc/libpkgconf-client.rst index d75df35..6816fdf 100644 --- a/doc/libpkgconf-client.rst +++ b/doc/libpkgconf-client.rst @@ -9,21 +9,32 @@ 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) +.. c:function:: void pkgconf_client_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:: void pkgconf_client_init(pkgconf_client_t *client, pkgconf_error_handler_func_t error_handler, void *error_handler_data, const pkgconf_cross_personality_t *personality) 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 + :param pkgconf_cross_personality_t* personality: the cross-compile personality to use for defaults :return: nothing -.. c:function:: pkgconf_client_t* pkgconf_client_new(pkgconf_error_handler_func_t error_handler) +.. c:function:: pkgconf_client_t* pkgconf_client_new(pkgconf_error_handler_func_t error_handler, void *error_handler_data, const pkgconf_cross_personality_t *personality) 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 + :param pkgconf_cross_personality_t* personality: cross-compile personality to use :return: A pkgconf client object. :rtype: pkgconf_client_t* @@ -97,11 +108,14 @@ thread boundaries. :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, ...) +.. c:function:: bool pkgconf_trace(const pkgconf_client_t *client, const char *filename, size_t len, const char *funcname, 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* filename: The file the function is in. + :param size_t lineno: The line number currently being executed. + :param char* funcname: The function name to use. :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 diff --git a/doc/libpkgconf-dependency.rst b/doc/libpkgconf-dependency.rst index 1ee3e09..a31405a 100644 --- a/doc/libpkgconf-dependency.rst +++ b/doc/libpkgconf-dependency.rst @@ -14,6 +14,7 @@ The `dependency` module provides support for building `dependency lists` (the ba :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. + :param uint flags: Any flags to attach to the dependency node. :return: A dependency node. :rtype: pkgconf_dependency_t * @@ -25,6 +26,29 @@ The `dependency` module provides support for building `dependency lists` (the ba :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_one(pkgconf_dependency_t *dep) + + Frees a dependency node. + + :param pkgconf_dependency_t* dep: The dependency node to free. + :return: nothing + +.. c:function:: pkgconf_dependency_t *pkgconf_dependency_ref(pkgconf_client_t *owner, pkgconf_dependency_t *dep) + + Increases a dependency node's refcount. + + :param pkgconf_client_t* owner: The client object which owns the memory of this dependency node. + :param pkgconf_dependency_t* dep: The dependency to increase the refcount of. + :return: the dependency node on success, else NULL + +.. c:function:: void pkgconf_dependency_unref(pkgconf_client_t *owner, pkgconf_dependency_t *dep) + + Decreases a dependency node's refcount and frees it if necessary. + + :param pkgconf_client_t* owner: The client object which owns the memory of this dependency node. + :param pkgconf_dependency_t* dep: The dependency to decrease the refcount of. + :return: nothing + .. c:function:: void pkgconf_dependency_free(pkgconf_list_t *list) Release a dependency list and it's child dependency nodes. @@ -41,6 +65,7 @@ The `dependency` module provides support for building `dependency lists` (the ba :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. + :param uint flags: Any flags to attach to the dependency nodes. :return: nothing .. c:function:: void pkgconf_dependency_parse(const pkgconf_client_t *client, pkgconf_pkg_t *pkg, pkgconf_list_t *deplist, const char *depends) @@ -53,4 +78,13 @@ The `dependency` module provides support for building `dependency lists` (the ba :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. + :param uint flags: Any flags to attach to the dependency nodes. :return: nothing + +.. c:function:: pkgconf_dependency_t *pkgconf_dependency_copy(pkgconf_client_t *client, const pkgconf_dependency_t *dep) + + Copies a dependency node to a new one. + + :param pkgconf_client_t* client: The client object that will own this dependency. + :param pkgconf_dependency_t* dep: The dependency node to copy. + :return: a pointer to a new dependency node, else NULL diff --git a/doc/libpkgconf-fragment.rst b/doc/libpkgconf-fragment.rst index efbc0c6..00759b7 100644 --- a/doc/libpkgconf-fragment.rst +++ b/doc/libpkgconf-fragment.rst @@ -6,13 +6,14 @@ The `fragment` module provides low-level management and rendering of fragment li `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) +.. c:function:: void pkgconf_fragment_add(const pkgconf_client_t *client, pkgconf_list_t *list, const char *string, unsigned int flags) 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. + :param uint flags: Parsing-related flags for the package. :return: nothing .. c:function:: bool pkgconf_fragment_has_system_dir(const pkgconf_client_t *client, const pkgconf_fragment_t *frag) @@ -110,5 +111,6 @@ which is composable, mergeable and reorderable. :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 uint flags: Any parsing flags to be aware of. :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 index e923f61..0478944 100644 --- a/doc/libpkgconf-path.rst +++ b/doc/libpkgconf-path.rst @@ -25,12 +25,12 @@ variables. :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) +.. c:function:: size_t pkgconf_path_build_from_environ(const char *envvarname, 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* envvarname: 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. @@ -46,6 +46,14 @@ variables. :return: true if the path list has a matching prefix, otherwise false :rtype: bool +.. c:function:: void pkgconf_path_copy_list(pkgconf_list_t *dst, const pkgconf_list_t *src) + + Copies a path list to another path list. + + :param pkgconf_list_t* dst: The path list to copy to. + :param pkgconf_list_t* src: The path list to copy from. + :return: nothing + .. c:function:: void pkgconf_path_free(pkgconf_list_t *dirlist) Releases any path nodes attached to the given path list. diff --git a/doc/libpkgconf-personality.rst b/doc/libpkgconf-personality.rst new file mode 100644 index 0000000..134671a --- /dev/null +++ b/doc/libpkgconf-personality.rst @@ -0,0 +1,27 @@ + +libpkgconf `personality` module +========================= + +.. c:function:: const pkgconf_cross_personality_t *pkgconf_cross_personality_default(void) + + Returns the default cross-compile personality. + + Not thread safe. + + :rtype: pkgconf_cross_personality_t* + :return: the default cross-compile personality + +.. c:function:: void pkgconf_cross_personality_deinit(pkgconf_cross_personality_t *) + + Decrements the count of default cross personality instances. + + Not thread safe. + + :rtype: void + +.. c:function:: pkgconf_cross_personality_t *pkgconf_cross_personality_find(const char *triplet) + + Attempts to find a cross-compile personality given a triplet. + + :rtype: pkgconf_cross_personality_t* + :return: the default cross-compile personality diff --git a/doc/libpkgconf-pkg.rst b/doc/libpkgconf-pkg.rst index e3d083e..044bd1f 100644 --- a/doc/libpkgconf-pkg.rst +++ b/doc/libpkgconf-pkg.rst @@ -5,22 +5,14 @@ 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) +.. c:function:: pkgconf_pkg_t *pkgconf_pkg_new_from_file(const pkgconf_client_t *client, const char *filename, FILE *f, unsigned int flags) 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. + :param uint flags: The flags to use when parsing. :returns: A ``pkgconf_pkg_t`` object which contains the package data. :rtype: pkgconf_pkg_t * @@ -126,7 +118,7 @@ routines. :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) +.. 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, unsigned int skip_flags) Walk and resolve the dependency graph up to `maxdepth` levels. @@ -135,6 +127,7 @@ routines. :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. + :param uint skip_flags: Skip over dependency nodes containing the specified flags. A setting of 0 skips no dependency nodes. :return: ``PKGCONF_PKG_ERRF_OK`` on success, else an error code. :rtype: unsigned int diff --git a/doc/libpkgconf-queue.rst b/doc/libpkgconf-queue.rst index a8e7572..43fca69 100644 --- a/doc/libpkgconf-queue.rst +++ b/doc/libpkgconf-queue.rst @@ -33,11 +33,32 @@ Using the `queue` module functions is the recommended way of working with depend :param pkgconf_list_t* list: The dependency resolution queue to release. :return: nothing +.. c:function:: void pkgconf_solution_free(pkgconf_client_t *client, pkgconf_pkg_t *world, int maxdepth) + + Removes references to package nodes contained in a solution. + + :param pkgconf_client_t* client: The pkgconf client object to use for dependency resolution. + :param pkgconf_pkg_t* world: The root for the generated dependency graph. Should have PKGCONF_PKG_PROPF_VIRTUAL flag. + :returns: nothing + +.. c:function:: bool pkgconf_queue_solve(pkgconf_client_t *client, pkgconf_list_t *list, pkgconf_pkg_t *world, int maxdepth) + + Solves and flattens the dependency graph for the supplied dependency list. + + :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_pkg_t* world: The root for the generated dependency graph, provided by the caller. Should have PKGCONF_PKG_PROPF_VIRTUAL flag. + :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 + .. 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. + This function should not be used in new code. Use pkgconf_queue_solve instead. + :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. diff --git a/doc/libpkgconf-tuple.rst b/doc/libpkgconf-tuple.rst index b87751d..419168b 100644 --- a/doc/libpkgconf-tuple.rst +++ b/doc/libpkgconf-tuple.rst @@ -64,13 +64,14 @@ attached to a given client object. :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) +.. c:function:: char *pkgconf_tuple_parse(const pkgconf_client_t *client, pkgconf_list_t *vars, const char *value, unsigned int flags) 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. + :param uint flags: Any flags to consider while parsing. :return: the variable data with any variables substituted :rtype: char * diff --git a/doc/libpkgconf.rst b/doc/libpkgconf.rst index e95bb13..37167f0 100644 --- a/doc/libpkgconf.rst +++ b/doc/libpkgconf.rst @@ -11,6 +11,7 @@ libpkgconf - an API for managing `pkg-config` modules libpkgconf-dependency libpkgconf-fragment libpkgconf-path + libpkgconf-personality libpkgconf-pkg libpkgconf-queue libpkgconf-tuple