3
* libpkgconf consumer lifecycle management
5
* Copyright (c) 2016 pkgconf authors (see AUTHORS).
7
* Permission to use, copy, modify, and/or distribute this software for any
8
* purpose with or without fee is hereby granted, provided that the above
9
* copyright notice and this permission notice appear in all copies.
11
* This software is provided 'as is' and without any warranty, express or
12
* implied. In no event shall the authors be liable for any damages arising
13
* from the use of this software.
16
#include <libpkgconf/config.h>
17
#include <libpkgconf/stdinc.h>
18
#include <libpkgconf/libpkgconf.h>
23
* libpkgconf `client` module
24
* ==========================
26
* The libpkgconf `client` module implements the `pkgconf_client_t` "client" object.
27
* Client objects store all necessary state for libpkgconf allowing for multiple instances to run
30
* Client objects are not thread safe, in other words, a client object should not be shared across
35
trace_path_list(const pkgconf_client_t *client, const char *desc, pkgconf_list_t *list)
37
const pkgconf_node_t *n;
39
PKGCONF_TRACE(client, "%s:", desc);
40
PKGCONF_FOREACH_LIST_ENTRY(list->head, n)
42
const pkgconf_path_t *p = n->data;
44
PKGCONF_TRACE(client, " - '%s'", p->path);
51
* .. c:function:: void pkgconf_client_dir_list_build(pkgconf_client_t *client)
53
* Bootstraps the package search paths. If the ``PKGCONF_PKG_PKGF_ENV_ONLY`` `flag` is set on the client,
54
* then only the ``PKG_CONFIG_PATH`` environment variable will be used, otherwise both the
55
* ``PKG_CONFIG_PATH`` and ``PKG_CONFIG_LIBDIR`` environment variables will be used.
57
* :param pkgconf_client_t* client: The pkgconf client object to bootstrap.
61
pkgconf_client_dir_list_build(pkgconf_client_t *client, const pkgconf_cross_personality_t *personality)
63
pkgconf_path_build_from_environ("PKG_CONFIG_PATH", NULL, &client->dir_list, true);
65
if (!(client->flags & PKGCONF_PKG_PKGF_ENV_ONLY))
67
pkgconf_list_t dir_list = PKGCONF_LIST_INITIALIZER;
68
const pkgconf_list_t *prepend_list = &personality->dir_list;
70
if (getenv("PKG_CONFIG_LIBDIR") != NULL)
72
/* PKG_CONFIG_LIBDIR= should empty the search path entirely. */
73
(void) pkgconf_path_build_from_environ("PKG_CONFIG_LIBDIR", NULL, &dir_list, true);
74
prepend_list = &dir_list;
77
pkgconf_path_copy_list(&client->dir_list, prepend_list);
78
pkgconf_path_free(&dir_list);
85
* .. 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)
87
* Initialise a pkgconf client object.
89
* :param pkgconf_client_t* client: The client to initialise.
90
* :param pkgconf_error_handler_func_t error_handler: An optional error handler to use for logging errors.
91
* :param void* error_handler_data: user data passed to optional error handler
92
* :param pkgconf_cross_personality_t* personality: the cross-compile personality to use for defaults
96
pkgconf_client_init(pkgconf_client_t *client, pkgconf_error_handler_func_t error_handler, void *error_handler_data, const pkgconf_cross_personality_t *personality)
98
client->error_handler_data = error_handler_data;
99
client->error_handler = error_handler;
100
client->auditf = NULL;
103
if (client->trace_handler == NULL)
104
pkgconf_client_set_trace_handler(client, NULL, NULL);
107
pkgconf_client_set_error_handler(client, error_handler, error_handler_data);
108
pkgconf_client_set_warn_handler(client, NULL, NULL);
110
pkgconf_client_set_sysroot_dir(client, personality->sysroot_dir);
111
pkgconf_client_set_buildroot_dir(client, NULL);
112
pkgconf_client_set_prefix_varname(client, NULL);
114
if(getenv("PKG_CONFIG_SYSTEM_LIBRARY_PATH") == NULL)
115
pkgconf_path_copy_list(&client->filter_libdirs, &personality->filter_libdirs);
117
pkgconf_path_build_from_environ("PKG_CONFIG_SYSTEM_LIBRARY_PATH", NULL, &client->filter_libdirs, false);
119
if(getenv("PKG_CONFIG_SYSTEM_INCLUDE_PATH") == NULL)
120
pkgconf_path_copy_list(&client->filter_includedirs, &personality->filter_includedirs);
122
pkgconf_path_build_from_environ("PKG_CONFIG_SYSTEM_INCLUDE_PATH", NULL, &client->filter_includedirs, false);
124
/* GCC uses these environment variables to define system include paths, so we should check them. */
126
pkgconf_path_build_from_environ("BELIBRARIES", NULL, &client->filter_libdirs, false);
128
pkgconf_path_build_from_environ("LIBRARY_PATH", NULL, &client->filter_libdirs, false);
130
pkgconf_path_build_from_environ("CPATH", NULL, &client->filter_includedirs, false);
131
pkgconf_path_build_from_environ("C_INCLUDE_PATH", NULL, &client->filter_includedirs, false);
132
pkgconf_path_build_from_environ("CPLUS_INCLUDE_PATH", NULL, &client->filter_includedirs, false);
133
pkgconf_path_build_from_environ("OBJC_INCLUDE_PATH", NULL, &client->filter_includedirs, false);
136
/* also use the path lists that MSVC uses on windows */
137
pkgconf_path_build_from_environ("INCLUDE", NULL, &client->filter_includedirs, false);
140
PKGCONF_TRACE(client, "initialized client @%p", client);
142
trace_path_list(client, "filtered library paths", &client->filter_libdirs);
143
trace_path_list(client, "filtered include paths", &client->filter_includedirs);
149
* .. 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)
151
* Allocate and initialise a pkgconf client object.
153
* :param pkgconf_error_handler_func_t error_handler: An optional error handler to use for logging errors.
154
* :param void* error_handler_data: user data passed to optional error handler
155
* :param pkgconf_cross_personality_t* personality: cross-compile personality to use
156
* :return: A pkgconf client object.
157
* :rtype: pkgconf_client_t*
160
pkgconf_client_new(pkgconf_error_handler_func_t error_handler, void *error_handler_data, const pkgconf_cross_personality_t *personality)
162
pkgconf_client_t *out = calloc(sizeof(pkgconf_client_t), 1);
163
pkgconf_client_init(out, error_handler, error_handler_data, personality);
170
* .. c:function:: void pkgconf_client_deinit(pkgconf_client_t *client)
172
* Release resources belonging to a pkgconf client object.
174
* :param pkgconf_client_t* client: The client to deinitialise.
178
pkgconf_client_deinit(pkgconf_client_t *client)
180
PKGCONF_TRACE(client, "deinit @%p", client);
182
if (client->prefix_varname != NULL)
183
free(client->prefix_varname);
185
if (client->sysroot_dir != NULL)
186
free(client->sysroot_dir);
188
if (client->buildroot_dir != NULL)
189
free(client->buildroot_dir);
191
pkgconf_path_free(&client->filter_libdirs);
192
pkgconf_path_free(&client->filter_includedirs);
194
pkgconf_tuple_free_global(client);
195
pkgconf_path_free(&client->dir_list);
196
pkgconf_cache_free(client);
202
* .. c:function:: void pkgconf_client_free(pkgconf_client_t *client)
204
* Release resources belonging to a pkgconf client object and then free the client object itself.
206
* :param pkgconf_client_t* client: The client to deinitialise and free.
210
pkgconf_client_free(pkgconf_client_t *client)
212
pkgconf_client_deinit(client);
219
* .. c:function:: const char *pkgconf_client_get_sysroot_dir(const pkgconf_client_t *client)
221
* Retrieves the client's sysroot directory (if any).
223
* :param pkgconf_client_t* client: The client object being accessed.
224
* :return: A string containing the sysroot directory or NULL.
225
* :rtype: const char *
228
pkgconf_client_get_sysroot_dir(const pkgconf_client_t *client)
230
return client->sysroot_dir;
236
* .. c:function:: void pkgconf_client_set_sysroot_dir(pkgconf_client_t *client, const char *sysroot_dir)
238
* Sets or clears the sysroot directory on a client object. Any previous sysroot directory setting is
239
* automatically released if one was previously set.
241
* Additionally, the global tuple ``$(pc_sysrootdir)`` is set as appropriate based on the new setting.
243
* :param pkgconf_client_t* client: The client object being modified.
244
* :param char* sysroot_dir: The sysroot directory to set or NULL to unset.
248
pkgconf_client_set_sysroot_dir(pkgconf_client_t *client, const char *sysroot_dir)
250
if (client->sysroot_dir != NULL)
251
free(client->sysroot_dir);
253
client->sysroot_dir = sysroot_dir != NULL ? strdup(sysroot_dir) : NULL;
255
PKGCONF_TRACE(client, "set sysroot_dir to: %s", client->sysroot_dir != NULL ? client->sysroot_dir : "<default>");
257
pkgconf_tuple_add_global(client, "pc_sysrootdir", client->sysroot_dir != NULL ? client->sysroot_dir : "/");
263
* .. c:function:: const char *pkgconf_client_get_buildroot_dir(const pkgconf_client_t *client)
265
* Retrieves the client's buildroot directory (if any).
267
* :param pkgconf_client_t* client: The client object being accessed.
268
* :return: A string containing the buildroot directory or NULL.
269
* :rtype: const char *
272
pkgconf_client_get_buildroot_dir(const pkgconf_client_t *client)
274
return client->buildroot_dir;
280
* .. c:function:: void pkgconf_client_set_buildroot_dir(pkgconf_client_t *client, const char *buildroot_dir)
282
* Sets or clears the buildroot directory on a client object. Any previous buildroot directory setting is
283
* automatically released if one was previously set.
285
* Additionally, the global tuple ``$(pc_top_builddir)`` is set as appropriate based on the new setting.
287
* :param pkgconf_client_t* client: The client object being modified.
288
* :param char* buildroot_dir: The buildroot directory to set or NULL to unset.
292
pkgconf_client_set_buildroot_dir(pkgconf_client_t *client, const char *buildroot_dir)
294
if (client->buildroot_dir != NULL)
295
free(client->buildroot_dir);
297
client->buildroot_dir = buildroot_dir != NULL ? strdup(buildroot_dir) : NULL;
299
PKGCONF_TRACE(client, "set buildroot_dir to: %s", client->buildroot_dir != NULL ? client->buildroot_dir : "<default>");
301
pkgconf_tuple_add_global(client, "pc_top_builddir", client->buildroot_dir != NULL ? client->buildroot_dir : "$(top_builddir)");
307
* .. c:function:: bool pkgconf_error(const pkgconf_client_t *client, const char *format, ...)
309
* Report an error to a client-registered error handler.
311
* :param pkgconf_client_t* client: The pkgconf client object to report the error to.
312
* :param char* format: A printf-style format string to use for formatting the error message.
313
* :return: true if the error handler processed the message, else false.
317
pkgconf_error(const pkgconf_client_t *client, const char *format, ...)
319
char errbuf[PKGCONF_BUFSIZE];
322
va_start(va, format);
323
vsnprintf(errbuf, sizeof errbuf, format, va);
326
return client->error_handler(errbuf, client, client->error_handler_data);
332
* .. c:function:: bool pkgconf_warn(const pkgconf_client_t *client, const char *format, ...)
334
* Report an error to a client-registered warn handler.
336
* :param pkgconf_client_t* client: The pkgconf client object to report the error to.
337
* :param char* format: A printf-style format string to use for formatting the warning message.
338
* :return: true if the warn handler processed the message, else false.
342
pkgconf_warn(const pkgconf_client_t *client, const char *format, ...)
344
char errbuf[PKGCONF_BUFSIZE];
347
va_start(va, format);
348
vsnprintf(errbuf, sizeof errbuf, format, va);
351
return client->warn_handler(errbuf, client, client->warn_handler_data);
357
* .. c:function:: bool pkgconf_trace(const pkgconf_client_t *client, const char *filename, size_t len, const char *funcname, const char *format, ...)
359
* Report a message to a client-registered trace handler.
361
* :param pkgconf_client_t* client: The pkgconf client object to report the trace message to.
362
* :param char* filename: The file the function is in.
363
* :param size_t lineno: The line number currently being executed.
364
* :param char* funcname: The function name to use.
365
* :param char* format: A printf-style format string to use for formatting the trace message.
366
* :return: true if the trace handler processed the message, else false.
370
pkgconf_trace(const pkgconf_client_t *client, const char *filename, size_t lineno, const char *funcname, const char *format, ...)
372
char errbuf[PKGCONF_BUFSIZE];
376
if (client == NULL || client->trace_handler == NULL)
379
len = snprintf(errbuf, sizeof errbuf, "%s:" SIZE_FMT_SPECIFIER " [%s]: ", filename, lineno, funcname);
381
va_start(va, format);
382
vsnprintf(errbuf + len, sizeof(errbuf) - len, format, va);
385
pkgconf_strlcat(errbuf, "\n", sizeof errbuf);
387
return client->trace_handler(errbuf, client, client->trace_handler_data);
393
* .. c:function:: bool pkgconf_default_error_handler(const char *msg, const pkgconf_client_t *client, const void *data)
395
* The default pkgconf error handler.
397
* :param char* msg: The error message to handle.
398
* :param pkgconf_client_t* client: The client object the error originated from.
399
* :param void* data: An opaque pointer to extra data associated with the client for error handling.
400
* :return: true (the function does nothing to process the message)
404
pkgconf_default_error_handler(const char *msg, const pkgconf_client_t *client, const void *data)
416
* .. c:function:: unsigned int pkgconf_client_get_flags(const pkgconf_client_t *client)
418
* Retrieves resolver-specific flags associated with a client object.
420
* :param pkgconf_client_t* client: The client object to retrieve the resolver-specific flags from.
421
* :return: a bitfield of resolver-specific flags
425
pkgconf_client_get_flags(const pkgconf_client_t *client)
427
return client->flags;
433
* .. c:function:: void pkgconf_client_set_flags(pkgconf_client_t *client, unsigned int flags)
435
* Sets resolver-specific flags associated with a client object.
437
* :param pkgconf_client_t* client: The client object to set the resolver-specific flags on.
441
pkgconf_client_set_flags(pkgconf_client_t *client, unsigned int flags)
443
client->flags = flags;
449
* .. c:function:: const char *pkgconf_client_get_prefix_varname(const pkgconf_client_t *client)
451
* Retrieves the name of the variable that should contain a module's prefix.
452
* In some cases, it is necessary to override this variable to allow proper path relocation.
454
* :param pkgconf_client_t* client: The client object to retrieve the prefix variable name from.
455
* :return: the prefix variable name as a string
456
* :rtype: const char *
459
pkgconf_client_get_prefix_varname(const pkgconf_client_t *client)
461
return client->prefix_varname;
467
* .. c:function:: void pkgconf_client_set_prefix_varname(pkgconf_client_t *client, const char *prefix_varname)
469
* Sets the name of the variable that should contain a module's prefix.
470
* If the variable name is ``NULL``, then the default variable name (``prefix``) is used.
472
* :param pkgconf_client_t* client: The client object to set the prefix variable name on.
473
* :param char* prefix_varname: The prefix variable name to set.
477
pkgconf_client_set_prefix_varname(pkgconf_client_t *client, const char *prefix_varname)
479
if (prefix_varname == NULL)
480
prefix_varname = "prefix";
482
if (client->prefix_varname != NULL)
483
free(client->prefix_varname);
485
client->prefix_varname = strdup(prefix_varname);
487
PKGCONF_TRACE(client, "set prefix_varname to: %s", client->prefix_varname);
493
* .. c:function:: pkgconf_client_get_warn_handler(const pkgconf_client_t *client)
495
* Returns the warning handler if one is set, else ``NULL``.
497
* :param pkgconf_client_t* client: The client object to get the warn handler from.
498
* :return: a function pointer to the warn handler or ``NULL``
500
pkgconf_error_handler_func_t
501
pkgconf_client_get_warn_handler(const pkgconf_client_t *client)
503
return client->warn_handler;
509
* .. c:function:: pkgconf_client_set_warn_handler(pkgconf_client_t *client, pkgconf_error_handler_func_t warn_handler, void *warn_handler_data)
511
* Sets a warn handler on a client object or uninstalls one if set to ``NULL``.
513
* :param pkgconf_client_t* client: The client object to set the warn handler on.
514
* :param pkgconf_error_handler_func_t warn_handler: The warn handler to set.
515
* :param void* warn_handler_data: Optional data to associate with the warn handler.
519
pkgconf_client_set_warn_handler(pkgconf_client_t *client, pkgconf_error_handler_func_t warn_handler, void *warn_handler_data)
521
client->warn_handler = warn_handler;
522
client->warn_handler_data = warn_handler_data;
524
if (client->warn_handler == NULL)
526
PKGCONF_TRACE(client, "installing default warn handler");
527
client->warn_handler = pkgconf_default_error_handler;
534
* .. c:function:: pkgconf_client_get_error_handler(const pkgconf_client_t *client)
536
* Returns the error handler if one is set, else ``NULL``.
538
* :param pkgconf_client_t* client: The client object to get the error handler from.
539
* :return: a function pointer to the error handler or ``NULL``
541
pkgconf_error_handler_func_t
542
pkgconf_client_get_error_handler(const pkgconf_client_t *client)
544
return client->error_handler;
550
* .. c:function:: pkgconf_client_set_error_handler(pkgconf_client_t *client, pkgconf_error_handler_func_t error_handler, void *error_handler_data)
552
* Sets a warn handler on a client object or uninstalls one if set to ``NULL``.
554
* :param pkgconf_client_t* client: The client object to set the error handler on.
555
* :param pkgconf_error_handler_func_t error_handler: The error handler to set.
556
* :param void* error_handler_data: Optional data to associate with the error handler.
560
pkgconf_client_set_error_handler(pkgconf_client_t *client, pkgconf_error_handler_func_t error_handler, void *error_handler_data)
562
client->error_handler = error_handler;
563
client->error_handler_data = error_handler_data;
565
if (client->error_handler == NULL)
567
PKGCONF_TRACE(client, "installing default error handler");
568
client->error_handler = pkgconf_default_error_handler;
576
* .. c:function:: pkgconf_client_get_trace_handler(const pkgconf_client_t *client)
578
* Returns the error handler if one is set, else ``NULL``.
580
* :param pkgconf_client_t* client: The client object to get the error handler from.
581
* :return: a function pointer to the error handler or ``NULL``
583
pkgconf_error_handler_func_t
584
pkgconf_client_get_trace_handler(const pkgconf_client_t *client)
586
return client->trace_handler;
592
* .. c:function:: pkgconf_client_set_trace_handler(pkgconf_client_t *client, pkgconf_error_handler_func_t trace_handler, void *trace_handler_data)
594
* Sets a warn handler on a client object or uninstalls one if set to ``NULL``.
596
* :param pkgconf_client_t* client: The client object to set the error handler on.
597
* :param pkgconf_error_handler_func_t trace_handler: The error handler to set.
598
* :param void* trace_handler_data: Optional data to associate with the error handler.
602
pkgconf_client_set_trace_handler(pkgconf_client_t *client, pkgconf_error_handler_func_t trace_handler, void *trace_handler_data)
604
client->trace_handler = trace_handler;
605
client->trace_handler_data = trace_handler_data;
607
if (client->trace_handler == NULL)
609
client->trace_handler = pkgconf_default_error_handler;
610
PKGCONF_TRACE(client, "installing default trace handler");