cpp: allow application to determine visibility attributes (#1431)

### Changelog
<!-- Write a one-sentence summary of the user-impacting change (API,
UI/UX, performance, etc) that could appear in a changelog. Write "None"
if there is no user-facing change -->

### Docs

<!-- Link to a Docs PR, tracking ticket in Linear, OR write "None" if no
documentation changes are needed. -->

### Description

Proposed as an alternative to
#1380.

Adds an `#ifndef` guard around the existing definition logic in
`visibility.hpp`. This allows application code to determine the meaning
of MCAP_PUBLIC directly, if the implementation in `visibility.hpp`
doesn't work for them.
<!-- Describe the problem, what has changed, and motivation behind those
changes. Pretend you are advocating for this change and the reader is
skeptical. -->

<!-- In addition to unit tests, describe any manual testing you did to
validate this change. -->

<table><tr><th>Before</th><th>After</th></tr><tr><td>

<!--before content goes here-->

</td><td>

<!--after content goes here-->

</td></tr></table>

<!-- If necessary, link relevant Linear or Github issues. Use `Fixes:
foxglove/repo#1234` to auto-close the Github issue or Fixes: FG-### for
Linear isses. -->

Author: james-rms

cpp/README.md

@@ -109,6 +109,20 @@ Refer to the API documentation in
 for full details. The high-level interfaces for reading and writing are
 `McapReader` and `McapWriter`.
 
+### Visibility
+
+By default, the MCAP library will attempt to export its symbols from the translation unit where
+`MCAP_IMPLEMENTATION` is defined, and import them elsewhere. See `mcap/visibility.hpp` for exact
+semantics. If your application requires something different, you can define the `MCAP_PUBLIC` macro
+before including the library.
+
+```cpp
+// use the MCAP library internally but keep all symbols hidden
+#define MCAP_IMPLEMENTATION
+#define MCAP_PUBLIC __attribute__((visibility("hidden")))
+#include <mcap/writer.hpp>
+```
+
 ## Releasing new versions
 
 1. Update the `#define MCAP_LIBRARY_VERSION` and all other occurrences of the same version number, e.g. in `conanfile.py`, `build.sh`, and others.

cpp/bench/conanfile.py

@@ -4,7 +4,7 @@
 class McapBenchmarksConan(ConanFile):
     settings = "os", "compiler", "build_type", "arch"
     generators = "cmake"
-    requires = "benchmark/1.7.0", "mcap/2.0.2"
+    requires = "benchmark/1.7.0", "mcap/2.1.0"
 
     def build(self):
         cmake = CMake(self)

cpp/build-docs.sh

@@ -4,7 +4,7 @@ set -e
 
 conan config init
 
-conan editable add ./mcap mcap/2.0.2
+conan editable add ./mcap mcap/2.1.0
 conan install docs --install-folder docs/build/Release \
   -s compiler.cppstd=17 -s build_type=Release --build missing
 

cpp/build.sh

@@ -4,7 +4,7 @@ set -e
 
 conan config init
 
-conan editable add ./mcap mcap/2.0.2
+conan editable add ./mcap mcap/2.1.0
 conan install test --install-folder test/build/Debug \
   -s compiler.cppstd=17 -s build_type=Debug --build missing
 

cpp/docs/conanfile.py

@@ -4,7 +4,7 @@
 class McapDocsConan(ConanFile):
     settings = "os", "compiler", "build_type", "arch"
     generators = "cmake"
-    requires = "mcap/2.0.2"
+    requires = "mcap/2.1.0"
 
     def build(self):
         cmake = CMake(self)

cpp/examples/conanfile.py

@@ -5,7 +5,7 @@ class McapExamplesConan(ConanFile):
     settings = "os", "compiler", "build_type", "arch"
     generators = "cmake"
     requires = [
-        "mcap/2.0.2",
+        "mcap/2.1.0",
         "protobuf/3.21.1",
         "nlohmann_json/3.10.5",
         "catch2/2.13.8",

cpp/mcap/conanfile.py

@@ -3,7 +3,7 @@
 
 class McapConan(ConanFile):
     name = "mcap"
-    version = "2.0.2"
+    version = "2.1.0"
     url = "https://github.com/foxglove/mcap"
     homepage = "https://github.com/foxglove/mcap"
     description = "A C++ implementation of the MCAP file format"

cpp/mcap/include/mcap/types.hpp

@@ -14,7 +14,7 @@
 
 namespace mcap {
 
-#define MCAP_LIBRARY_VERSION "2.0.2"
+#define MCAP_LIBRARY_VERSION "2.1.0"
 
 using SchemaId = uint16_t;
 using ChannelId = uint16_t;

cpp/mcap/include/mcap/visibility.hpp

@@ -1,24 +1,28 @@
-#pragma once
-
+/** Defines an MCAP_PUBLIC visibility attribute macro, which is used on all public interfaces.
+ *  This can be defined before including `mcap.hpp` to directly control symbol visibility.
+ *  If not defined externally, this library attempts to export symbols from the translation unit
+ *  where MCAP_IMPLEMENTATION is defined, and import them anywhere else.
+ */
+#ifndef MCAP_PUBLIC
 #if defined _WIN32 || defined __CYGWIN__
-#  ifdef __GNUC__
-#    define MCAP_EXPORT __attribute__((dllexport))
-#    define MCAP_IMPORT __attribute__((dllimport))
-#  else
-#    define MCAP_EXPORT __declspec(dllexport)
-#    define MCAP_IMPORT __declspec(dllimport)
-#  endif
 #  ifdef MCAP_IMPLEMENTATION
-#    define MCAP_PUBLIC MCAP_EXPORT
+#    ifdef __GNUC__
+#      define MCAP_PUBLIC __attribute__((dllexport))
+#    else
+#      define MCAP_PUBLIC __declspec(dllexport)
+#    endif
 #  else
-#    define MCAP_PUBLIC MCAP_IMPORT
+#    ifdef __GNUC__
+#      define MCAP_PUBLIC __attribute__((dllimport))
+#    else
+#      define MCAP_PUBLIC __declspec(dllimport)
+#    endif
 #  endif
 #else
-#  define MCAP_EXPORT __attribute__((visibility("default")))
-#  define MCAP_IMPORT
 #  if __GNUC__ >= 4
 #    define MCAP_PUBLIC __attribute__((visibility("default")))
 #  else
 #    define MCAP_PUBLIC
 #  endif
 #endif
+#endif

cpp/test/conanfile.py

@@ -4,7 +4,7 @@
 class McapTestConan(ConanFile):
     settings = "os", "compiler", "build_type", "arch"
     generators = "cmake"
-    requires = "catch2/2.13.8", "mcap/2.0.2", "nlohmann_json/3.10.5"
+    requires = "catch2/2.13.8", "mcap/2.1.0", "nlohmann_json/3.10.5"
 
     def build(self):
         cmake = CMake(self)