libcamera/base: Validate internal headers as private

Headers which must not be exposed as part of the public libcamera API
should 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).

Build targets which are intended to use the private API's will use the
libcamera_private to handle the automatic definition of the inclusion
guard.

Reviewed-by: Laurent Pinchart <laurent.pinchart@ideasonboard.com>
Signed-off-by: Kieran Bingham <kieran.bingham@ideasonboard.com>

include/libcamera/base/event_dispatcher.h

@@ -9,6 +9,8 @@
 
 #include <vector>
 
+#include <libcamera/base/private.h>
+
 namespace libcamera {
 
 class EventNotifier;

include/libcamera/base/event_dispatcher_poll.h

@@ -11,6 +11,8 @@
 #include <map>
 #include <vector>
 
+#include <libcamera/base/private.h>
+
 #include <libcamera/base/event_dispatcher.h>
 
 struct pollfd;

include/libcamera/base/event_notifier.h

@@ -7,6 +7,8 @@
 #ifndef __LIBCAMERA_BASE_EVENT_NOTIFIER_H__
 #define __LIBCAMERA_BASE_EVENT_NOTIFIER_H__
 
+#include <libcamera/base/private.h>
+
 #include <libcamera/base/object.h>
 #include <libcamera/base/signal.h>
 

include/libcamera/base/file.h

@@ -12,6 +12,8 @@
 #include <map>
 #include <string>
 
+#include <libcamera/base/private.h>
+
 #include <libcamera/base/class.h>
 #include <libcamera/base/span.h>
 

include/libcamera/base/log.h

@@ -10,6 +10,8 @@
 #include <chrono>
 #include <sstream>
 
+#include <libcamera/base/private.h>
+
 #include <libcamera/base/class.h>
 #include <libcamera/base/utils.h>
 

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',
     'span.h',

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 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

include/libcamera/base/semaphore.h

@@ -9,6 +9,7 @@
 
 #include <condition_variable>
 
+#include <libcamera/base/private.h>
 #include <libcamera/base/thread.h>
 
 namespace libcamera {

include/libcamera/base/thread.h

@@ -12,6 +12,8 @@
 #include <sys/types.h>
 #include <thread>
 
+#include <libcamera/base/private.h>
+
 #include <libcamera/base/message.h>
 #include <libcamera/base/signal.h>
 #include <libcamera/base/utils.h>

include/libcamera/base/timer.h

@@ -10,6 +10,8 @@
 #include <chrono>
 #include <stdint.h>
 
+#include <libcamera/base/private.h>
+
 #include <libcamera/base/object.h>
 #include <libcamera/base/signal.h>
 

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 */

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

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)

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)

src/ipa/raspberrypi/meson.build

@@ -3,7 +3,7 @@
 ipa_name = 'ipa_rpi'
 
 rpi_ipa_deps = [
-    libcamera_dep,
+    libcamera_private,
     dependency('boost'),
     libatomic,
 ]

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)

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)

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)

src/libcamera/meson.build

@@ -112,6 +112,7 @@ endif
 libcamera_deps = [
     libatomic,
     libcamera_base,
+    libcamera_base_private,
     libdl,
     libgnutls,
     liblttng,
@@ -143,9 +144,15 @@ libcamera_dep = declare_dependency(sources : [
                                        libcamera_generated_ipa_headers,
                                    ],
                                    include_directories : libcamera_includes,
-                                   dependencies: libcamera_base,
+                                   dependencies : libcamera_base,
                                    link_with : libcamera)
 
+# Internal dependency 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,

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',

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)

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)

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])
 

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)
 

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]

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)
 

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)
 

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)
 

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)
 

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)
 

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)
 

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,

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)

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)

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)