Skip to content

Commit

Permalink
update build documentation in README.md
Browse files Browse the repository at this point in the history
  • Loading branch information
@wahern
wahern committed Mar 21, 2016
1 parent 5364f89 commit 1ac72ad
Showing 1 changed file with 116 additions and 106 deletions.
222 changes: 116 additions & 106 deletions README.md
View file
Expand Up @@ -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
<http://25thandclement.com/~william/projects/luapath.html>

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.


<!-- Markdeep: --><style class="fallback">body{visibility:hidden;white-space:pre;font-family:monospace}</style><script src="markdeep.min.js"></script><script src="https://casual-effects.com/markdeep/latest/markdeep.min.js"></script><script>window.alreadyProcessedMarkdeep||(document.body.style.visibility="visible")</script>

0 comments on commit 1ac72ad

Please sign in to comment.