diff --git a/README.md b/README.md index e80009d..7582f5d 100644 --- a/README.md +++ b/README.md @@ -11,206 +11,216 @@ 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. +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 +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 5.2 and LuaJIT include headers are completely -random across systems, the build system relies on mk/luapath to locate the -correct headers, including selecting the correct headers at compile-time -when conflicting headers are encountered. mk/luapath uses various POSIX -utilities. For more information, see - - -cqueues should work (plus or minus a few tweaks) on recent versions of -Linux, OS X, Solaris, NetBSD, FreeBSD, OpenBSD, and derivatives. The only -other possible candidate is AIX, if and when support for AIX's pollset -interface is added to the embedded "kpoll" library. +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](http://25thandclement.com/~william/projects/luapath.html). +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. System introspection occurs during -compile-time. However, the `configure' Make target can be used to cache the -build environment. +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 -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 - -All the common GNU-style compiler variables are supported, including CC, -CPPFLAGS, CFLAGS, LDFLAGS, and SOFLAGS. 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. - -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. +### 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, -## Build Targets +``` +$ make LUA_APIS="5.2 5.3" +``` -cqueues targets both the Lua 5.2 and Lua 5.1 (LuaJIT) API. For various -reasons the build system is capable of building both 5.1 and 5.2 modules -simultaneously in a single Make invocation. Therefore, there are many -seemingly superfluous target names, either out of necessity or for -convenience. +### Toolchain Flags -### liblua5.1-cqueues +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 -Build Lua 5.1 cqueues modules + - `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 -### liblua5.2-cqueues +``` +$ $(CC) $(ALL_LUA53_CPPFLAGS) $(ALL_CPPFLAGS) +``` -Build Lua 5.2 cqueues modules +where the Lua-specific flags remain separate from more general flags. -### liblua5.3-cqueues - -Build Lua 5.3 cqueues modules - - -### liblua5.1-cqueues-install - -Install Lua 5.1 cqueues modules +### 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: -### liblua5.2-cqueues-install + - `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` -Install Lua 5.2 cqueues modules +### Caching Environment -### liblua5.3-cqueues-install +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. -Install Lua 5.3 cqueues modules +## Build Targets -### liblua5.1-cqueues-uninstall +`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. -Uninstall Lua 5.1 cqueues modules +### Compile Targets -### liblua5.2-cqueues-uninstall +#### liblua5.1-cqueues -Uninstall Lua 5.2 cqueues modules +Build Lua 5.1 cqueues modules +#### liblua5.2-cqueues -### liblua5.3-cqueues-uninstall +Build Lua 5.2 cqueues modules -Uninstall Lua 5.3 cqueues modules +#### liblua5.3-cqueues +Build Lua 5.3 cqueues modules -### cqueues5.1 +#### all5.1 Synonym for liblua5.1-cqueues -### cqueues5.2 - -Synonym for liblua5.2-cqueues - - -### cqueues5.3 +#### all5.2 Synonym for liblua5.2-cqueues -### cqueues +#### all5.3 -Invokes cqueues5.1 and cqueues5.2 +Synonym for liblua5.3-cqueues +#### all -### install5.1 +Invokes one or more of the above according to the definition of `LUA_APIS`. -Invokes liblua5.1-cqueues-install +### Install Targets -### install5.2 - -Invokes liblua5.2-cqueues-install +#### liblua5.1-cqueues-install +Install Lua 5.1 cqueues modules -### install5.3 +#### liblua5.2-cqueues-install -Invokes liblua5.3-cqueues-install +Install Lua 5.2 cqueues modules +#### liblua5.3-cqueues-install -### uninstall5.1 +Install Lua 5.3 cqueues modules -Invokes liblua5.1-cqueues-uninstall +#### install5.1 +Invokes liblua5.1-cqueues-install -### uninstall5.2 +#### install5.2 -Invokes liblua5.2-cqueues-uninstall +Invokes liblua5.2-cqueues-install +#### install5.3 -### uninstall5.3 +Invokes liblua5.3-cqueues-install -Invokes liblua5.3-cqueues-uninstall +#### install +Invokes one of more of the above install targets according to `LUA_APIS`. -### install -Invokes install5.1 and install5.2 +### Uninstall Targets +#### liblua5.1-cqueues-uninstall -### uninstall +Uninstall Lua 5.1 cqueues modules -Invokes uninstall5.1 and uninstall5.2 +#### liblua5.2-cqueues-uninstall +Uninstall Lua 5.2 cqueues modules -### all5.1 +#### liblua5.3-cqueues-uninstall -Build all Lua 5.1 binary targets +Uninstall Lua 5.3 cqueues modules +#### uninstall5.1 -### all5.2 +Invokes liblua5.1-cqueues-uninstall -Build all Lua 5.2 binary targets +#### uninstall5.2 +Invokes liblua5.2-cqueues-uninstall -### all5.3 +#### uninstall5.3 -Build all Lua 5.3 binary targets +Invokes liblua5.3-cqueues-uninstall +#### uninstall -### all +Invokes one or more of the above uninstall targets according to `LUA_APIS`. -Build all binary targets (the default) +### Other Targets -### clean +#### clean rm binary targets, object files, debugging symbols, etc - -### clean~ +#### clean~ clean + rm *~ - -### debian +#### 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. + + +