Merge pull request #1361 from sdroege/staticlib-gc-sections-symbol-vi…

…sibility

linkage: Add a note about symbol visibility and unused sections to the paragraph about staticlibs

src/linkage.md

@@ -52,6 +52,16 @@ be ignored in favor of only building the artifacts specified by command line.
   compiled as dynamic libraries) will have to be specified manually when
   linking that static library from somewhere. The `--print=native-static-libs` flag may help with this.
 
+  Note that, because the resulting static library contains the code of all the
+  dependencies, including the standard library, and also exports all public
+  symbols of them, linking the static library into an executable or shared
+  library may need special care. In case of a shared library the list of
+  exported symbols will have to be limited via e.g. a linker or symbol version
+  script, exported symbols list (macOS), or module definition file (Windows).
+  Additionally, unused sections can be removed to remove all code of
+  dependencies that is not actually used (e.g. `--gc-sections` or `-dead_strip`
+  for macOS).
+
 * `--crate-type=cdylib`, `#![crate_type = "cdylib"]` - A dynamic system
   library will be produced.  This is used when compiling
   a dynamic library to be loaded from another language.  This output type will