Failed build on Alpine Linux 3.23.2 of version 1.3.16

[Roman3349]

Describe the bug
Build for paho.mqtt.c fails on Alpine Linux 3.23.

To Reproduce
Take a library trace as outlined in the README, and/or have a program or describe the steps to reproduce the behavior:

1. Install Alpine Linux 3.23
2. apk update
3. apk add cmake openssl-dev git
4. git clone https://github.com/eclipse-paho/paho.mqtt.c.git
5. cd paho.mqtt.c/
6. cmake -B build -DPAHO_BUILD_SHARED=TRUE -DPAHO_WITH_SSL=TRUE -DPAHO_WITH_UNIX_SOCKETS=TRUE -DPAHO_BUILD_SAMPLES=TRUE -DPAHO_ENABLE_TESTING=FALSE -DCMAKE_BUILD_RPATH_USE_ORIGIN=ON
7. cmake --build build

Expected behavior
Successful build.

Screenshots
If applicable, add screenshots to help explain your problem.

Log files
Please try to attach log files rather than pasting the log contents. It makes the issues easier to read.

alpine:~/paho.mqtt.c$ cmake -B build -DPAHO_BUILD_SHARED=TRUE -DPAHO_WITH_SSL=TRUE -DPAHO_WITH_UNIX_SOCKETS=TRUE -DPAHO_BUILD_SAMPLES=TRUE -DPAHO_ENABLE_TESTING=FALSE -DCMAKE_BUILD_RPATH_USE_ORIGIN=ON
-- The C compiler identification is GNU 15.2.0
-- Detecting C compiler ABI info
-- Detecting C compiler ABI info - done
-- Check for working C compiler: /usr/bin/cc - skipped
-- Detecting C compile features
-- Detecting C compile features - done
-- CMake version: 4.1.3
-- CMake system name: Linux
-- Timestamp is 2026-02-27T00:04:23Z
-- Found OpenSSL: /usr/lib/libcrypto.so (found version "3.5.5")
-- Using OpenSSL with headers at /usr/include
-- Configuring done (0.3s)
-- Generating done (0.1s)
-- Build files have been written to: /home/roman/paho.mqtt.c/build
alpine:~/paho.mqtt.c$ cmake --build build
[  1%] Building C object src/CMakeFiles/common_obj.dir/MQTTTime.c.o
[  2%] Building C object src/CMakeFiles/common_obj.dir/MQTTProtocolClient.c.o
[  3%] Building C object src/CMakeFiles/common_obj.dir/Clients.c.o
[  4%] Building C object src/CMakeFiles/common_obj.dir/utf-8.c.o
[  5%] Building C object src/CMakeFiles/common_obj.dir/MQTTPacket.c.o
[  6%] Building C object src/CMakeFiles/common_obj.dir/MQTTPacketOut.c.o
[  8%] Building C object src/CMakeFiles/common_obj.dir/Messages.c.o
[  9%] Building C object src/CMakeFiles/common_obj.dir/Tree.c.o
[ 10%] Building C object src/CMakeFiles/common_obj.dir/Socket.c.o
[ 11%] Building C object src/CMakeFiles/common_obj.dir/Log.c.o
[ 12%] Building C object src/CMakeFiles/common_obj.dir/MQTTPersistence.c.o
[ 13%] Building C object src/CMakeFiles/common_obj.dir/Thread.c.o
[ 15%] Building C object src/CMakeFiles/common_obj.dir/MQTTProtocolOut.c.o
[ 16%] Building C object src/CMakeFiles/common_obj.dir/MQTTPersistenceDefault.c.o
[ 17%] Building C object src/CMakeFiles/common_obj.dir/SocketBuffer.c.o
[ 18%] Building C object src/CMakeFiles/common_obj.dir/LinkedList.c.o
[ 19%] Building C object src/CMakeFiles/common_obj.dir/MQTTProperties.c.o
[ 20%] Building C object src/CMakeFiles/common_obj.dir/MQTTReasonCodes.c.o
[ 22%] Building C object src/CMakeFiles/common_obj.dir/Base64.c.o
[ 23%] Building C object src/CMakeFiles/common_obj.dir/SHA1.c.o
[ 24%] Building C object src/CMakeFiles/common_obj.dir/WebSocket.c.o
[ 25%] Building C object src/CMakeFiles/common_obj.dir/Proxy.c.o
[ 26%] Building C object src/CMakeFiles/common_obj.dir/StackTrace.c.o
[ 27%] Building C object src/CMakeFiles/common_obj.dir/Heap.c.o
[ 27%] Built target common_obj
[ 29%] Building C object src/CMakeFiles/paho-mqtt3c.dir/MQTTClient.c.o
[ 30%] Linking C shared library libpaho-mqtt3c.so
[ 30%] Built target paho-mqtt3c
[ 31%] Building C object src/CMakeFiles/paho-mqtt3a.dir/MQTTAsync.c.o
[ 32%] Building C object src/CMakeFiles/paho-mqtt3a.dir/MQTTAsyncUtils.c.o
[ 33%] Linking C shared library libpaho-mqtt3a.so
[ 33%] Built target paho-mqtt3a
[ 34%] Building C object src/CMakeFiles/MQTTVersion.dir/MQTTVersion.c.o
[ 36%] Linking C executable MQTTVersion
[ 36%] Built target MQTTVersion
[ 37%] Building C object src/CMakeFiles/common_ssl_obj.dir/MQTTTime.c.o
[ 38%] Building C object src/CMakeFiles/common_ssl_obj.dir/MQTTProtocolClient.c.o
[ 39%] Building C object src/CMakeFiles/common_ssl_obj.dir/Clients.c.o
[ 40%] Building C object src/CMakeFiles/common_ssl_obj.dir/utf-8.c.o
[ 41%] Building C object src/CMakeFiles/common_ssl_obj.dir/MQTTPacket.c.o
[ 43%] Building C object src/CMakeFiles/common_ssl_obj.dir/MQTTPacketOut.c.o
[ 44%] Building C object src/CMakeFiles/common_ssl_obj.dir/Messages.c.o
[ 45%] Building C object src/CMakeFiles/common_ssl_obj.dir/Tree.c.o
[ 46%] Building C object src/CMakeFiles/common_ssl_obj.dir/Socket.c.o
[ 47%] Building C object src/CMakeFiles/common_ssl_obj.dir/Log.c.o
[ 48%] Building C object src/CMakeFiles/common_ssl_obj.dir/MQTTPersistence.c.o
[ 50%] Building C object src/CMakeFiles/common_ssl_obj.dir/Thread.c.o
[ 51%] Building C object src/CMakeFiles/common_ssl_obj.dir/MQTTProtocolOut.c.o
[ 52%] Building C object src/CMakeFiles/common_ssl_obj.dir/MQTTPersistenceDefault.c.o
[ 53%] Building C object src/CMakeFiles/common_ssl_obj.dir/SocketBuffer.c.o
[ 54%] Building C object src/CMakeFiles/common_ssl_obj.dir/LinkedList.c.o
[ 55%] Building C object src/CMakeFiles/common_ssl_obj.dir/MQTTProperties.c.o
[ 56%] Building C object src/CMakeFiles/common_ssl_obj.dir/MQTTReasonCodes.c.o
[ 58%] Building C object src/CMakeFiles/common_ssl_obj.dir/Base64.c.o
[ 59%] Building C object src/CMakeFiles/common_ssl_obj.dir/SHA1.c.o
[ 60%] Building C object src/CMakeFiles/common_ssl_obj.dir/WebSocket.c.o
[ 61%] Building C object src/CMakeFiles/common_ssl_obj.dir/Proxy.c.o
[ 62%] Building C object src/CMakeFiles/common_ssl_obj.dir/StackTrace.c.o
[ 63%] Building C object src/CMakeFiles/common_ssl_obj.dir/Heap.c.o
[ 63%] Built target common_ssl_obj
[ 65%] Building C object src/CMakeFiles/paho-mqtt3cs.dir/MQTTClient.c.o
[ 66%] Building C object src/CMakeFiles/paho-mqtt3cs.dir/SSLSocket.c.o
/home/roman/paho.mqtt.c/src/Heap.h:55:24: error: expected declaration specifiers or '...' before string constant
   55 | #define free(x) myfree(__FILE__, __LINE__, x)
      |                        ^~~~~~~~
