Merge pull request #192 from ska-sa/shared-lib

Add experimental support for a shared library

.ci/configure.sh

@@ -16,4 +16,5 @@ shift
     --with-mlx5dv=$extras \
     --with-pcap=$extras \
     --with-cap=$extras \
+    --enable-shared=$extras \
     "$@"

.gitignore

@@ -12,6 +12,8 @@ Makefile.in
 /config.status
 /config.sub
 /configure
+/m4/lt*.m4
+/m4/libtool.m4
 /spead2.pc
 /python-build.cfg
 /wheelhouse

RELEASE-PROCESS

@@ -1,5 +1,8 @@
 - Update version number in doc/changelog.rst
 - Update version number in src/spead2/_version.py
+- Update the shared library version number in src/Makefile.am:
+  - If there are ABI changes, update the first number and reset the second to zero.
+  - Otherwise, increment the second number.
 - Check that .pyi stubs have been updated
 - Check that Github Actions successfully tested the release and built wheels
 - Install the sdist from Github Actions and check that it passes pytest

configure.ac

@@ -26,6 +26,7 @@ AC_PROG_RANLIB
 AC_ARG_VAR(AR, [Static library archiver command])
 AC_ARG_VAR(RANLIB, [Generate index to static library])
 AC_LANG(C++)
+LT_INIT([disable-static disable-shared])
 
 ### Check for -std=c++11
 
@@ -246,6 +247,7 @@ AM_CONDITIONAL([DEBUG_LOG], [test "x$enable_debug_log" = "xyes"])
 AM_CONDITIONAL([OPTIMIZED], [test "x$enable_optimized" != "xno"])
 AM_CONDITIONAL([COVERAGE], [test "x$enable_coverage" = "xyes"])
 AM_CONDITIONAL([LTO], [test "x$enable_lto" = "xyes"])
+AM_CONDITIONAL([SHARED_LIBRARY], [test "x$enable_shared" = "xyes"])
 AM_CONDITIONAL([SPEAD2_USE_IBV], [test "x$SPEAD2_USE_IBV" = "x1"])
 AM_CONDITIONAL([SPEAD2_USE_CUDA], [test "x$SPEAD2_USE_CUDA" = "x1"])
 AM_CONDITIONAL([SPEAD2_USE_GDRAPI], [test "x$SPEAD2_USE_GDRAPI" = "x1"])
@@ -272,6 +274,7 @@ SPEAD2_PRINT_CONDITION([debug logging], [DEBUG_LOG])
 SPEAD2_PRINT_CONDITION([compiler optimization], [OPTIMIZED])
 SPEAD2_PRINT_CONDITION([link-time optimization], [LTO])
 SPEAD2_PRINT_CONDITION([coverage], [COVERAGE])
+SPEAD2_PRINT_CONDITION([shared library], [SHARED_LIBRARY])
 SPEAD2_PRINT_FEATURE([MOVNTDQ instruction], [test "x$SPEAD2_USE_MOVNTDQ" = "x1"])
 echo ""
 echo "System calls:"

doc/introduction.rst

@@ -110,5 +110,16 @@ usage is
     ./configure --enable-lto AR=gcc-ar RANLIB=gcc-ranlib
 
 The installation will install some benchmark tools, a static library, and the
-header files. At the moment there is no intention to create a shared library,
-because the ABI is not stable.
+header files.
+
+Shared library
+^^^^^^^^^^^^^^
+There is experimental support for building a shared library. Pass
+``--enable-shared`` to ``configure``. It's not recommended for general use
+because the binary interface is likely to be incompatible between spead2
+versions, requiring software linked against the shared library to be
+recompiled after upgrading spead2 (which defeats one of the points of a shared
+library). It also exports a lot of symbols (e.g., from Boost) that may clash
+with other libraries. Performance may be lower than using the static library.
+It is made available for users who need to load the library dynamically as part
+of a plugin system.

src/Makefile.am

@@ -1,4 +1,4 @@
-# Copyright 2016, 2020 National Research Foundation (SARAO)
+# Copyright 2016, 2020, 2022 National Research Foundation (SARAO)
 #
 # This program is free software: you can redistribute it and/or modify it under
 # the terms of the GNU Lesser General Public License as published by the Free
@@ -100,3 +100,12 @@ libspead2_a_SOURCES = \
 	send_udp.cpp \
 	send_udp_ibv.cpp \
 	send_writer.cpp
+
+if SHARED_LIBRARY
+lib_LTLIBRARIES = libspead2.la
+libspead2_la_SOURCES = $(libspead2_a_SOURCES)
+libspead2_la_LDFLAGS = -shared -version-info 1:0:0
+# Dummy CXXFLAGS to force automake to build the sources independently for
+# this target.
+libspead2_la_CXXFLAGS = $(AM_CXXFLAGS)
+endif