From 4fde15290c7696923457da6caad05c070accaeca Mon Sep 17 00:00:00 2001 From: Claude Date: Thu, 8 Oct 2026 06:51:19 +0000 Subject: [PATCH] docs: add workaround for luaossl build errors with GCC 15 (C23) 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) Claude-Session: https://claude.ai/code/session_01Fbxfe5Uw8eGzyXeS5y7RU2 --- docs/getting_started.md | 30 ++++++++++++++++++++++++++++++ 1 file changed, 30 insertions(+) diff --git a/docs/getting_started.md b/docs/getting_started.md index 06fcfa37..484816a1 100644 --- a/docs/getting_started.md +++ b/docs/getting_started.md @@ -34,6 +34,36 @@ $ luarocks install lapis > within its own runtime you will want to install Lapis targeting Lua 5.1. You > can use the `--lua-version=5.1` flag with LuaRocks to accomplish this. +### Troubleshooting luaossl Build Errors + +Lapis depends on [luaossl](https://github.com/wahern/luaossl), a C module that +LuaRocks compiles when it installs Lapis. GCC 15 and newer use the C23 standard +by default, and building luaossl as C23 needs recent releases of both luaossl +and OpenSSL. With older ones the install stops with compiler errors like these: + + src/openssl.c:12452:14: error: passing argument 1 of 'PEM_ASN1_write_bio' from incompatible pointer type [-Wincompatible-pointer-types] + src/openssl.c:1186:26: error: too many arguments to function 'optcmp'; expected 0, have 2 + +To work around it, have LuaRocks compile with GNU C17, which was the default +before GCC 15: + +```bash +$ luarocks install lapis CFLAGS="-O2 -fPIC -std=gnu17" +``` + +Setting `CFLAGS` replaces the flags LuaRocks uses by default, which is why the +value repeats `-O2 -fPIC`. Leaving out `-fPIC` makes the build fail when +linking. The setting applies to every C module the command compiles, and the +same argument works with other LuaRocks commands that compile luaossl, such as +`luarocks build --only-deps`. + +Alternatively, update OpenSSL, including its development headers. OpenSSL +fixed its part in 3.0.19, 3.3.6, 3.4.4, 3.5.5, 3.6.1 and 4.0.0, and every later +release in those series has the fix. The 3.1 and 3.2 series never got it. +luaossl fixed its part in release 20250929, and LuaRocks installs the newest +release unless your project pins an older one. A luaossl older than 20250929 +needs the `CFLAGS` workaround whatever your OpenSSL version. + ## Creating An Application ### `lapis` Command Line Tool