/home/roman/paho.mqtt.c/src/Heap.h:55:34: error: expected declaration specifiers or '...' before numeric constant
   55 | #define free(x) myfree(__FILE__, __LINE__, x)
      |                                  ^~~~~~~~
gmake[2]: *** [src/CMakeFiles/paho-mqtt3cs.dir/build.make:93: src/CMakeFiles/paho-mqtt3cs.dir/SSLSocket.c.o] Error 1
gmake[1]: *** [CMakeFiles/Makefile2:339: src/CMakeFiles/paho-mqtt3cs.dir/all] Error 2
gmake: *** [Makefile:156: all] Error 2

Environment (please complete the following information):

• OS: Alpine Linux
• Version 3.23.3

Additional context
Add any other context about the problem here.

$ gcc --version
gcc (Alpine 15.2.0) 15.2.0
Copyright (C) 2025 Free Software Foundation, Inc.
This is free software; see the source for copying conditions.  There is NO
warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.

Alpine Linux uses musl libc instead of glibc.
This is fixed after moving #include <openssl/ssl.h> before #include "Heap.h" and I don't know why...

[fpagliughi]

I confirmed this. I loaded an Alpine container, followed the directions, and saw the same build issue with GCC v15.2.
I also tried clang v21 on Alpine and saw it as well.

