Add documentation on soname / install_name issue

I don't have time to verify the solution again,
so the documentation is mostly from what I remember,
and the slint PR.
The Linux version may not be entirely correct, but at least it should
point people in the right direction.

doc/src/common_issues.md

@@ -1,5 +1,12 @@
 # Commonly encountered (Non-Corrosion) Issues
 
+## Table of Contents
+
+- [Linking Debug C/C++ libraries into Rust fails on Windows MSVC targets](#linking-debug-cc-libraries-into-rust-fails-on-windows-msvc-targets)
+- [Linking Rust static libraries into Debug C/C++ binaries fails on Windows MSVC targets](#linking-rust-static-libraries-into-debug-cc-binaries-fails-on-windows-msvc-targets)
+- [Missing `soname` on Linux for `cdylibs`](#missing-soname-on-linux-for-cdylibs)
+- [Missing `install_name` on MacOS for `ccdylibs` / Hardcoded references to the build-directory](#missing-installname-on-macos-for-ccdylibs--hardcoded-references-to-the-build-directory)
+
 ## Linking Debug C/C++ libraries into Rust fails on Windows MSVC targets
 
 `rustc` always links against the non-debug Windows runtime on `*-msvc` targets.
@@ -50,3 +57,32 @@ For debug builds, this is likely to be the preferable solution. It assumes that
 is built by the `cc` crate, which respects the `CFLAGS` and `CXXFLAGS` environment variables.
 
 [cxx]: https://github.com/dtolnay/cxx
+
+
+## Missing `soname` on Linux for `cdylibs`
+
+Cargo doesn't support setting the `soname` field for cdylib, which may cause issues.
+You can set the soname manually by passing a linker-flag such as `-Clink-arg=-Wl,-soname,libyour_crate.so`
+to the linker via `corrosion_add_target_local_rustflags()` and additionally seting the `IMPORTED_SONAME`
+property on the import CMake target:  
+```
+set_target_properties(your_crate-shared PROPERTIES IMPORTED_SONAME libyour_crate.so)
+```
+Replace `your_crate` with the name of your shared library as defined in the `[lib]` section of your Cargo.toml
+Manifest file.
+
+Attention: The Linux section may not be entirely correct, maybe `$ORIGIN` needs to be added to the linker arguments.
+Feel free to open a pull-request with corrections.
+
+## Missing `install_name` on MacOS for `ccdylibs` / Hardcoded references to the build-directory
+
+The solution here is essentially the same as in the previous section.
+```
+corrosion_add_target_local_rustflags(your_crate -Clink-arg=-Wl,-install_name,@rpath/libyour_crate.dylib,-current_version,${PROJECT_VERSION_MAJOR}.${PROJECT_VERSION_MINOR},-compatibility_version,${PROJECT_VERSION_MAJOR}.0)
+set_target_properties(your_crate-shared PROPERTIES IMPORTED_NO_SONAME 0)
+set_target_properties(your_crate-shared PROPERTIES IMPORTED_SONAME libyour_crate.dylib)
+```
+When building binaries using this shared library, you should set the build rpath to the output directory of
+your shared library, e.g. by setting `set(CMAKE_BUILD_RPATH ${YOUR_CUSTOM_OUTPUT_DIRECTORY})` before adding
+executables.
+For a practical example, you may look at [Slint PR 2455](https://github.com/slint-ui/slint/pull/2455).