1 2libpkgconf `pkg` module 3======================= 4 5The `pkg` module provides dependency resolution services and the overall `.pc` file parsing 6routines. 7 8.. c:function:: pkgconf_pkg_t *pkgconf_pkg_new_from_file(const pkgconf_client_t *client, const char *filename, FILE *f, unsigned int flags) 9 10 Parse a .pc file into a pkgconf_pkg_t object structure. 11 12 :param pkgconf_client_t* client: The pkgconf client object to use for dependency resolution. 13 :param char* filename: The filename of the package file (including full path). 14 :param FILE* f: The file object to read from. 15 :param uint flags: The flags to use when parsing. 16 :returns: A ``pkgconf_pkg_t`` object which contains the package data. 17 :rtype: pkgconf_pkg_t * 18 19.. c:function:: void pkgconf_pkg_free(pkgconf_client_t *client, pkgconf_pkg_t *pkg) 20 21 Releases all releases for a given ``pkgconf_pkg_t`` object. 22 23 :param pkgconf_client_t* client: The client which owns the ``pkgconf_pkg_t`` object, `pkg`. 24 :param pkgconf_pkg_t* pkg: The package to free. 25 :return: nothing 26 27.. c:function:: pkgconf_pkg_t *pkgconf_pkg_ref(const pkgconf_client_t *client, pkgconf_pkg_t *pkg) 28 29 Adds an additional reference to the package object. 30 31 :param pkgconf_client_t* client: The pkgconf client object which owns the package being referenced. 32 :param pkgconf_pkg_t* pkg: The package object being referenced. 33 :return: The package itself with an incremented reference count. 34 :rtype: pkgconf_pkg_t * 35 36.. c:function:: void pkgconf_pkg_unref(pkgconf_client_t *client, pkgconf_pkg_t *pkg) 37 38 Releases a reference on the package object. If the reference count is 0, then also free the package. 39 40 :param pkgconf_client_t* client: The pkgconf client object which owns the package being dereferenced. 41 :param pkgconf_pkg_t* pkg: The package object being dereferenced. 42 :return: nothing 43 44.. c:function:: pkgconf_pkg_t *pkgconf_scan_all(pkgconf_client_t *client, void *data, pkgconf_pkg_iteration_func_t func) 45 46 Iterates over all packages found in the `package directory list`, running ``func`` on them. If ``func`` returns true, 47 then stop iteration and return the last iterated package. 48 49 :param pkgconf_client_t* client: The pkgconf client object to use for dependency resolution. 50 :param void* data: An opaque pointer to data to provide the iteration function with. 51 :param pkgconf_pkg_iteration_func_t func: A function which is called for each package to determine if the package matches, 52 always return ``false`` to iterate over all packages. 53 :return: A package object reference if one is found by the scan function, else ``NULL``. 54 :rtype: pkgconf_pkg_t * 55 56.. c:function:: pkgconf_pkg_t *pkgconf_pkg_find(pkgconf_client_t *client, const char *name) 57 58 Search for a package. 59 60 :param pkgconf_client_t* client: The pkgconf client object to use for dependency resolution. 61 :param char* name: The name of the package `atom` to use for searching. 62 :return: A package object reference if the package was found, else ``NULL``. 63 :rtype: pkgconf_pkg_t * 64 65.. c:function:: int pkgconf_compare_version(const char *a, const char *b) 66 67 Compare versions using RPM version comparison rules as described in the LSB. 68 69 :param char* a: The first version to compare in the pair. 70 :param char* b: The second version to compare in the pair. 71 :return: -1 if the first version is less than, 0 if both versions are equal, 1 if the second version is less than. 72 :rtype: int 73 74.. c:function:: pkgconf_pkg_t *pkgconf_builtin_pkg_get(const char *name) 75 76 Looks up a built-in package. The package should not be freed or dereferenced. 77 78 :param char* name: An atom corresponding to a built-in package to search for. 79 :return: the built-in package if present, else ``NULL``. 80 :rtype: pkgconf_pkg_t * 81 82.. c:function:: const char *pkgconf_pkg_get_comparator(const pkgconf_dependency_t *pkgdep) 83 84 Returns the comparator used in a depgraph dependency node as a string. 85 86 :param pkgconf_dependency_t* pkgdep: The depgraph dependency node to return the comparator for. 87 :return: A string matching the comparator or ``"???"``. 88 :rtype: char * 89 90.. c:function:: pkgconf_pkg_comparator_t pkgconf_pkg_comparator_lookup_by_name(const char *name) 91 92 Look up the appropriate comparator bytecode in the comparator set (defined 93 in ``pkg.c``, see ``pkgconf_pkg_comparator_names`` and ``pkgconf_pkg_comparator_impls``). 94 95 :param char* name: The comparator to look up by `name`. 96 :return: The comparator bytecode if found, else ``PKGCONF_CMP_ANY``. 97 :rtype: pkgconf_pkg_comparator_t 98 99.. c:function:: pkgconf_pkg_t *pkgconf_pkg_verify_dependency(pkgconf_client_t *client, pkgconf_dependency_t *pkgdep, unsigned int *eflags) 100 101 Verify a pkgconf_dependency_t node in the depgraph. If the dependency is solvable, 102 return the appropriate ``pkgconf_pkg_t`` object, else ``NULL``. 103 104 :param pkgconf_client_t* client: The pkgconf client object to use for dependency resolution. 105 :param pkgconf_dependency_t* pkgdep: The dependency graph node to solve. 106 :param uint* eflags: An optional pointer that, if set, will be populated with an error code from the resolver. 107 :return: On success, the appropriate ``pkgconf_pkg_t`` object to solve the dependency, else ``NULL``. 108 :rtype: pkgconf_pkg_t * 109 110.. c:function:: unsigned int pkgconf_pkg_verify_graph(pkgconf_client_t *client, pkgconf_pkg_t *root, int depth) 111 112 Verify the graph dependency nodes are satisfiable by walking the tree using 113 ``pkgconf_pkg_traverse()``. 114 115 :param pkgconf_client_t* client: The pkgconf client object to use for dependency resolution. 116 :param pkgconf_pkg_t* root: The root entry in the package dependency graph which should contain the top-level dependencies to resolve. 117 :param int depth: The maximum allowed depth for dependency resolution. 118 :return: On success, ``PKGCONF_PKG_ERRF_OK`` (0), else an error code. 119 :rtype: unsigned int 120 121.. 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) 122 123 Walk and resolve the dependency graph up to `maxdepth` levels. 124 125 :param pkgconf_client_t* client: The pkgconf client object to use for dependency resolution. 126 :param pkgconf_pkg_t* root: The root of the dependency graph. 127 :param pkgconf_pkg_traverse_func_t func: A traversal function to call for each resolved node in the dependency graph. 128 :param void* data: An opaque pointer to data to be passed to the traversal function. 129 :param int maxdepth: The maximum depth to walk the dependency graph for. -1 means infinite recursion. 130 :param uint skip_flags: Skip over dependency nodes containing the specified flags. A setting of 0 skips no dependency nodes. 131 :return: ``PKGCONF_PKG_ERRF_OK`` on success, else an error code. 132 :rtype: unsigned int 133 134.. c:function:: int pkgconf_pkg_cflags(pkgconf_client_t *client, pkgconf_pkg_t *root, pkgconf_list_t *list, int maxdepth) 135 136 Walks a dependency graph and extracts relevant ``CFLAGS`` fragments. 137 138 :param pkgconf_client_t* client: The pkgconf client object to use for dependency resolution. 139 :param pkgconf_pkg_t* root: The root of the dependency graph. 140 :param pkgconf_list_t* list: The fragment list to add the extracted ``CFLAGS`` fragments to. 141 :param int maxdepth: The maximum allowed depth for dependency resolution. -1 means infinite recursion. 142 :return: ``PKGCONF_PKG_ERRF_OK`` if successful, otherwise an error code. 143 :rtype: unsigned int 144 145.. c:function:: int pkgconf_pkg_libs(pkgconf_client_t *client, pkgconf_pkg_t *root, pkgconf_list_t *list, int maxdepth) 146 147 Walks a dependency graph and extracts relevant ``LIBS`` fragments. 148 149 :param pkgconf_client_t* client: The pkgconf client object to use for dependency resolution. 150 :param pkgconf_pkg_t* root: The root of the dependency graph. 151 :param pkgconf_list_t* list: The fragment list to add the extracted ``LIBS`` fragments to. 152 :param int maxdepth: The maximum allowed depth for dependency resolution. -1 means infinite recursion. 153 :return: ``PKGCONF_PKG_ERRF_OK`` if successful, otherwise an error code. 154 :rtype: unsigned int 155