Skip to content

docs: add workaround for luaossl build errors with GCC 15 (C23) - #821

Open
a-schaefers wants to merge 1 commit into
leafo:masterfrom
a-schaefers:docs/luaossl-gcc15-c23-install-workaround
Open

a-schaefers wants to merge 1 commit into
leafo:masterfrom
a-schaefers:docs/luaossl-gcc15-c23-install-workaround

Conversation

@a-schaefers

@a-schaefers a-schaefers commented Oct 8, 2026 •

Copy link
Copy Markdown

Related to #802

GCC 15 and newer compile C as gnu23 by default. luaossl, a required dependency of lapis, only compiles as C23 when both luaossl and the OpenSSL headers it builds against carry C23 fixes, so on those toolchains luarocks install lapis stops while building luaossl. This is the build failure reported in leafo/lapis issue 802.

Add a "Troubleshooting luaossl Build Errors" section under Basic Setup in the Getting Started guide. It:

  • shows the compiler errors users see, copied from a real GCC 15.2 build
  • documents the workaround, which works on every LuaRocks 3.x because VAR=VALUE arguments set LuaRocks variables for every rock the command builds, including dependencies: luarocks install lapis CFLAGS="-O2 -fPIC -std=gnu17"
  • explains why -O2 -fPIC is repeated: a CFLAGS variable replaces LuaRocks' Unix default of "-O2 -fPIC", and without -fPIC the modules fail to link
  • notes that the same argument works for luarocks build --only-deps
  • gives the alternative fix: OpenSSL fixed its ocsp.h macro in 3.0.19, 3.3.6, 3.4.4, 3.5.5, 3.6.1 and 4.0.0 (3.1 and 3.2 never got it), and luaossl fixed its own function prototypes in 20250929 (LuaRocks currently installs 20260910-0). A project that pins an older luaossl still needs the flag

Verified with GCC 15.2.0 and binutils 2.45 from Ubuntu 25.10, Lua 5.1, and both LuaRocks 3.8.0 (Ubuntu's package) and 3.13.0:

  • OpenSSL 3.0.13 headers, plain luarocks install lapis: fails in luaossl 20260910-0 with the PEM_ASN1_write_bio error at src/openssl.c:12452
  • same setup with the CFLAGS argument: installs. lapis loads, hmac_sha1 and hmac_sha256 match the RFC 2202 and RFC 4231 test vectors, signed values and CSRF tokens round-trip, and a mock request sets a signed session cookie
  • luaossl 20220711-0: fails as C23 even against OpenSSL 3.5.5 headers (optcmp, get_ex_data and set_ex_data errors). With the CFLAGS argument it builds and its HMAC output is correct
  • OpenSSL 3.5.5 headers and libraries from Ubuntu 26.04, no extra flags: lapis with luaossl 20260910-0 installs and passes the same checks, and luaossl 20250929-0 builds and runs
  • CFLAGS="-std=gnu17" without -fPIC: luaossl and lpeg fail to link with "relocation R_X86_64_PC32 ... recompile with -fPIC"
  • luarocks build --only-deps on an app rockspec that depends on lapis: fails without the argument and installs with it
  • OpenSSL release tags: the fixed ocsp.h macro is in 3.0.19, 3.3.6, 3.4.4, 3.5.5, 3.6.1 and 4.0.0 and in the next patch release of each, and missing from 3.0.18, 3.1.8, 3.2.6, 3.3.5, 3.4.3, 3.5.4 and 3.6.0

GCC 15 and newer compile C as gnu23 by default. luaossl, a required
dependency of lapis, only compiles as C23 when both luaossl and the
OpenSSL headers it builds against carry C23 fixes, so on those
toolchains `luarocks install lapis` stops while building luaossl. This
is the build failure reported in leafo/lapis issue 802.

Add a "Troubleshooting luaossl Build Errors" section under Basic Setup
in the Getting Started guide. It:

- shows the compiler errors users see, copied from a real GCC 15.2 build
- documents the workaround, which works on every LuaRocks 3.x because
  VAR=VALUE arguments set LuaRocks variables for every rock the command
  builds, including dependencies:
      luarocks install lapis CFLAGS="-O2 -fPIC -std=gnu17"
- explains why -O2 -fPIC is repeated: a CFLAGS variable replaces
  LuaRocks' Unix default of "-O2 -fPIC", and without -fPIC the modules
  fail to link
- notes that the same argument works for `luarocks build --only-deps`
- gives the alternative fix: OpenSSL fixed its ocsp.h macro in 3.0.19,
  3.3.6, 3.4.4, 3.5.5, 3.6.1 and 4.0.0 (3.1 and 3.2 never got it), and
  luaossl fixed its own function prototypes in 20250929 (LuaRocks
  currently installs 20260910-0). A project that pins an older luaossl
  still needs the flag

Verified with GCC 15.2.0 and binutils 2.45 from Ubuntu 25.10, Lua 5.1,
and both LuaRocks 3.8.0 (Ubuntu's package) and 3.13.0:

- OpenSSL 3.0.13 headers, plain `luarocks install lapis`: fails in
  luaossl 20260910-0 with the PEM_ASN1_write_bio error at
  src/openssl.c:12452
- same setup with the CFLAGS argument: installs. lapis loads,
  hmac_sha1 and hmac_sha256 match the RFC 2202 and RFC 4231 test
  vectors, signed values and CSRF tokens round-trip, and a mock request
  sets a signed session cookie
- luaossl 20220711-0: fails as C23 even against OpenSSL 3.5.5 headers
  (optcmp, get_ex_data and set_ex_data errors). With the CFLAGS
  argument it builds and its HMAC output is correct
- OpenSSL 3.5.5 headers and libraries from Ubuntu 26.04, no extra
  flags: lapis with luaossl 20260910-0 installs and passes the same
  checks, and luaossl 20250929-0 builds and runs
- CFLAGS="-std=gnu17" without -fPIC: luaossl and lpeg fail to link with
  "relocation R_X86_64_PC32 ... recompile with -fPIC"
- `luarocks build --only-deps` on an app rockspec that depends on lapis:
  fails without the argument and installs with it
- OpenSSL release tags: the fixed ocsp.h macro is in 3.0.19, 3.3.6,
  3.4.4, 3.5.5, 3.6.1 and 4.0.0 and in the next patch release of each,
  and missing from 3.0.18, 3.1.8, 3.2.6, 3.3.5, 3.4.3, 3.5.4 and 3.6.0

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Fbxfe5Uw8eGzyXeS5y7RU2
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants