Bit

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: