Add section on configuration flags to README

Makefile.am

@@ -67,7 +67,7 @@ noinst_HEADERS += examples/random.h
 PRECOMPUTED_LIB = libsecp256k1_precomputed.la
 noinst_LTLIBRARIES = $(PRECOMPUTED_LIB)
 libsecp256k1_precomputed_la_SOURCES =  src/precomputed_ecmult.c src/precomputed_ecmult_gen.c
-libsecp256k1_precomputed_la_CPPFLAGS = $(SECP_INCLUDES)
+libsecp256k1_precomputed_la_CPPFLAGS = $(SECP_INCLUDES) $(SECP_CONFIG_DEFINES)
 
 if USE_EXTERNAL_ASM
 COMMON_LIB = libsecp256k1_common.la
@@ -86,7 +86,7 @@ endif
 endif
 
 libsecp256k1_la_SOURCES = src/secp256k1.c
-libsecp256k1_la_CPPFLAGS = $(SECP_INCLUDES)
+libsecp256k1_la_CPPFLAGS = $(SECP_INCLUDES) $(SECP_CONFIG_DEFINES)
 libsecp256k1_la_LIBADD = $(SECP_LIBS) $(COMMON_LIB) $(PRECOMPUTED_LIB)
 libsecp256k1_la_LDFLAGS = -no-undefined -version-info $(LIB_VERSION_CURRENT):$(LIB_VERSION_REVISION):$(LIB_VERSION_AGE)
 
@@ -101,17 +101,17 @@ bench_SOURCES = src/bench.c
 bench_LDADD = libsecp256k1.la $(SECP_LIBS) $(SECP_TEST_LIBS) $(COMMON_LIB)
 bench_internal_SOURCES = src/bench_internal.c
 bench_internal_LDADD = $(SECP_LIBS) $(COMMON_LIB) $(PRECOMPUTED_LIB)
-bench_internal_CPPFLAGS = $(SECP_INCLUDES)
+bench_internal_CPPFLAGS = $(SECP_INCLUDES) $(SECP_CONFIG_DEFINES)
 bench_ecmult_SOURCES = src/bench_ecmult.c
 bench_ecmult_LDADD = $(SECP_LIBS) $(COMMON_LIB) $(PRECOMPUTED_LIB)
-bench_ecmult_CPPFLAGS = $(SECP_INCLUDES)
+bench_ecmult_CPPFLAGS = $(SECP_INCLUDES) $(SECP_CONFIG_DEFINES)
 endif
 
 TESTS =
 if USE_TESTS
 noinst_PROGRAMS += tests
 tests_SOURCES = src/tests.c
-tests_CPPFLAGS = $(SECP_INCLUDES) $(SECP_TEST_INCLUDES)
+tests_CPPFLAGS = $(SECP_INCLUDES) $(SECP_TEST_INCLUDES) $(SECP_CONFIG_DEFINES)
 if VALGRIND_ENABLED
 tests_CPPFLAGS += -DVALGRIND
 noinst_PROGRAMS += valgrind_ctime_test
@@ -129,7 +129,7 @@ endif
 if USE_EXHAUSTIVE_TESTS
 noinst_PROGRAMS += exhaustive_tests
 exhaustive_tests_SOURCES = src/tests_exhaustive.c
-exhaustive_tests_CPPFLAGS = $(SECP_INCLUDES)
+exhaustive_tests_CPPFLAGS = $(SECP_INCLUDES) $(SECP_CONFIG_DEFINES)
 if !ENABLE_COVERAGE
 exhaustive_tests_CPPFLAGS += -DVERIFY
 endif
@@ -142,7 +142,7 @@ endif
 if USE_EXAMPLES
 noinst_PROGRAMS += ecdsa_example
 ecdsa_example_SOURCES = examples/ecdsa.c
-ecdsa_example_CPPFLAGS = -I$(top_srcdir)/include
+ecdsa_example_CPPFLAGS = -I$(top_srcdir)/include $(SECP_CONFIG_DEFINES)
 ecdsa_example_LDADD = libsecp256k1.la
 ecdsa_example_LDFLAGS = -static
 if BUILD_WINDOWS
@@ -152,7 +152,7 @@ TESTS += ecdsa_example
 if ENABLE_MODULE_ECDH
 noinst_PROGRAMS += ecdh_example
 ecdh_example_SOURCES = examples/ecdh.c
-ecdh_example_CPPFLAGS = -I$(top_srcdir)/include
+ecdh_example_CPPFLAGS = -I$(top_srcdir)/include $(SECP_CONFIG_DEFINES)
 ecdh_example_LDADD = libsecp256k1.la
 ecdh_example_LDFLAGS = -static
 if BUILD_WINDOWS
@@ -163,7 +163,7 @@ endif
 if ENABLE_MODULE_SCHNORRSIG
 noinst_PROGRAMS += schnorr_example
 schnorr_example_SOURCES = examples/schnorr.c
-schnorr_example_CPPFLAGS = -I$(top_srcdir)/include
+schnorr_example_CPPFLAGS = -I$(top_srcdir)/include $(SECP_CONFIG_DEFINES)
 schnorr_example_LDADD = libsecp256k1.la
 schnorr_example_LDFLAGS = -static
 if BUILD_WINDOWS
@@ -178,11 +178,11 @@ EXTRA_PROGRAMS = precompute_ecmult precompute_ecmult_gen
 CLEANFILES = $(EXTRA_PROGRAMS)
 
 precompute_ecmult_SOURCES = src/precompute_ecmult.c
-precompute_ecmult_CPPFLAGS = $(SECP_INCLUDES)
+precompute_ecmult_CPPFLAGS = $(SECP_INCLUDES) $(SECP_CONFIG_DEFINES)
 precompute_ecmult_LDADD = $(SECP_LIBS) $(COMMON_LIB)
 
 precompute_ecmult_gen_SOURCES = src/precompute_ecmult_gen.c
-precompute_ecmult_gen_CPPFLAGS = $(SECP_INCLUDES)
+precompute_ecmult_gen_CPPFLAGS = $(SECP_INCLUDES) $(SECP_CONFIG_DEFINES)
 precompute_ecmult_gen_LDADD = $(SECP_LIBS) $(COMMON_LIB)
 
 # See Automake manual, Section "Errors with distclean".

README.md

@@ -71,7 +71,157 @@ libsecp256k1 is built using autotools:
     $ make check  # run the test suite
     $ sudo make install  # optional
 
