Author: Mike Pall

BitOp

# Installation

This page explains how to build Lua BitOp from source, against an existing Lua installation. If you've installed Lua using a package manager (e.g. as part of a Linux distribution), you're advised to check for a pre-built package of Lua BitOp and install this instead.

## Prerequisites

To compile Lua BitOp, your Lua 5.1/5.2 installation must include all development files (e.g. include files). If you've installed Lua from source, you already have them (e.g. in `/usr/local/include` on POSIX systems).

If you've installed Lua using a package manager, you may need to install an extra Lua development package (e.g. `liblua5.1-dev` on Debian/Ubuntu).

Probably any current C compiler which can compile Lua also works for Lua BitOp. The C99 `<stdint.h>` include file is mandatory, but the source contains a workaround for MSVC.

Lua is by default configured to use `double` as its number type. Lua BitOp supports IEEE 754 doubles or alternative configurations with int32_t or int64_t (suitable for embedded systems without floating-point hardware). The `float` number type is not supported.

## Configuration

You may need to modify the build scripts and change the paths to the Lua development files or some compiler flags. Check the start of `Makefile` (POSIX), `Makefile.mingw` (MinGW on Windows) or `msvcbuild.bat` (MSVC on Windows) and follow the instructions in the comments.

E.g. the Lua 5.1 include files are located in `/usr/include/lua5.1`, if you've installed the Debian/Ubuntu Lua development package.

## Build & Install

After » downloading Lua BitOp, unpack the distribution file, open a terminal/command window, change into the newly created directory and follow the instructions below.

### Linux, *BSD, Mac OS X

For Linux, *BSD and most other POSIX systems just run:

    make

For Mac OS X you need to run this instead:

    make macosx

You probably need to be the root user to install the resulting `bit.so` into the C module directory for your current Lua installation. Most systems provide `sudo`, so you can run:

    sudo make install

### MinGW on Windows

Start a command prompt and make sure the MinGW tools are in your PATH. Then run:

    mingw32-make -f Makefile.mingw

If you've adjusted the path where C modules for Lua should be installed, you can run:

    mingw32-make -f Makefile.mingw install

Otherwise just copy the file `bit.dll` to the appropriate directory. By default this is the same directory where `lua.exe` resides.

### MSVC on Windows

Open a "Visual Studio .NET Command Prompt", change to the directory where `msvcbuild.bat` resides and run it:

    msvcbuild

If the file `bit.dll` has been successfully built, copy it to the directory where C modules for your Lua installation are installed. By default this is the same directory where `lua.exe` resides.

### Embedding Lua BitOp

If you're embedding Lua into your application, it's quite simple to add Lua BitOp as a static module:

1. Copy the file `bit.c` from the Lua BitOp distribution to your Lua source code directory.

2. Add this file to your build script (e.g. modify the Makefile) or import it as a build dependency in your IDE.

3. Edit `lualib.h` and add the following two lines:

    #define LUA_BITLIBNAME "bit"
    LUALIB_API int luaopen_bit(lua_State *L);

4. Edit `linit.c` and add this immediately before the line with `{NULL, NULL}`:

      {LUA_BITLIBNAME, luaopen_bit},

5. Now recompile and you're done!

## Testing

You can optionally test whether the installation of Lua BitOp was successful. Keep the terminal/command window open and run one of the following commands:

For Linux, *BSD and Mac OS X:

    make test

For MinGW on Windows:

    mingw32-make -f Makefile.mingw test

For MSVC on Windows:

    msvctest

If any of the tests fail, please check that you've properly set the paths in the build scripts, compiled with the same headers you've compiled your Lua installation (in particular if you've changed the number type in `luaconf.h`) and installed the C module into the directory which matches your Lua installation. Double check everything if you've installed multiple Lua interpreters (e.g. both in `/usr/bin` and in `/usr/local/bin`).

If you get a warning or a failure about a broken `tostring()` function or about broken hex literals, then your Lua installation is defective. Check with your distributor, replace/upgrade a broken compiler or C library or re-install Lua yourself with the right configuration settings (in particular see `LUA_NUMBER_*` and `luai_num*` in `luaconf.h`).

## Benchmarks

The distribution contains several benchmarks:

- `bitbench.lua` tests the speed of basic bit operations. The benchmark is auto-scaling with a minimum runtime of 1 second for each part. The loop overhead is computed first and subtracted from the following measurements. The time to run a bit operation includes the overhead of setting up its parameters and calling the corresponding C function.
- `nsievebits.lua` is a simple benchmark adapted from the » Computer Language Benchmarks Game (formerly known as Great Computer Language Shootout). The scale factor is exponential, so run it with a small number between 2 and 10 and time it (e.g. `time lua nsievebits.lua 6`).
- `md5test.lua` when given the argument "bench" runs an auto-scaling benchmark and prints the time per character needed to compute the MD5 hash of a (medium-length) string. Please note that this implementation is mainly intended as a regression test. It's not suitable for cross-language comparisons against fully optimized MD5 implementations.

Copyright © 2012 Mike Pall · Contact