Merge pull request #456 from libtom/mp-has-comment

s_mp_rand_platform: add comment regarding MP_HAS requiring dead code elim

Author: sjaeckel

doc/bn.tex

@@ -298,6 +298,11 @@ \subsection{Build Depends}
 includes itself twice). This is to help resolve as many dependencies as possible.  In the last pass
 the symbol \texttt{LTM\_LAST} will be defined. This is useful for ``trims''.
 
+Note that the configuration system relies
+on dead code elimination. Unfortunately this can result in linking errors on compilers which
+perform insufficient dead code elimination. In particular MSVC with the /Od option enabled shows this issue.
+The issue can be resolved by passing the /O option instead to the compiler.
+
 \subsection{Build Trims}
 A trim is a manner of removing functionality from a function that is not required.  For instance,
 to perform RSA cryptography you only require exponentiation with odd moduli so even moduli support

s_mp_rand_platform.c

@@ -117,6 +117,25 @@ mp_err s_read_wincsp(void *p, size_t n);
 mp_err s_read_getrandom(void *p, size_t n);
 mp_err s_read_urandom(void *p, size_t n);
 
+/*
+ * Note: libtommath relies on dead code elimination
+ * for the configuration system, i.e., the MP_HAS macro.
+ *
+ * If you observe linking errors in this functions,
+ * your compiler does not perform the dead code compilation
+ * such that the unused functions are still referenced.
+ *
+ * This happens for example for MSVC if the /Od compilation
+ * option is given. The option /Od instructs MSVC to
+ * not perform any "optimizations", not even removal of
+ * dead code wrapped in `if (0)` blocks.
+ *
+ * If you still insist on compiling with /Od, simply
+ * comment out the lines which result in linking errors.
+ *
+ * We intentionally don't fix this issue in order
+ * to have a single point of failure for misconfigured compilers.
+ */
 mp_err s_mp_rand_platform(void *p, size_t n)
 {
    mp_err err = MP_ERR;