-To compile optional modules (such as Schnorr signatures), you need to run `./configure` with additional flags (such as `--enable-module-schnorrsig`). Run `./configure --help` to see the full list of available flags.
+
+To compile optional modules (such as Schnorr signatures), you need to run `./configure` with additional flags (such as `--enable-module-schnorrsig`). Run `./configure --help` to see the full list of available flags and environment variables.
+
+Configuration flags
+-----------
+
+The build process recognizes the following flags. Unless otherwise specified, valid values for each option are "yes" and "no".
+
+### Toggle Dev-Mode
+
+| Autotools           | Manual             | Default |
+|---------------------|--------------------|---------|
+| `--enable-dev_mode` | None               | no      |
+
+In dev mode, all binaries and modules are enabled by default but individual options can still be overridden explicitly. Options may have different default values when in dev-mode. This option is hidden from `./configure --help`.
+
+
+### Enable Coverage
+
+| Autotools           | Manual              | Default | Default (dev-mode) |
+|---------------------|---------------------|---------|--------------------|
+| `--enable-coverage` | `-DENABLE_COVERAGE` | no      | no                 |
+
+Enable compiler flags to support kcov coverage analysis. Compiles out all VERIFY code as a side effect.
+
+### Enable Benchmarks
+
+| Autotools            | Manual               | Default | Default (dev-mode) |
+|----------------------|----------------------|---------|--------------------|
+| `--enable-benchmark` | `-DENABLE_BENCHMARK` | yes     | yes                |
+
+Additionally compile the benchmarks.
+
+
+### Enable Tests
+
+| Autotools        | Manual           | Default | Default (dev-mode) |
+|------------------|------------------|---------|--------------------|
+| `--enable-tests` | `-DENABLE_TESTS` | yes     | yes                |
+
+Additionally compile the tests.
+
+### Enable Exhaustive tests
+
+| Autotools                   | Manual                      | Default | Default (dev-mode) |
+|-----------------------------|-----------------------------|---------|--------------------|
+| `--enable-exhaustive-tests` | `-DENABLE_EXHAUSTIVE_TESTS` | yes     | yes                |
+
+Additionally compile the tests.
+
+### Enable Examples
+
+| Autotools           | Manual              | Default | Default (dev-mode) |
+|---------------------|---------------------|---------|--------------------|
+| `--enable-examples` | `-DENABLE_EXAMPLES` | no      | yes                |
+
+Additionally compile the examples.
+
+### Enable Valgrind Checks
+
+| Autotools         | Manual | Default   | Default (dev-mode)  |
+|-------------------|--------|-----------|---------------------|
+| `--with-valgrind` | None   | auto      | auto                |
+
+Build with extra checks for running inside Valgrind. Valid values are "yes", "no", and "auto".
+
+### Enable External Default Callbacks
+
+| Autotools                             | Manual                               | Default | Default (dev-mode) |
+|---------------------------------------|--------------------------------------|---------|--------------------|
+| `--enable-external-default-callbacks` | `-DUSE_EXTERNAL_DEFAULT_CALLBACKS`   | no      | no                 |
+
+Enable external default callback functions. Ensure that you supply them in your code, otherwise you will get a linker error.
+
+### Allow Experimental Options
+
+| Autotools               | Manual                  | Default | Default (dev-mode) |
+|-------------------------|-------------------------|---------|--------------------|
+| `--enable-experimental` | `-DENABLE_EXPERIMENTAL` | no      | yes                |
+
+Allow passing of experimental build options. The following options are experimental:
+
+- `--with-asm=arm`
+
+### Enable ECDH Module
+
+| Autotools              | Manual                 | Default | Default (dev-mode) |
+|------------------------|------------------------|---------|--------------------|
+| `--enable-module-ecdh` | `-DENABLE_MODULE_ECDH` | no      | yes                |
+
+Enable the ECDH module.
+
+### Enable Recovery Module
+
+| Autotools                  | Manual                     | Default | Default (dev-mode) |
+|----------------------------|----------------------------|---------|--------------------|
+| `--enable-module-recovery` | `-DENABLE_MODULE_RECOVERY` | no      | yes                |
+
+Enable the ECDSA public key recovery module.
+
+### Enable Extrakeys Module
+
+| Autotools                   | Manual                      | Default | Default (dev-mode) |
+|-----------------------------|-----------------------------|---------|--------------------|
+| `--enable-module-extrakeys` | `-DENABLE_MODULE_EXTRAKEYS` | no      | yes                |
+
+Enable the extrakeys module. Extrakeys exports miscellaneous and supplimentary public key functions.
+
+### Enable Schnorrsig Module
+
+| Autotools                    | Manual                       | Default | Default (dev-mode) |
+|------------------------------|------------------------------|---------|--------------------|
+| `--enable-module-schnorrsig` | `-DENABLE_MODULE_SCHNORRSIG` | no      | yes                |
+
+Enable the Schnorr signatures module.
+
+### Override `widemul` Setting
+
+| Autotools                            | Manual    | Default | Default (dev-mode) |
+|--------------------------------------|-----------|---------|--------------------|
+| `--with-test-override-wide-multiply` | See below | auto    | auto               |
+
+Test-only override of the (autodetected by the C code) "widemul" setting, used in the multiplication implementation. Legal values are "int64" (for `[u]int64_t`), "int128" (for `[unsigned] __int128`), and "auto" (the default).
+
+`-DUSE_FORCE_WIDEMUL_INT128` is passed when "int128" is specified, and `-DUSE_FORCE_WIDEMUL_INT64` is passed when int64 is specified. Neither option is passed when "auto" is specified.
+
+### Assembly Optimizations
+
+| Autotools    | Manual    | Default | Default (dev-mode) |
+|--------------|-----------|---------|--------------------|
+| `--with-asm` | See below | auto    | auto               |
+
+Specifies the assembly options to use. Legal values are "x86_64", "arm", "no", and "auto". Please note that --with-asm=arm is an experimental option (see [Allow Experimental Options](#allow-experimental-options).
+
+`-USE_ASM_X86_64` is passed when "x86_64" is specified. `-DUSE_EXTERNAL_ASM` is passed when "arm" is passed. When "auto" is passed, the system checks if assembly optimizations are available for the current architecture and sets one of the above macros accordingly. Passing "none" completely disables assembly optimizations.
+
+### Tune `ecmult` Table Window
+
+| Autotools              | Manual                 | Default | Default (dev-mode) |
+|------------------------|------------------------|---------|--------------------|
+| `--with-ecmult-window` | `-DECMULT_WINDOW_SIZE` | auto    | auto               |
+
+Window size for ecmult precomputation for verification, specified as integer in range `[2..24]`. Larger values result in possibly better performance at the cost of an exponentially larger precomputed table. The table will store `2^(SIZE-1) * 64` bytes of data but can be larger in memory due to platform-specific padding and alignment. A window size larger than 15 will require you delete the prebuilt precomputed_ecmult.c file so that it can be rebuilt. For very large window sizes, use `make -j 1` to reduce memory use during compilation. "auto" is a reasonable setting for desktop machines (currently 15).
+
+### Tune `ecmult` Bit Precision
+
+| Autotools                     | Manual                   | Default | Default (dev-mode) |
+|-------------------------------|--------------------------|---------|--------------------|
+| `--with-ecmult-gen-precision` | `-DECMULT_GEN_PREC_BITS` | auto    | auto               |
+
+Precision bits to tune the precomputed table size for signing. Valid values are "2", "4", "8", and "auto". The size of the table is 32kB for 2 bits, 64kB for 4 bits, 512kB for 8 bits of precision. A larger table size usually results in possible faster signing. "auto" is a reasonable setting for desktop machines (currently 4).
 
 Usage examples
 -----------

configure.ac

@@ -224,7 +224,7 @@ fi
 AM_CONDITIONAL([VALGRIND_ENABLED],[test "$enable_valgrind" = "yes"])
 
 if test x"$enable_coverage" = x"yes"; then
-    AC_DEFINE(COVERAGE, 1, [Define this symbol to compile out all VERIFY code])
+    SECP_CONFIG_DEFINES="$SECP_CONFIG_DEFINES -DCOVERAGE=1"
     SECP_CFLAGS="-O0 --coverage $SECP_CFLAGS"
     LDFLAGS="--coverage $LDFLAGS"
 else
@@ -266,7 +266,7 @@ enable_external_asm=no
 
 case $set_asm in
 x86_64)
-  AC_DEFINE(USE_ASM_X86_64, 1, [Define this symbol to enable x86_64 assembly optimizations])
+  SECP_CONFIG_DEFINES="$SECP_CONFIG_DEFINES -DUSE_ASM_X86_64=1"
   ;;
 arm)
   enable_external_asm=yes
