1# lws event library support 2 3## v4.0 and below 4 5Before v4.1, lws allowed selecting some event library support for inclusion 6in the libwebsockets library 7 8Option|Feature 9---|--- 10`LWS_WITH_GLIB`|glib 11`LWS_WITH_LIBEVENT`|libevent 12`LWS_WITH_LIBUV`|libuv 13`LWS_WITH_LIBEV`|libev 14 15The user code can select by `info->options` flags at runtime which event loop 16it wants to use. 17 18The only restriction is that libev and libevent can't coexist, because their 19header namespace conflicts. 20 21## v4.1 and above 22 23Lws continues to support the old way described above, but there's an additional 24new cmake option that decides how they are built if any are selected, 25`LWS_WITH_EVLIB_PLUGINS`. 26 27The old behaviour is set by `LWS_WITH_EVLIB_PLUGINS=0`, for UNIX platforms, this 28is set to 1 by default. This causes the enabled event lib support to each be built into 29its own dynamically linked plugin, and lws will bring in the requested support alone 30at runtime after seeing the `info->options` flags requested by the user code. 31 32This has two main benefits, first the conflict around building libevent and libev 33together is removed, they each build isolated in their own plugin; the libwebsockets 34core library build doesn't import any of their headers (see below for exception). 35And second, for distro packaging, the event lib support plugins can be separately 36packaged, and apps take dependencies on the specific event lib plugin package, which 37itself depends on the libwebsockets core library. This allows just the needed 38dependencies for the packageset without forcing everything to bring everything in. 39 40Separately, lws itself has some optional dependencies on libuv, if you build lwsws 41or on Windows you want plugins at all. CMake will detect these situations and 42select to link the lws library itself to libuv if so as well, independent of whatever 43is happening with the event lib support. 44 45## evlib plugin install 46 47The produced plugins are named 48 49event lib|plugin name 50---|--- 51glib|`libwebsockets-evlib_glib.so` 52event|`libwebsockets-evlib_event.so` 53uv|`libwebsockets-evlib_uv.so` 54ev|`libwebsockets-evlib_ev.so` 55 56The evlib plugins are installed alongside libwebsockets.so/.a into the configured 57library dir, it's often `/usr/local/lib/` by default on linux. 58 59Lws looks for them at runtime using the build-time-configured path. 60 61## Component packaging 62 63The canonical package name is `libwebsockets`, the recommended way to split the 64packaging is put the expected libs and pkgconfig in `libwebsockets` or `libwebsockets-core`, 65the latter is followed by the provided cmake, and produce an additional package per build 66event library plugin, named, eg `libwebsockets-evlib_glib`, which has a dependency on 67`libwebsockets[-core]`. 68 69Applications that use the default event loop can directly require `libwebsockets[-core]`, 70and application packages that need specific event loop support can just require, eg, 71`libwebsockets-evlib_glib`, which will bring that in and the core lws pieces in one step. 72There is then no problem with multiple apps requiring different event libs, they will 73bring in all the necessary pieces which will not conflict either as packages or at 74runtime. 75 76## `LWS_WITH_DISTRO_RECOMMENDED` 77 78The cmake helper config `LWS_WITH_DISTRO_RECOMMENDED` is adapted to build all the 79event libs with the event lib plugin support enabled. 80 81