doc: describe how to reduce the binary size #1973

pull fametrano wants to merge 1 commits into bitcoin-core:master from fametrano:docs-gc-sections changing 1 files +21 −0

fametrano commented at 8:21 PM on October 21, 2026: contributor

A static build linked with --gc-sections can drop the precomputed tables and code a program never calls, and the README does not say how. This adds a section on it, with the functions that use each table, the options that set the table sizes and the advice against -Os. It addresses the last open item of #1065.

text size in bytes of a program linked against the static library, built with the default modules and the section's flags (programs and commands):

program	without gc	with gc	tables kept with gc
ECDSA signing, `secp256k1_context_create`	1341897	126952	`ecmult_gen`
ECDSA verification, `secp256k1_context_static`	1342105	1124953	`ecmult`
ECDSA verification, `secp256k1_context_create`	1342081	1229593	both
ECDH, `secp256k1_context_static`	1342001	70740	neither

Measured with size and nm (Debian, aarch64, GCC 14.2, GNU ld 2.44). With gc, the CMake command gives the same sizes as the Autotools one for signing, verification with the static context and ECDH.

theStack added the label user-documentation on Oct 23, 2026

in README.md:156 in 2e5529f275

 151 | +To get this with GNU ld, compile the library with `-ffunction-sections -fdata-sections` and link your program with `-Wl,--gc-sections`:
 152 | +
 153 | +    $ ./configure --disable-shared CFLAGS="-g -O2 -ffunction-sections -fdata-sections"    # Autotools
 154 | +    $ cmake -B build -DBUILD_SHARED_LIBS=OFF -DCMAKE_C_FLAGS="-ffunction-sections -fdata-sections"    # CMake
 155 | +
 156 | +With the default modules, GCC 14 and GNU ld on aarch64, the code and tables of a program that only signs shrink from 1.3 MB to 0.13 MB. A program that only verifies shrinks to 1.1 MB with `secp256k1_context_static` and to 1.2 MB with a context made by `secp256k1_context_create`, which keeps the signing table linked in.

real-or-random commented at 6:25 PM on October 30, 2026:

I don't think we need that sentence, and it's hard to maintain.

in README.md:150 in 2e5529f275
```
 143 | @@ -144,6 +144,18 @@ In "Developer Command Prompt for VS 2022":
 144 |      >cmake -B build -T ClangCL
 145 |      >cmake --build build --config RelWithDebInfo
 146 |  
 147 | +Reducing the size of a static build
 148 | +-----------------------------------
 149 | +
 150 | +The library contains large precomputed tables, one for signing and one for verification. A program linked statically only needs the tables of the functions it calls, but the linker keeps them unless each function and table sits in its own section and unused sections are discarded.
```
real-or-random commented at 6:40 PM on October 30, 2026:

I think this is misguided. Signing and verification are just two examples of functions that use the tables. The description should be more generic and differentiate between API functions which cannot the static context (e.g., signing, key gen, ecdh, ...) and those which can. Though it's a still a bit hard to describe because we the latter includes functions which use the ecmult table and some that don't use any table (and in the API docs we rightly don't say anything about this). It's probably good enough to roughly list those here that require the ecmult table (anything else than verification?)
real-or-random commented at 6:41 PM on October 30, 2026: contributor

Concept ACK

I think if we add such a section to the README, it should also mention the config options to tweak the table sizes and also that we discourate -Os (see https://github.com/bitcoin-core/secp256k1/discussions/1436 for details)
fametrano force-pushed on Oct 31, 2026
fametrano renamed this:
~~doc: describe dropping unused tables from static builds~~
doc: describe how to reduce the binary size
on Oct 31, 2026
fametrano commented at 4:24 AM on October 31, 2026: contributor

I pushed the rewrite. The README no longer gives sizes. It describes the functions by context and table, names the table size options and advises against -Os.

To your question: besides verification, the ecmult table is used by public key recovery, public key tweaking and some MuSig2 and Silent Payments functions.

One point differs from your list: secp256k1_ecdh works with secp256k1_context_static and uses neither table, because it relies on secp256k1_ecmult_const_ge. The last row of the table in the PR description measures this, and the documentation of secp256k1_context_randomize names ECDH as the exception to its rule of thumb. So the section lists ECDH among the functions that use no table. Tell me if you meant something else.
theStack commented at 6:54 AM on October 31, 2026: contributor

Concept ACK

doc: describe how to reduce the binary size

Compiling with -ffunction-sections -fdata-sections and linking with
-Wl,--gc-sections lets the linker drop the precomputed tables and code
that a program never calls. Document this in the README, with the API
functions that use each table, the options that set the table sizes and
the advice against -Os.

Addresses the last open item of #1065.

9e1b054cfa

fametrano force-pushed on Nov 2, 2026

Contributors

Labels

Linked (view graph)

#1065 Further changes after making tables static