@@ -279,17 +279,17 @@ no)
 esac
 
 if test x"$enable_external_asm" = x"yes"; then
-  AC_DEFINE(USE_EXTERNAL_ASM, 1, [Define this symbol if an external (non-inline) assembly implementation is used])
+  SECP_CONFIG_DEFINES="$SECP_CONFIG_DEFINES -DUSE_EXTERNAL_ASM=1"
 fi
 
 
 # Select wide multiplication implementation
 case $set_widemul in
 int128)
-  AC_DEFINE(USE_FORCE_WIDEMUL_INT128, 1, [Define this symbol to force the use of the (unsigned) __int128 based wide multiplication implementation])
+  SECP_CONFIG_DEFINES="$SECP_CONFIG_DEFINES -DUSE_FORCE_WIDEMUL_INT128=1"
   ;;
 int64)
-  AC_DEFINE(USE_FORCE_WIDEMUL_INT64, 1, [Define this symbol to force the use of the (u)int64_t based wide multiplication implementation])
+  SECP_CONFIG_DEFINES="$SECP_CONFIG_DEFINES -DUSE_FORCE_WIDEMUL_INT64=1"
   ;;
 auto)
   ;;
@@ -316,7 +316,7 @@ case $set_ecmult_window in
     # not in range
     AC_MSG_ERROR($error_window_size)
   fi
-  AC_DEFINE_UNQUOTED(ECMULT_WINDOW_SIZE, $set_ecmult_window, [Set window size for ecmult precomputation])
+  SECP_CONFIG_DEFINES="$SECP_CONFIG_DEFINES -DECMULT_WINDOW_SIZE=$set_ecmult_window"
   ;;
 esac
 
@@ -329,7 +329,7 @@ fi
 
 case $set_ecmult_gen_precision in
 2|4|8)
-  AC_DEFINE_UNQUOTED(ECMULT_GEN_PREC_BITS, $set_ecmult_gen_precision, [Set ecmult gen precision bits])
+  SECP_CONFIG_DEFINES="$SECP_CONFIG_DEFINES -DECMULT_GEN_PREC_BITS=$set_ecmult_gen_precision"
   ;;
 *)
   AC_MSG_ERROR(['ecmult gen precision not 2, 4, 8 or "auto"'])