It looks like clang better explains the problem:

In file included from /home/fmp/paho.mqtt.c/src/SSLSocket.c:32:
In file included from /home/fmp/paho.mqtt.c/src/SocketBuffer.h:21:
In file included from /home/fmp/paho.mqtt.c/src/Socket.h:76:
In file included from /home/fmp/paho.mqtt.c/src/Thread.h:49:
In file included from /usr/include/pthread.h:30:
/usr/include/sched.h:85:6: error: expected parameter declarator
   85 | void free(void *);
      |      ^
/home/fmp/paho.mqtt.c/src/Heap.h:55:24: note: expanded from macro 'free'
   55 | #define free(x) myfree(__FILE__, __LINE__, x)
      |                        ^
<scratch space>:22:1: note: expanded from here
   22 | "/usr/include/sched.h"
      | ^

It seems that on Alpine, the system /usr/include/sched.h header contains a declaration for void free(void*);

That declaration of free() is not present in the sched.h header on my Ubuntu & Mint distros. On Alpine, it is being brought in after the macro declaration.

So, I believe the macro is being expanded into the header declaration of the free function in the sched.h file.

@icraggs : It seems that once again the C preprocessor is causing problems! It's maybe not a great idea to use a macro that redefines a standard function, the declaration of which is not in our control.

Alternately, perhaps, reconsider the order of the #include's. I guess Heap.h should come last?

[FrankZRS]

This exact same issue happened to my OpenWRT build, and I dug into the source code and found what I think is the cause:

In SSLSocket.c:

#include "Heap.h"

#include "SocketBuffer.h"
#include "MQTTClient.h"
#include "MQTTProtocolOut.h"
#include "SSLSocket.h"
#include "Log.h"
#include "StackTrace.h"
#include "Socket.h"

#include "Heap.h"

Notice that Heap.h is included twice. The bottom one has been there for years, but the top one is only added 2 weeks ago in this commit: @icraggs afcdeb5
The problem is that Heap.h contains macros that redefine free:

#define free(x) myfree(__FILE__, __LINE__, x)

This makes the order of includes critical. Any headers or code that calls free() expecting the standard behavior from <stdlib.h> can break. I believe this explains why moving Heap.h to be the first included header in SSLSocket.c triggered the problems seen by myself and others in this thread.

@Roman3349 @fpagliughi : If you are still having this issue, a quick workaround without having to modify the code, is to build with PAHO_HIGH_PERFORMANCE enabled (e.g. my project uses CMAKE so I enabled the option there). This will avoid using the macros defined in Heap.h. Of course that's only applicable if you don't need any of the debugging features excluded by PAHO_HIGH_PERFORMANCE. I hope this is helpful.

[icraggs]

@fpagliughi we're having our entire heating system replaced this week so my responses are delayed!

This is an error on my part. Heap.h must always be the last header file included, so it doesn't affect any other. I don't know how that extra Heap.h got included in that commit - that's just strange.

[icraggs]

I'm going to ensure all the other source files have Heap.h at the end where it is included, and also add a comment stating that it should be after all other includes. This is so I don't forget, as well as other people!