Merge pull request #644 from apache/hotfix/642-cmake-private-linking-…

…workaround-doc

Documentation for Workaround for Conan's CMake private linking issue

documents/building/README.md

@@ -103,6 +103,26 @@ To see a complete overview of the available build options use the following comm
 conan inspect . | grep build_
 ```
 
+#### CMake Private Linking Workaround
+
+When using Celix via Conan, you may encounter an [issue](https://github.com/apache/celix/issues/642) where libzip.so is not found by linker.
+This is due to a [bug in Conan](https://github.com/conan-io/conan/issues/7192).
+
+A workaround we adopt in Celix is adding the following to conanfile.py:
+
+```python
+    def generate(self):
+        deps = CMakeDeps(self)
+        deps.generate()
+        tc = CMakeToolchain(self)
+        # the following is workaround for https://github.com/conan-io/conan/issues/7192
+        if self.settings.os == "Linux":
+            tc.cache_variables["CMAKE_EXE_LINKER_FLAGS"] = "-Wl,--unresolved-symbols=ignore-in-shared-libs"
+        elif self.settings.os == "Macos":
+            tc.cache_variables["CMAKE_EXE_LINKER_FLAGS"] = "-Wl,-undefined -Wl,dynamic_lookup"
+        tc.generate()
+```
+
 ### Building Apache Celix directly using CMake
 The following packages (libraries + headers) should be installed on your system: