1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
|
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" "http://www.w3.org/TR/html4/strict.dtd">
<html>
<head>
<title>Installation</title>
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
<meta name="Author" content="Mike Pall">
<meta name="Copyright" content="Copyright (C) 2005-2009, Mike Pall">
<meta name="Language" content="en">
<link rel="stylesheet" type="text/css" href="bluequad.css" media="screen">
<link rel="stylesheet" type="text/css" href="bluequad-print.css" media="print">
</head>
<body>
<div id="site">
<a href="http://bitop.luajit.org"><span>Bit<span id="logo">Op</span></span></a>
</div>
<div id="head">
<h1>Installation</h1>
</div>
<div id="nav">
<ul><li>
<a href="index.html">Lua BitOp</a>
</li><li>
<a class="current" href="install.html">Installation</a>
</li><li>
<a href="api.html">API Functions</a>
</li><li>
<a href="semantics.html">Semantics</a>
</li><li>
<a href="changes.html">Changes</a>
</li><li>
<a href="http://bitop.luajit.org/download.html">Download <span class="ext">»</span></a>
</li></ul>
</div>
<div id="main">
<p>
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.
</p>
<h2 id="prereq">Prerequisites</h2>
<p>
To compile Lua BitOp, your Lua 5.1 installation must include all development
files (e.g. include files). If you've installed Lua from source, you
already have them (e.g. in <tt>/usr/local/include</tt> on POSIX systems).
</p>
<p>
If you've installed Lua using a package manager, you may need to install
an extra Lua development package (e.g. <tt>liblua5.1-dev</tt> on
Debian/Ubuntu).
</p>
<p>
Probably any current C compiler which can compile Lua also works for
Lua BitOp. The C99 <tt><stdint.h></tt> include file is mandatory,
but the source contains a workaround for MSVC.
</p>
<p>
Lua is by default configured to use <tt>double</tt> 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 <tt>float</tt> number type is not supported.
</p>
<h2 id="config">Configuration</h2>
<p>
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
<tt>Makefile</tt> (POSIX), <tt>Makefile.mingw</tt> (MinGW on Windows)
or <tt>msvcbuild.bat</tt> (MSVC on Windows) and follow the instructions
in the comments.
</p>
<p>
E.g. the Lua 5.1 include files are located in <tt>/usr/include/lua5.1</tt>,
if you've installed the Debian/Ubuntu Lua development package.
</p>
<h2 id="build">Build & Install</h2>
<p>
After <a href="http://bitop.luajit.org/download.html"><span class="ext">»</span> downloading</a> Lua BitOp,
unpack the distribution file, open a terminal/command window,
change into the newly created directory and follow the instructions below.
</p>
<h3 id="posix">Linux, *BSD, Mac OS X</h3>
<p>
For Linux, *BSD and most other POSIX systems just run:
</p>
<pre class="code">
make
</pre>
<p>
For Mac OS X you need to run this instead:
</p>
<pre class="code">
make macosx
</pre>
<p>
You probably need to be the root user to install the resulting <tt>bit.so</tt>
into the C module directory for your current Lua installation.
Most systems provide <tt>sudo</tt>, so you can run:
</p>
<pre class="code">
sudo make install
</pre>
<h3 id="mingw">MinGW on Windows</h3>
<p>
Start a command prompt and make sure the MinGW tools are in your PATH.
Then run:
</p>
<pre class="code">
mingw32-make -f Makefile.mingw
</pre>
<p>
If you've adjusted the path where C modules for Lua should be installed,
you can run:
</p>
<pre class="code">
mingw32-make -f Makefile.mingw install
</pre>
<p>
Otherwise just copy the file <tt>bit.dll</tt> to the appropriate directory.
By default this is the same directory where <tt>lua.exe</tt> resides.
</p>
<h3 id="msvc">MSVC on Windows</h3>
<p>
Open a "Visual Studio .NET Command Prompt", change to the directory
where <tt>msvcbuild.bat</tt> resides and run it:
</p>
<pre class="code">
msvcbuild
</pre>
<p>
If the file <tt>bit.dll</tt> 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 <tt>lua.exe</tt> resides.
</p>
<h3 id="embed">Embedding Lua BitOp</h3>
<p>
If you're embedding Lua into your application, it's quite simple to
add Lua BitOp as a static module:
</p>
<p>
1. Copy the file <tt>bit.c</tt> from the Lua BitOp distribution
to your Lua source code directory.
</p>
<p>
2. Add this file to your build script (e.g. modify the Makefile) or
import it as a build dependency in your IDE.
</p>
<p>
3. Edit <tt>lualib.h</tt> and add the following two lines:
</p>
<pre class="code">
#define LUA_BITLIBNAME "bit"
LUALIB_API int luaopen_bit(lua_State *L);
</pre>
<p>
4. Edit <tt>linit.c</tt> and add this immediately before the line
with <tt>{NULL, NULL}</tt>:
</p>
<pre class="code">
{LUA_BITLIBNAME, luaopen_bit},
</pre>
<p>
5. Now recompile and you're done!
</p>
<h2 id="test">Testing</h2>
<p>
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:
</p>
<p>
For Linux, *BSD and Mac OS X:
</p>
<pre class="code">
make test
</pre>
<p>
For MinGW on Windows:
</p>
<pre class="code">
mingw32-make -f Makefile.mingw test
</pre>
<p>
For MSVC on Windows:
</p>
<pre class="code">
msvctest
</pre>
<p>
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 <tt>luaconf.h</tt>) 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 <tt>/usr/bin</tt>
and in <tt>/usr/local/bin</tt>).
</p>
<p>
If you get a warning or a failure about a broken <tt>tostring()</tt> 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 <tt>LUA_NUMBER_*</tt> and <tt>luai_num*</tt>
in <tt>luaconf.h</tt>).
</p>
<h2 id="bench">Benchmarks</h2>
<p>
The distribution contains several benchmarks:
</p>
<ul>
<li><tt>bitbench.lua</tt> 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.</li>
<li><tt>nsievebits.lua</tt> is a simple benchmark adapted from the
<a href="http://shootout.alioth.debian.org/"><span class="ext">»</span> Computer Language Benchmarks Game</a>
(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. <tt>time lua nsievebits.lua 6</tt>).</li>
<li><tt>md5test.lua</tt> 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.</li>
</ul>
<br class="flush">
</div>
<div id="foot">
<hr class="hide">
Copyright © 2009 Mike Pall
<span class="noprint">
·
<a href="contact.html">Contact</a>
</span>
</div>
</body>
</html>
|
