[libcamera-devel] [PATCH 12/16] libcamera/base: Validate internal headers as private
Hirokazu Honda
hiroh at chromium.org
Fri Jun 25 06:12:57 CEST 2021
Hi Kieran, thank you for the patch.
On Fri, Jun 25, 2021 at 10:35 AM Kieran Bingham
<kieran.bingham at ideasonboard.com> wrote:
>
> Headers which must not be exposed as part of the public libcamera API
> can include base/private.h.
>
> Any interface which includes the private.h header will only be able to
> build if the libcamera_private dependency is used (or the
> libcamera_base_private dependency directly)
>
I couldn't understand well which one of the four dependencies
(libcamera_private, libcamera_base, libcamera_dep,
libcamera_base_private) should be used in a specific target.
Would you mind describing the rule of using these dependencies?
> Signed-off-by: Kieran Bingham <kieran.bingham at ideasonboard.com>
> ---
> include/libcamera/base/event_dispatcher.h | 2 ++
> .../libcamera/base/event_dispatcher_poll.h | 2 ++
> include/libcamera/base/event_notifier.h | 1 +
> include/libcamera/base/file.h | 1 +
> include/libcamera/base/log.h | 1 +
> include/libcamera/base/meson.build | 1 +
> include/libcamera/base/private.h | 22 +++++++++++++++++++
> include/libcamera/base/semaphore.h | 1 +
> include/libcamera/base/thread.h | 1 +
> include/libcamera/base/timer.h | 1 +
> include/libcamera/base/utils.h | 2 ++
> src/android/meson.build | 2 +-
> src/ipa/ipu3/meson.build | 2 +-
> src/ipa/libipa/meson.build | 2 +-
> src/ipa/raspberrypi/meson.build | 2 +-
> src/ipa/rkisp1/meson.build | 2 +-
> src/ipa/vimc/meson.build | 2 +-
> src/libcamera/base/meson.build | 8 +++++++
> src/libcamera/meson.build | 10 +++++++--
> src/libcamera/proxy/worker/meson.build | 2 +-
> src/v4l2/meson.build | 2 +-
> test/camera/meson.build | 2 +-
> test/ipa/meson.build | 2 +-
> test/ipc/meson.build | 2 +-
> test/libtest/meson.build | 2 +-
> test/log/meson.build | 2 +-
> test/media_device/meson.build | 4 ++--
> test/meson.build | 2 +-
> test/pipeline/ipu3/meson.build | 2 +-
> test/pipeline/rkisp1/meson.build | 2 +-
> test/process/meson.build | 2 +-
> .../generated_serializer/meson.build | 2 +-
> test/serialization/meson.build | 2 +-
> test/v4l2_subdevice/meson.build | 2 +-
> test/v4l2_videodevice/meson.build | 2 +-
> 35 files changed, 74 insertions(+), 25 deletions(-)
> create mode 100644 include/libcamera/base/private.h
>
> diff --git a/include/libcamera/base/event_dispatcher.h b/include/libcamera/base/event_dispatcher.h
> index 045df27fff16..825af7a33919 100644
> --- a/include/libcamera/base/event_dispatcher.h
> +++ b/include/libcamera/base/event_dispatcher.h
> @@ -9,6 +9,8 @@
>
> #include <vector>
>
> +#include <libcamera/base/private.h>
> +
> namespace libcamera {
>
> class EventNotifier;
> diff --git a/include/libcamera/base/event_dispatcher_poll.h b/include/libcamera/base/event_dispatcher_poll.h
> index ae2a3f04e4b9..88835902980c 100644
> --- a/include/libcamera/base/event_dispatcher_poll.h
> +++ b/include/libcamera/base/event_dispatcher_poll.h
> @@ -13,6 +13,8 @@
>
> #include <libcamera/base/event_dispatcher.h>
>
> +#include <libcamera/base/private.h>
> +
> struct pollfd;
>
> namespace libcamera {
> diff --git a/include/libcamera/base/event_notifier.h b/include/libcamera/base/event_notifier.h
> index 8a6419f23004..6bb4e5143aa6 100644
> --- a/include/libcamera/base/event_notifier.h
> +++ b/include/libcamera/base/event_notifier.h
> @@ -8,6 +8,7 @@
> #define __LIBCAMERA_INTERNAL_EVENT_NOTIFIER_H__
>
> #include <libcamera/base/object.h>
> +#include <libcamera/base/private.h>
> #include <libcamera/base/signal.h>
>
> namespace libcamera {
> diff --git a/include/libcamera/base/file.h b/include/libcamera/base/file.h
> index e8e4b76e1a4e..cecbb254591f 100644
> --- a/include/libcamera/base/file.h
> +++ b/include/libcamera/base/file.h
> @@ -12,6 +12,7 @@
> #include <sys/types.h>
>
> #include <libcamera/base/class.h>
> +#include <libcamera/base/private.h>
>
> #include <libcamera/span.h>
>
> diff --git a/include/libcamera/base/log.h b/include/libcamera/base/log.h
> index b93c947ae7db..70582cd47902 100644
> --- a/include/libcamera/base/log.h
> +++ b/include/libcamera/base/log.h
> @@ -11,6 +11,7 @@
> #include <sstream>
>
> #include <libcamera/base/class.h>
> +#include <libcamera/base/private.h>
> #include <libcamera/base/utils.h>
>
> namespace libcamera {
> diff --git a/include/libcamera/base/meson.build b/include/libcamera/base/meson.build
> index 83c664affc88..aaac324d7149 100644
> --- a/include/libcamera/base/meson.build
> +++ b/include/libcamera/base/meson.build
> @@ -12,6 +12,7 @@ libcamera_base_headers = files([
> 'log.h',
> 'message.h',
> 'object.h',
> + 'private.h',
> 'semaphore.h',
> 'signal.h',
> 'thread.h',
> diff --git a/include/libcamera/base/private.h b/include/libcamera/base/private.h
> new file mode 100644
> index 000000000000..b54ad076688e
> --- /dev/null
> +++ b/include/libcamera/base/private.h
> @@ -0,0 +1,22 @@
> +/* SPDX-License-Identifier: LGPL-2.1-or-later */
> +/*
> + * Copyright (C) 2021, Google Inc.
> + *
> + * private.h - Private Header Validation
> + *
> + * A selection of internal libcamera headers are installed as part
> + * of the libcamera package to allow sharing of a select subset of
> + * internal functionality with IPA module developers only.
> + *
> + * This functionality is not considered part of the public libcamera
> + * API, and can therefore potentially face ABI instabilities which
> + * should not be exposed to applications. IPA modules however should be
> + * versioned and more closely matched to the libcamera installation.
> + *
> + * Components which include this file can not be included in any file
> + * which forms part of the libcamera API.
> + */
> +
> +#ifndef LIBCAMERA_BASE_PRIVATE
> +#error "Private headers must not be included in the libcamera API"
> +#endif
> diff --git a/include/libcamera/base/semaphore.h b/include/libcamera/base/semaphore.h
> index c8e62e3ee68b..d8146eb8060b 100644
> --- a/include/libcamera/base/semaphore.h
> +++ b/include/libcamera/base/semaphore.h
> @@ -9,6 +9,7 @@
>
> #include <condition_variable>
>
> +#include <libcamera/base/private.h>
> #include <libcamera/base/thread.h>
>
> namespace libcamera {
> diff --git a/include/libcamera/base/thread.h b/include/libcamera/base/thread.h
> index 2ed18d49c978..b30ed12715a2 100644
> --- a/include/libcamera/base/thread.h
> +++ b/include/libcamera/base/thread.h
> @@ -13,6 +13,7 @@
> #include <thread>
>
> #include <libcamera/base/message.h>
> +#include <libcamera/base/private.h>
> #include <libcamera/base/signal.h>
> #include <libcamera/base/utils.h>
>
> diff --git a/include/libcamera/base/timer.h b/include/libcamera/base/timer.h
> index e79e85f1ef0d..f762e8767d97 100644
> --- a/include/libcamera/base/timer.h
> +++ b/include/libcamera/base/timer.h
> @@ -11,6 +11,7 @@
> #include <stdint.h>
>
> #include <libcamera/base/object.h>
> +#include <libcamera/base/private.h>
> #include <libcamera/base/signal.h>
>
> namespace libcamera {
> diff --git a/include/libcamera/base/utils.h b/include/libcamera/base/utils.h
> index d1aaff65211a..07685045aa05 100644
> --- a/include/libcamera/base/utils.h
> +++ b/include/libcamera/base/utils.h
> @@ -19,6 +19,8 @@
> #include <utility>
> #include <vector>
>
> +#include <libcamera/base/private.h>
> +
> #ifndef __DOXYGEN__
>
> /* uClibc and uClibc-ng don't provide O_TMPFILE */
> diff --git a/src/android/meson.build b/src/android/meson.build
> index bd58ef964c2a..7d1e7e85f16e 100644
> --- a/src/android/meson.build
> +++ b/src/android/meson.build
> @@ -4,7 +4,7 @@ android_deps = [
> dependency('libexif', required : get_option('android')),
> dependency('libjpeg', required : get_option('android')),
> dependency('yaml-0.1', required : get_option('android')),
> - libcamera_dep,
> + libcamera_private,
> ]
>
> android_enabled = true
> diff --git a/src/ipa/ipu3/meson.build b/src/ipa/ipu3/meson.build
> index 0d843846acde..b63641908710 100644
> --- a/src/ipa/ipu3/meson.build
> +++ b/src/ipa/ipu3/meson.build
> @@ -12,7 +12,7 @@ mod = shared_module(ipa_name,
> [ipu3_ipa_sources, libcamera_generated_ipa_headers],
> name_prefix : '',
> include_directories : [ipa_includes, libipa_includes],
> - dependencies : libcamera_dep,
> + dependencies : libcamera_private,
> link_with : libipa,
> install : true,
> install_dir : ipa_install_dir)
> diff --git a/src/ipa/libipa/meson.build b/src/ipa/libipa/meson.build
> index 038fc49060ef..ca541a5aafd7 100644
> --- a/src/ipa/libipa/meson.build
> +++ b/src/ipa/libipa/meson.build
> @@ -14,4 +14,4 @@ libipa_includes = include_directories('..')
>
> libipa = static_library('ipa', [libipa_sources, libipa_headers],
> include_directories : ipa_includes,
> - dependencies : libcamera_dep)
> + dependencies : libcamera_private)
> diff --git a/src/ipa/raspberrypi/meson.build b/src/ipa/raspberrypi/meson.build
> index 230356d3ce3a..d7203aa042cd 100644
> --- a/src/ipa/raspberrypi/meson.build
> +++ b/src/ipa/raspberrypi/meson.build
> @@ -3,7 +3,7 @@
> ipa_name = 'ipa_rpi'
>
> rpi_ipa_deps = [
> - libcamera_dep,
> + libcamera_private,
> dependency('boost'),
> libatomic,
> ]
> diff --git a/src/ipa/rkisp1/meson.build b/src/ipa/rkisp1/meson.build
> index 1a1c71591039..f76b37f5af50 100644
> --- a/src/ipa/rkisp1/meson.build
> +++ b/src/ipa/rkisp1/meson.build
> @@ -6,7 +6,7 @@ mod = shared_module(ipa_name,
> ['rkisp1.cpp', libcamera_generated_ipa_headers],
> name_prefix : '',
> include_directories : [ipa_includes, libipa_includes],
> - dependencies : libcamera_dep,
> + dependencies : libcamera_private,
> link_with : libipa,
> install : true,
> install_dir : ipa_install_dir)
> diff --git a/src/ipa/vimc/meson.build b/src/ipa/vimc/meson.build
> index a35825ae25a6..ecbeee136451 100644
> --- a/src/ipa/vimc/meson.build
> +++ b/src/ipa/vimc/meson.build
> @@ -6,7 +6,7 @@ mod = shared_module(ipa_name,
> ['vimc.cpp', libcamera_generated_ipa_headers],
> name_prefix : '',
> include_directories : [ipa_includes, libipa_includes],
> - dependencies : libcamera_dep,
> + dependencies : libcamera_private,
> link_with : libipa,
> install : true,
> install_dir : ipa_install_dir)
> diff --git a/src/libcamera/base/meson.build b/src/libcamera/base/meson.build
> index a8b04cfc8a5f..871721571e98 100644
> --- a/src/libcamera/base/meson.build
> +++ b/src/libcamera/base/meson.build
> @@ -21,10 +21,15 @@ libcamera_base_deps = [
> dependency('threads'),
> ]
>
> +# Internal components must use the libcamera_base_private dependency to enable
> +# the use of headers which must not be exposed to the libcamera public api.
> +libcamera_base_args = [ '-DLIBCAMERA_BASE_PRIVATE' ]
> +
> libcamera_base_lib = shared_library('libcamera-base',
> [libcamera_base_sources, libcamera_base_headers],
> name_prefix : '',
> install : true,
> + cpp_args : libcamera_base_args,
> include_directories : libcamera_includes,
> dependencies : libcamera_base_deps)
>
> @@ -39,3 +44,6 @@ pkg_mod.generate(libcamera_base_lib,
> version : '1.0',
> description : 'Camera support base utility library',
> subdirs : 'libcamera')
> +
> +libcamera_base_private = declare_dependency(dependencies : libcamera_base,
> + compile_args : libcamera_base_args)
> diff --git a/src/libcamera/meson.build b/src/libcamera/meson.build
> index 1f163cfe1225..64c7475f1a2e 100644
> --- a/src/libcamera/meson.build
> +++ b/src/libcamera/meson.build
> @@ -115,7 +115,7 @@ libcamera_deps = [
> libgnutls,
> liblttng,
> libudev,
> - libcamera_base,
> + libcamera_base_private,
> ]
>
> # We add '/' to the build_rpath as a 'safe' path to act as a boolean flag.
> @@ -143,9 +143,15 @@ libcamera_dep = declare_dependency(sources : [
> libcamera_generated_ipa_headers,
> ],
> include_directories : libcamera_includes,
> - dependencies: libcamera_base,
> + dependencies : libcamera_base,
> link_with : libcamera)
>
> +# Internal dependancy for components and plugins which can use Private APIs
> +libcamera_private = declare_dependency(dependencies : [
> + libcamera_dep,
> + libcamera_base_private,
> + ])
> +
> pkg_mod = import('pkgconfig')
> pkg_mod.generate(libcamera,
> libraries : libcamera_base_lib,
> diff --git a/src/libcamera/proxy/worker/meson.build b/src/libcamera/proxy/worker/meson.build
> index 28fe5f1fd6b2..70c8760a3d42 100644
> --- a/src/libcamera/proxy/worker/meson.build
> +++ b/src/libcamera/proxy/worker/meson.build
> @@ -21,7 +21,7 @@ foreach mojom : ipa_mojoms
> [worker, libcamera_generated_ipa_headers],
> install : true,
> install_dir : proxy_install_dir,
> - dependencies : libcamera_dep)
> + dependencies : libcamera_private)
> endforeach
>
> config_h.set('IPA_PROXY_DIR',
> diff --git a/src/v4l2/meson.build b/src/v4l2/meson.build
> index 0accac194be4..f78497b6799b 100644
> --- a/src/v4l2/meson.build
> +++ b/src/v4l2/meson.build
> @@ -31,5 +31,5 @@ v4l2_compat = shared_library('v4l2-compat',
> v4l2_compat_sources,
> name_prefix : '',
> install : true,
> - dependencies : [libcamera_dep, libdl],
> + dependencies : [libcamera_private, libdl],
> cpp_args : v4l2_compat_cpp_args)
> diff --git a/test/camera/meson.build b/test/camera/meson.build
> index 9cb95affffab..002a87b594e0 100644
> --- a/test/camera/meson.build
> +++ b/test/camera/meson.build
> @@ -12,7 +12,7 @@ camera_tests = [
>
> foreach t : camera_tests
> exe = executable(t[0], t[1],
> - dependencies : libcamera_dep,
> + dependencies : libcamera_private,
> link_with : test_libraries,
> include_directories : test_includes_internal)
> test(t[0], exe, suite : 'camera', is_parallel : false)
> diff --git a/test/ipa/meson.build b/test/ipa/meson.build
> index e8a041b5bbd2..7938633e54ab 100644
> --- a/test/ipa/meson.build
> +++ b/test/ipa/meson.build
> @@ -7,7 +7,7 @@ ipa_test = [
>
> foreach t : ipa_test
> exe = executable(t[0], [t[1], libcamera_generated_ipa_headers],
> - dependencies : libcamera_dep,
> + dependencies : libcamera_private,
> link_with : [libipa, test_libraries],
> include_directories : [libipa_includes, test_includes_internal])
>
> diff --git a/test/ipc/meson.build b/test/ipc/meson.build
> index ad47b2feb718..2a6cd7fb8433 100644
> --- a/test/ipc/meson.build
> +++ b/test/ipc/meson.build
> @@ -7,7 +7,7 @@ ipc_tests = [
>
> foreach t : ipc_tests
> exe = executable(t[0], t[1],
> - dependencies : libcamera_dep,
> + dependencies : libcamera_private,
> link_with : test_libraries,
> include_directories : test_includes_internal)
>
> diff --git a/test/libtest/meson.build b/test/libtest/meson.build
> index 542335ea5e7c..351629f3ce73 100644
> --- a/test/libtest/meson.build
> +++ b/test/libtest/meson.build
> @@ -18,7 +18,7 @@ test_includes_internal = [
> ]
>
> libtest = static_library('libtest', libtest_sources,
> - dependencies : libcamera_dep,
> + dependencies : libcamera_private,
> include_directories : test_includes_internal)
>
> test_libraries = [libtest]
> diff --git a/test/log/meson.build b/test/log/meson.build
> index 8cd664e04a00..ac87841a24e1 100644
> --- a/test/log/meson.build
> +++ b/test/log/meson.build
> @@ -7,7 +7,7 @@ log_test = [
>
> foreach t : log_test
> exe = executable(t[0], t[1],
> - dependencies : libcamera_dep,
> + dependencies : libcamera_private,
> link_with : test_libraries,
> include_directories : test_includes_internal)
>
> diff --git a/test/media_device/meson.build b/test/media_device/meson.build
> index 1dfcdd8bd744..83dfe8f11d2f 100644
> --- a/test/media_device/meson.build
> +++ b/test/media_device/meson.build
> @@ -11,12 +11,12 @@ media_device_tests = [
> ]
>
> lib_mdev_test = static_library('lib_mdev_test', lib_mdev_test_sources,
> - dependencies : libcamera_dep,
> + dependencies : libcamera_private,
> include_directories : test_includes_internal)
>
> foreach t : media_device_tests
> exe = executable(t[0], t[1],
> - dependencies : libcamera_dep,
> + dependencies : libcamera_private,
> link_with : [test_libraries, lib_mdev_test],
> include_directories : test_includes_internal)
>
> diff --git a/test/meson.build b/test/meson.build
> index 045ad2a2d7c9..b8615e0fd3e6 100644
> --- a/test/meson.build
> +++ b/test/meson.build
> @@ -64,7 +64,7 @@ endforeach
>
> foreach t : internal_tests
> exe = executable(t[0], t[1],
> - dependencies : libcamera_dep,
> + dependencies : libcamera_private,
> link_with : test_libraries,
> include_directories : test_includes_internal)
>
> diff --git a/test/pipeline/ipu3/meson.build b/test/pipeline/ipu3/meson.build
> index d062ecd269f2..16701080ca2b 100644
> --- a/test/pipeline/ipu3/meson.build
> +++ b/test/pipeline/ipu3/meson.build
> @@ -6,7 +6,7 @@ ipu3_test = [
>
> foreach t : ipu3_test
> exe = executable(t[0], t[1],
> - dependencies : libcamera_dep,
> + dependencies : libcamera_private,
> link_with : test_libraries,
> include_directories : test_includes_internal)
>
> diff --git a/test/pipeline/rkisp1/meson.build b/test/pipeline/rkisp1/meson.build
> index ece147b054e4..364b5711a0f9 100644
> --- a/test/pipeline/rkisp1/meson.build
> +++ b/test/pipeline/rkisp1/meson.build
> @@ -6,7 +6,7 @@ rkisp1_test = [
>
> foreach t : rkisp1_test
> exe = executable(t[0], t[1],
> - dependencies : libcamera_dep,
> + dependencies : libcamera_private,
> link_with : test_libraries,
> include_directories : test_includes_internal)
>
> diff --git a/test/process/meson.build b/test/process/meson.build
> index d2272d509db3..af86b277db63 100644
> --- a/test/process/meson.build
> +++ b/test/process/meson.build
> @@ -6,7 +6,7 @@ process_tests = [
>
> foreach t : process_tests
> exe = executable(t[0], t[1],
> - dependencies : libcamera_dep,
> + dependencies : libcamera_private,
> link_with : test_libraries,
> include_directories : test_includes_internal)
>
> diff --git a/test/serialization/generated_serializer/meson.build b/test/serialization/generated_serializer/meson.build
> index 2460e0b114b3..9fb9cd1db968 100644
> --- a/test/serialization/generated_serializer/meson.build
> +++ b/test/serialization/generated_serializer/meson.build
> @@ -8,7 +8,7 @@ exe = executable('generated_serializer_test',
> generated_test_header,
> generated_test_serializer,
> ],
> - dependencies : libcamera_dep,
> + dependencies : libcamera_private,
> link_with : test_libraries,
> include_directories : [
> test_includes_internal,
> diff --git a/test/serialization/meson.build b/test/serialization/meson.build
> index 60ebf3255b28..5446e4907f33 100644
> --- a/test/serialization/meson.build
> +++ b/test/serialization/meson.build
> @@ -9,7 +9,7 @@ serialization_tests = [
>
> foreach t : serialization_tests
> exe = executable(t[0], [t[1], 'serialization_test.cpp'],
> - dependencies : libcamera_dep,
> + dependencies : libcamera_private,
> link_with : test_libraries,
> include_directories : test_includes_internal)
> test(t[0], exe, suite : 'serialization', is_parallel : true)
> diff --git a/test/v4l2_subdevice/meson.build b/test/v4l2_subdevice/meson.build
> index 40d39766af9b..d82be3c60b75 100644
> --- a/test/v4l2_subdevice/meson.build
> +++ b/test/v4l2_subdevice/meson.build
> @@ -7,7 +7,7 @@ v4l2_subdevice_tests = [
>
> foreach t : v4l2_subdevice_tests
> exe = executable(t[0], [t[1], 'v4l2_subdevice_test.cpp'],
> - dependencies : libcamera_dep,
> + dependencies : libcamera_private,
> link_with : test_libraries,
> include_directories : test_includes_internal)
> test(t[0], exe, suite : 'v4l2_subdevice', is_parallel : false)
> diff --git a/test/v4l2_videodevice/meson.build b/test/v4l2_videodevice/meson.build
> index e733518c0185..643f82edce5e 100644
> --- a/test/v4l2_videodevice/meson.build
> +++ b/test/v4l2_videodevice/meson.build
> @@ -16,7 +16,7 @@ v4l2_videodevice_tests = [
>
> foreach t : v4l2_videodevice_tests
> exe = executable(t[0], [t[1], 'v4l2_videodevice_test.cpp'],
> - dependencies : libcamera_dep,
> + dependencies : libcamera_private,
> link_with : test_libraries,
> include_directories : test_includes_internal)
> test(t[0], exe, suite : 'v4l2_videodevice', is_parallel : false)
> --
> 2.30.2
>
More information about the libcamera-devel
mailing list