Improve support for macOS dylib versioning

We now use the soversion to set compatibility_version and
current_version by default. This is the only sane thing we can do by
default because of the restrictions on the values that can be used for
compatibility and current version.

Users can override this value with the `darwin_versions:` kwarg, which
can be a single value or a two-element list of values. The first one
is the compatibility version and the second is the current version.

Fixes https://github.com/mesonbuild/meson/issues/3555
Fixes https://github.com/mesonbuild/meson/issues/1451

2 files changed, 18 insertions, 2 deletions

diff --git a/docs/markdown/Reference-manual.md b/docs/markdown/Reference-manual.md
index e830557..ea11f60 100644
--- a/docs/markdown/Reference-manual.md
+++ b/docs/markdown/Reference-manual.md
@@ -1183,13 +1183,20 @@ extra keyword arguments.
   `soversion` is `4`, a Windows DLL will be called `foo-4.dll` and one
   of the aliases of the Linux shared library would be
   `libfoo.so.4`. If this is not specified, the first part of `version`
-  is used instead. For example, if `version` is `3.6.0` and
+  is used instead (see below). For example, if `version` is `3.6.0` and
   `soversion` is not defined, it is set to `3`.
 - `version` a string specifying the version of this shared library,
   such as `1.1.0`. On Linux and OS X, this is used to set the shared
   library version in the filename, such as `libfoo.so.1.1.0` and
   `libfoo.1.1.0.dylib`. If this is not specified, `soversion` is used
-  instead (see below).
+  instead (see above).
+- `darwin_versions` *(added 0.48)* an integer, string, or a list of
+  versions to use for setting dylib `compatibility version` and
+  `current version` on macOS. If a list is specified, it must be
+  either zero, one, or two elements. If only one element is specified
+  or if it's not a list, the specified value will be used for setting
+  both compatibility version and current version. If unspecified, the
+  `soversion` will be used as per the aforementioned rules.
 - `vs_module_defs` a string, a File object, or Custom Target for a
   Microsoft module definition file for controlling symbol exports,
   etc., on platforms where that is possible (e.g. Windows).
diff --git a/docs/markdown/snippets/shared_library_darwin_versions.md b/docs/markdown/snippets/shared_library_darwin_versions.md
new file mode 100644
index 0000000..ad137f3
--- /dev/null
+++ b/docs/markdown/snippets/shared_library_darwin_versions.md
@@ -0,0 +1,9 @@
+## `shared_library()` now supports setting dylib compatibility and current version
+
+Now, by default `shared_library()` sets `-compatibility_version` and
+`-current_version` of a macOS dylib using the `soversion`.
+
+This can be overriden by using the `darwin_versions:` kwarg to
+[`shared_library()`](Reference-manual.md#shared_library). As usual, you can
+also pass this kwarg to `library()` or `build_target()` and it will be used in
+the appropriate circumstances.