@@ -350,26 +350,26 @@ SECP_CFLAGS="$SECP_CFLAGS $WERROR_CFLAGS"
 ###
 
 if test x"$enable_module_ecdh" = x"yes"; then
-  AC_DEFINE(ENABLE_MODULE_ECDH, 1, [Define this symbol to enable the ECDH module])
+  SECP_CONFIG_DEFINES="$SECP_CONFIG_DEFINES -DENABLE_MODULE_ECDH=1"
 fi
 
 if test x"$enable_module_recovery" = x"yes"; then
-  AC_DEFINE(ENABLE_MODULE_RECOVERY, 1, [Define this symbol to enable the ECDSA pubkey recovery module])
+  SECP_CONFIG_DEFINES="$SECP_CONFIG_DEFINES -DENABLE_MODULE_RECOVERY=1"
 fi
 
 if test x"$enable_module_schnorrsig" = x"yes"; then
-  AC_DEFINE(ENABLE_MODULE_SCHNORRSIG, 1, [Define this symbol to enable the schnorrsig module])
+  SECP_CONFIG_DEFINES="$SECP_CONFIG_DEFINES -DENABLE_MODULE_SCHNORRSIG=1"
   enable_module_extrakeys=yes
 fi
 
 # Test if extrakeys is set after the schnorrsig module to allow the schnorrsig
 # module to set enable_module_extrakeys=yes
 if test x"$enable_module_extrakeys" = x"yes"; then
-  AC_DEFINE(ENABLE_MODULE_EXTRAKEYS, 1, [Define this symbol to enable the extrakeys module])
+  SECP_CONFIG_DEFINES="$SECP_CONFIG_DEFINES -DENABLE_MODULE_EXTRAKEYS=1"
 fi
 
 if test x"$enable_external_default_callbacks" = x"yes"; then
-  AC_DEFINE(USE_EXTERNAL_DEFAULT_CALLBACKS, 1, [Define this symbol if an external implementation of the default callbacks is used])
+  SECP_CONFIG_DEFINES="$SECP_CONFIG_DEFINES -DUSE_EXTERNAL_DEFAULT_CALLBACKS=1"
 fi
 
 ###
@@ -391,13 +391,13 @@ fi
 ### Generate output
 ###
 
-AC_CONFIG_HEADERS([src/libsecp256k1-config.h])
 AC_CONFIG_FILES([Makefile libsecp256k1.pc])
 AC_SUBST(SECP_INCLUDES)
 AC_SUBST(SECP_LIBS)
 AC_SUBST(SECP_TEST_LIBS)
 AC_SUBST(SECP_TEST_INCLUDES)
 AC_SUBST(SECP_CFLAGS)
+AC_SUBST(SECP_CONFIG_DEFINES)
 AM_CONDITIONAL([ENABLE_COVERAGE], [test x"$enable_coverage" = x"yes"])
 AM_CONDITIONAL([USE_TESTS], [test x"$enable_tests" != x"no"])
 AM_CONDITIONAL([USE_EXHAUSTIVE_TESTS], [test x"$enable_exhaustive_tests" != x"no"])

src/field.h

@@ -18,10 +18,6 @@
  *    imply normality.
  */
 
-#if defined HAVE_CONFIG_H
-#include "libsecp256k1-config.h"
-#endif
-
 #include "util.h"
 
 #if defined(SECP256K1_WIDEMUL_INT128)

src/field_5x52_impl.h

@@ -7,10 +7,6 @@
 #ifndef SECP256K1_FIELD_REPR_IMPL_H
 #define SECP256K1_FIELD_REPR_IMPL_H
 
-#if defined HAVE_CONFIG_H
-#include "libsecp256k1-config.h"
-#endif
-
 #include "util.h"
 #include "field.h"
 #include "modinv64_impl.h"

src/field_impl.h

@@ -7,10 +7,6 @@
 #ifndef SECP256K1_FIELD_IMPL_H
 #define SECP256K1_FIELD_IMPL_H
 
-#if defined HAVE_CONFIG_H
-#include "libsecp256k1-config.h"
-#endif
-
 #include "util.h"
 
 #if defined(SECP256K1_WIDEMUL_INT128)

src/modinv32.h

@@ -7,10 +7,6 @@
 #ifndef SECP256K1_MODINV32_H
 #define SECP256K1_MODINV32_H
 
-#if defined HAVE_CONFIG_H
-#include "libsecp256k1-config.h"
-#endif
-
 #include "util.h"
 
 /* A signed 30-bit limb representation of integers.