wahern/cqueues

API Documentation

Please refer to the PDF available at http://25thandclement.com/~william/projects/cqueues.pdf

Build Dependancies

The Makefile requires GNU Make. The source code should build with recent GCC, clang, or Solaris SunPro compilers.

If you use your own Makefile, note that GCC and especially clang may emit copious warnings about initializers and unused parameters. These warnings are stupid. Use -Wno-override-init (GCC), -Wno-initializer-overrides (clang) and -Wno-unused to quiet these. For other warnings, patches welcome.

M4 and awk are required to generate errno.c. It relies on mk/errno.list to enumerate the system error macro names. mk/errno.list is a small POSIX-compatible shell script. By default it processes GCC's -dM macro list (clang also supports this option). For SunPro it uses a slightly cruder method.

Because the location of Lua include headers are unpredictable across systems, the build system by default relies on mk/luapath to locate the correct headers. mk/luapath uses various POSIX utilities. For more information see the luapath project page. But see LUA_APIS, LUA51_CPPFLAGS, LUA52_CPPFLAGS, and LUA53_CPPFLAGS, below.

cqueues should work on recent versions of Linux, OS X, Solaris, NetBSD, FreeBSD, OpenBSD, and derivatives. The regression suite is run on all supported platforms before rolling a release, and regularly during the development. In the future support may be added for AIX and the AIX pollset interface. Windows support is planned, though initially by relying on BSD select.

Build Overview

There is no separate ./configure step at the moment. System introspection occurs during compile time. However, the configure Make target can be used to cache the build environment.

Build Environment

Lua APIs

cqueues targets the three latest Lua APIs---5.1, 5.2, and 5.3---and all can be compiled simultaneously. Supported build targets are automatically detected by default. To override API autodetection specify LUA_APIS. For example,

$ make LUA_APIS="5.2 5.3"

Toolchain Flags

All the common GNU-style compiler variables are supported, including CC, CPPFLAGS, CFLAGS, LDFLAGS, SOFLAGS, and LIBS. Note that you can specify the path to both Lua 5.1, 5.2, and 5.3 include headers at the same time in CPPFLAGS; the build system will work things out to ensure the correct headers are loaded at compile-time. To specify them explicitly provide

• LUA51_CPPFLAGS - preprocessor flags for Lua 5.1
• LUA52_CPPFLAGS - preprocessor flags for Lua 5.2
• LUA53_CPPFLAGS - preprocessor flags for Lua 5.3

To completely override all internally-defined flags, specify the ALL_-prefixed variant of any of the above. For example, specify ALL_CPPFLAGS to override the built-in optimization and warning flags. Note that object files are built using a command similar to

$ $(CC) $(ALL_LUA53_CPPFLAGS) $(ALL_CPPFLAGS)

where the Lua-specific flags remain separate from more general flags.

Installation Paths

All the common GNU-style installation path variables are supported, including prefix, bindir, libdir, datadir, includedir, and DESTDIR. These additional path variables are also allowed:

• lua51path - install path for Lua 5.1 modules, e.g. $(prefix)/share/lua/5.1
• lua51cpath - install path for Lua 5.1 C modules, e.g. $(prefix)/lib/lua/5.1
• lua52path - install path for Lua 5.2 modules, e.g. $(prefix)/share/lua/5.2
• lua52cpath - install path for Lua 5.2 C modules, e.g. $(prefix)/lib/lua/5.2
• lua53path - install path for Lua 5.3 modules, e.g. $(prefix)/share/lua/5.3
• lua53cpath - install path for Lua 5.3 C modules, e.g. $(prefix)/lib/lua/5.3

Caching Environment

Invoking the configure target will cache the Make environment and reload the variable values on subsequent invocations. Variables can be modified on an individual basis after this.

Build Targets

cqueues targets the Lua 5.1 (LuaJIT), 5.2, and 5.3 API. For various reasons the build system is capable of building all three modules simultaneously in a single Make invocation. Therefore, there are many seemingly superfluous target names, either out of necessity or for convenience.

Compile Targets

liblua5.1-cqueues

Build Lua 5.1 cqueues modules

liblua5.2-cqueues

Build Lua 5.2 cqueues modules

liblua5.3-cqueues

Build Lua 5.3 cqueues modules

all5.1

Synonym for liblua5.1-cqueues

all5.2

Synonym for liblua5.2-cqueues

all5.3

Synonym for liblua5.3-cqueues

all

Invokes one or more of the above according to the definition of LUA_APIS.

Install Targets

liblua5.1-cqueues-install

Install Lua 5.1 cqueues modules

liblua5.2-cqueues-install

Install Lua 5.2 cqueues modules

liblua5.3-cqueues-install

Install Lua 5.3 cqueues modules

install5.1

Invokes liblua5.1-cqueues-install

install5.2

Invokes liblua5.2-cqueues-install

install5.3

Invokes liblua5.3-cqueues-install

install

Invokes one of more of the above install targets according to LUA_APIS.

Uninstall Targets

liblua5.1-cqueues-uninstall

Uninstall Lua 5.1 cqueues modules

liblua5.2-cqueues-uninstall

Uninstall Lua 5.2 cqueues modules

liblua5.3-cqueues-uninstall

Uninstall Lua 5.3 cqueues modules

uninstall5.1

Invokes liblua5.1-cqueues-uninstall

uninstall5.2

Invokes liblua5.2-cqueues-uninstall

uninstall5.3

Invokes liblua5.3-cqueues-uninstall

uninstall

Invokes one or more of the above uninstall targets according to LUA_APIS.

Other Targets

clean

rm binary targets, object files, debugging symbols, etc

clean~

clean + rm *~

debian

Build debian packages liblua5.1-cqueues and liblua5.2-cqueues using the dpkg-buildpackage utility. The Make variables DPKG_BUILDPACKAGE and DPKG_BUILDPACKAGE_OPTIONS can be used to manipulate this process.