From bda6618bb696d62c3c578832827faaf131cbbd65 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Niklas=20Hamb=C3=BCchen?= <mail@nh2.me>
Date: Sun, 11 Aug 2019 20:46:06 +0200
Subject: [PATCH] zlib: Add comments regarding static/shared linking.

The main explanation was taken from commit:

    e999def1 zlib: clean up static/shared distincion

The `SHARED_MODE=1` bit was originally introduced in commit:

    0bfc84b0 Cross-compile zlib for Windows
---
 pkgs/development/libraries/zlib/default.nix | 17 +++++++++++++++++
 1 file changed, 17 insertions(+)

diff --git a/pkgs/development/libraries/zlib/default.nix b/pkgs/development/libraries/zlib/default.nix
index 7fb5be1c3434..9f5af47c7268 100644
--- a/pkgs/development/libraries/zlib/default.nix
+++ b/pkgs/development/libraries/zlib/default.nix
@@ -1,5 +1,20 @@
 { stdenv
 , fetchurl
+# Regarding static/shared libaries, the current behaviour is:
+#
+# - static=true,  shared=true:  builds both and moves .a to the .static output;
+#                               in this case `pkg-config` auto detection will
+#                               not work if the .static output is given as
+#                               buildInputs to another package (#66461)
+# - static=true,  shared=false: builds .a only and leaves it in the main output
+# - static=false, shared=true:  builds shared only
+#
+# To get both `.a` and shared libraries in one output,
+# you currently have to use
+#   static=false, shared=true
+# and use
+#   .overrideAttrs (old: { dontDisableStatic = true; })
+# This is because by default, upstream zlib ./configure builds both.
 , static ? true
 , shared ? true
 }:
@@ -68,6 +83,8 @@ stdenv.mkDerivation (rec {
   ] ++ stdenv.lib.optionals (stdenv.hostPlatform.libc == "msvcrt") [
     "-f" "win32/Makefile.gcc"
   ] ++ stdenv.lib.optionals shared [
+    # Note that as of writing (zlib 1.2.11), this flag only has an effect
+    # for Windows as it is specific to `win32/Makefile.gcc`.
     "SHARED_MODE=1"
   ];