build: Add extensive docs on visibility issues

Author: real-or-random

include/secp256k1.h

@@ -133,35 +133,56 @@ typedef int (*secp256k1_nonce_function)(
 # define SECP256K1_NO_BUILD
 #endif
 
-/* Symbol visibility. See https://gcc.gnu.org/wiki/Visibility */
-/* DLL_EXPORT is defined internally for shared builds */
+/* Symbol visibility. */
 #if defined(_WIN32) || defined(__CYGWIN__)
-# ifdef SECP256K1_BUILD
-#  ifdef DLL_EXPORT
+ /* GCC for Windows (e.g., MinGW) and for Cygwin accept the __declspec syntax
+  * for MVSC compatibility, see "Microsoft Windows Function Attributes" in the
+  * GCC manual. Note that __attribute__ ((visibility("default"))) is not exactly
+  * equivalent to __declspec (dllexport), and as a result, we want the latter
+  * even on GCC, see https://gcc.gnu.org/wiki/Visibility. */
+# if defined(SECP256K1_BUILD)
+#  if defined(DLL_EXPORT)
+   /* Building libsecp256k1 as a DLL. */
 #   define SECP256K1_API            __declspec (dllexport)
 #   define SECP256K1_API_VAR extern __declspec (dllexport)
 #  endif
 # elif defined(SECP256K1_IMPORT_AS_STATICLIB) && defined(SECP256K1_IMPORT_AS_DLL)
 #  error "At most one of SECP256K1_IMPORT_AS_STATICLIB and SECP256K1_IMPORT_AS_DLL must be defined."
 # elif defined(SECP256K1_IMPORT_AS_STATICLIB)
+   /* Linking against static libsecp256k1 requested explicitly. */
 #  define SECP256K1_API
 #  define SECP256K1_API_VAR  extern
 # elif defined(SECP256K1_IMPORT_AS_DLL)
+   /* Linking against libsecp256k1 DLL requested explicitly. */
 #  define SECP256K1_API             __declspec (dllimport)
 #  define SECP256K1_API_VAR  extern __declspec (dllimport)
-# elif defined _MSC_VER
+# elif defined(_MSC_VER)
+   /* No method requested explicitly. The following works on MSVC for both
+    * static and dynamic linking, as long as if at least one function is
+    * imported (i.e., not only variables are imported), which should be the case
+    * for any meaningful program that uses the libsecp256k1 API. The drawback of
+    * the following is that it may provoke linker warnings LNK4217 and LNK4286.
+    * See "Windows DLLs" in the libtool manual. */
 #  define SECP256K1_API
 #  define SECP256K1_API_VAR  extern __declspec (dllimport)
-# elif defined DLL_EXPORT
+# elif defined(DLL_EXPORT)
+   /* No method requested explicitly and we're not on MSVC. We make an educated
+    * guess based on DLL_EXPORT: If the importing program is itself a DLL, then
+    * it is likely that it also wants to import libsecp256k1 as a DLL. If our
+    * guess is wrong, the user will need to make a specific request using the
+    * macros checked above. See "Windows DLLs" in the libtool manual. */
 #  define SECP256K1_API             __declspec (dllimport)
 #  define SECP256K1_API_VAR  extern __declspec (dllimport)
 # endif
 #endif
 #ifndef SECP256K1_API
 # if defined(__GNUC__) && (__GNUC__ >= 4) && defined(SECP256K1_BUILD)
+   /* Building libsecp256k1 on non-Windows using GCC or compatible. */
 #  define SECP256K1_API             __attribute__ ((visibility ("default")))
 #  define SECP256K1_API_VAR  extern __attribute__ ((visibility ("default")))
 # else
+   /* Linking against libsecp256k1,
+      or building libsecp256k1 using an unknown compiler. */
 #  define SECP256K1_API
 #  define SECP256K1_API_VAR  extern
 # endif