Inconsistent build based on OS and libcap dependency

[mprather]

We've recently discovered a problem with our prototype app (first implementation with lws). Our app is designed on run on a variety of os platforms - windows, alpine, debian, ubuntu, arch. Our app utilizes makefiles for the linux builds. Packagement is handled with vcpkg.

We've noticed a difference with the Linux builds (windows is working great). The app compiles on all except Arch. The culprit is a dependency on libcap.

/usr/sbin/ld: /src/vcpkg/installed/x64-linux/lib/libwebsockets.a(unix-caps.c.o): in function `lws_plat_drop_app_privileges':
unix-caps.c:(.text+0x315): undefined reference to `cap_get_proc'
/usr/sbin/ld: unix-caps.c:(.text+0x331): undefined reference to `cap_set_flag'
/usr/sbin/ld: unix-caps.c:(.text+0x339): undefined reference to `cap_set_proc'
/usr/sbin/ld: unix-caps.c:(.text+0x359): undefined reference to `cap_free'
/usr/sbin/ld: unix-caps.c:(.text+0x4e1): undefined reference to `cap_get_proc'
/usr/sbin/ld: unix-caps.c:(.text+0x500): undefined reference to `cap_set_flag'
/usr/sbin/ld: unix-caps.c:(.text+0x508): undefined reference to `cap_set_proc'
/usr/sbin/ld: unix-caps.c:(.text+0x528): undefined reference to `cap_free'
collect2: error: ld returned 1 exit status

A quick scan of the build scripts and we found the following call:

CHECK_LIBRARY_EXISTS(cap cap_set_flag "" LWS_HAVE_LIBCAP)

I'm not familiar with this library but it seems that the default characteristic is looking for a library to enable some functionality. This will result in inconsistent builds when a perspective taken across different Linux distributions. Why would the other compilations work (where libcap is not installed) but a default Arch install then forces a different compilation path, which then breaks?

The easy makefile workaround, on Arch, is to simply add libcap as a library reference to the app's makefile. Since libcap is installed by default, this satifies the Check. However, this workaround does not work for other platforms as libcap is not natively installed with Alpine, Debian, or others. Writing a makefile to accommodate different distributions is not realistic.

From a vcpkg install, the most likely fix is to add libcap as a dependency. Then we would know that in all cases libcap is available and the opportunistic dependency can be realized.

But I'm still left wondering why this feature is not a discrete opt-in feature vs an implicit light-up feature like it is today. Is there a better way to manage this issue?

[mprather]

From a vcpkg install, the most likely fix is to add libcap as a dependency. Then we would know that in all cases libcap is available and the opportunistic dependency can be realized.

It turns out that adding libcap as a vcpkg dependency will not work. As written, the call to CHECK_LIBRARY_EXISTS only inspects system library locations via a link test. In effect, only the following paths are in scope for the test:

• /usr/lib
• /usr/lib64
• /lib
• /lib64
• compiler default search paths

It does not utilize paths typically used in toolchains:

• CMAKE_PREFIX_PATH
• CMAKE_LIBRARY_PATH
• vcpkg’s toolchain paths
• vcpkg’s installed tree

In reviewing #3260 and the related changes, the current behavior is only a partial solution. The underlying issue is that libwebsockets opportunistically probes the host system for libcap instead of respecting the toolchain, which leads to nondeterministic builds across distros and package managers.

The best fix is to leverage the new LWS_WITH_LIBCAP option together with find_package instead of check_library_exists. This ensures that when LWS_WITH_LIBCAP=ON, configuration fails if libcap is not found, rather than silently disabling the requested feature. If the library is found, the build proceeds knowing the dependency is truly available and ready for use. This removes host‑system variability from the build process.

This will make builds consistent across platforms.

[mprather]

@lws-team thanks for the fix. I'm a relatively new user to the library and I am wondering why this feature doesn't force a compilation failure if libcap is not found. If the consumer is requesting the library and it cannot be found, then shouldn't the config generate errors? Or is this just following a precedence on how features in this project are expected to work?