[libcamera-devel] [PATCH v4 1/3] meson: Shared Object version handling

[Laurent Pinchart]

On Thu, Oct 13, 2022 at 10:59:55AM +0100, Kieran Bingham wrote:
> The libcamera project is not yet ready to declare ABI nor API stability,
> but it will benefit the community to be able to provide more regular
> release cycles to determine 'versioned' points of history.
> 
> Ideally, these releases will be made at any ABI breakage, but can be
> made at arbitary time based points along the way.
> 
> To support releases which may not be ABI stable, declare the soversion
> of both the libcamera and libcamera-base library to be dependant upon
> both the major minor and patch component of the project version.
> 
> As part of this, introduce a new 'Versions' summary section to highlight
> the different version components that may become apparent within any
> given build.

Let's also document why EXCLUDE_SYMLINKS is added:

Bumping versions may leave dangling libcamera.so.* symlinks in build
directories. This will confuse Doxygen which will print during its
directory scanning phase a warning that the symlink can't be read. As we
don't need Doxygen to follow symlinks, disable it with EXCLUDE_SYMLINKS.

> Reviewed-by: Jacopo Mondi <jacopo at jmondi.org>
> Reviewed-by: Laurent Pinchart <laurent.pinchart at ideasonboard.com>
> Signed-off-by: Kieran Bingham <kieran.bingham at ideasonboard.com>
> 
> ---
> 
> v4:
>  - Use EXCLUDE_SYMLINKS
>  - Reduce redundant information from Versions summary
>  - -nvm appended when the sources do not match the project version.
>  - Fixed the update of the libcamera source version from the project
>    version in event of mismatch
> 
> v3:
>  - fix typo
>  - Use libcamera_version directly for SONAME.
>  - Fix ordering of EXCLUDE_PATTERNS
>  - Use meson.project_version() in the event the git versions
>    are incorrect.
>  - No need to present libcamera_version anymore
>    - Guaranteed to be the same as 'project_version'
> 
>  Documentation/Doxyfile.in      |  2 ++
>  meson.build                    | 32 ++++++++++++++++++++++++++++++++
>  src/libcamera/base/meson.build |  1 +
>  src/libcamera/meson.build      |  1 +
>  4 files changed, 36 insertions(+)
> 
> diff --git a/Documentation/Doxyfile.in b/Documentation/Doxyfile.in
> index 88dfcddaebf6..e4f0cd426d39 100644
> --- a/Documentation/Doxyfile.in
> +++ b/Documentation/Doxyfile.in
> @@ -66,6 +66,8 @@ EXCLUDE_SYMBOLS        = libcamera::BoundMethodArgs \
>                           *::details \
>                           std::*
>  
> +EXCLUDE_SYMLINKS       = YES
> +
>  HTML_OUTPUT            = api-html
>  
>  GENERATE_LATEX         = NO
> diff --git a/meson.build b/meson.build
> index 2c6173b4f97e..9b0966cb04c9 100644
> --- a/meson.build
> +++ b/meson.build
> @@ -26,6 +26,38 @@ endif
>  
>  libcamera_version = libcamera_git_version.split('+')[0]
>  
> +# A shallow clone, or a clone without a reachable tag equivalent to the
> +# meson.project_version() could leave the project in a mis-described state.
> +# Produce a warning in this event, and fix to a best effort.
> +if libcamera_version != meson.project_version()
> +    warning('The sources disagree about the version: '
> +            + libcamera_version + ' != ' + meson.project_version())
> +
> +    summary({'libcamera git version' : libcamera_git_version,
> +             'Source version match' : false,
> +            },
> +            bool_yn : true, section : 'Versions')
> +
> +    libcamera_git_version = libcamera_git_version.replace(libcamera_version,
> +                                                          meson.project_version())
> +    libcamera_version = meson.project_version()
> +
> +    # Append a marker to show we have modified this version string
> +    libcamera_git_version += '-nvm'
> +endif
> +
> +# Until we make ABI compatible releases, the full libcamera version is used as
> +# the soname. No ABI/API compatibility is guaranteed between releases. (x.x.x)

s/. (x.x.x)/(x.x.x)./ ?

You could also write x.y.z.

Same below.

> +#
> +# When automatic ABI based detection is used to increment the version, this

s/is used/will be used/

Other than this, this looks good to me.

> +# will bump the minor number. (x.x)
> +#
> +# When we declare a stable ABI/API we will provide a 1.0 release and the
> +# soversion at that point will be the 'major' release value. (x)
> +libcamera_soversion = libcamera_version
> +
> +summary({ 'Sources': libcamera_git_version, }, section : 'Versions')
> +
>  # This script generates the .tarball-version file on a 'meson dist' command.
>  meson.add_dist_script('utils/run-dist.sh')
>  
> diff --git a/src/libcamera/base/meson.build b/src/libcamera/base/meson.build
> index 7a75914ab2a8..7a7fd7e4ca87 100644
> --- a/src/libcamera/base/meson.build
> +++ b/src/libcamera/base/meson.build
> @@ -51,6 +51,7 @@ libcamera_base_args = [ '-DLIBCAMERA_BASE_PRIVATE' ]
>  libcamera_base_lib = shared_library('libcamera-base',
>                                      [libcamera_base_sources, libcamera_base_headers],
>                                      version : libcamera_version,
> +                                    soversion : libcamera_soversion,
>                                      name_prefix : '',
>                                      install : true,
>                                      cpp_args : libcamera_base_args,
> diff --git a/src/libcamera/meson.build b/src/libcamera/meson.build
> index 7fcbb2ddc9e7..5f39d2e2c60a 100644
> --- a/src/libcamera/meson.build
> +++ b/src/libcamera/meson.build
> @@ -161,6 +161,7 @@ libcamera_deps = [
>  libcamera = shared_library('libcamera',
>                             libcamera_sources,
>                             version : libcamera_version,
> +                           soversion : libcamera_soversion,
>                             name_prefix : '',
>                             install : true,
>                             include_directories : includes,

-- 
Regards,

Laurent Pinchart