miduo_client/Assets/ManagedResources/~Lua/3rd/luabitop/doc/install.html

239 lines
7.7 KiB
HTML

<!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-2012, 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">&raquo;</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/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 <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>&lt;stdint.h&gt;</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 &amp; Install</h2>
<p>
After <a href="http://bitop.luajit.org/download.html"><span class="ext">&raquo;</span>&nbsp;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&nbsp;OS&nbsp;X</h3>
<p>
For Linux, *BSD and most other POSIX systems just run:
</p>
<pre class="code">
make
</pre>
<p>
For Mac&nbsp;OS&nbsp;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&nbsp;OS&nbsp;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&nbsp;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">&raquo;</span>&nbsp;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&nbsp;lua&nbsp;nsievebits.lua&nbsp;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 &copy; 2012 Mike Pall
<span class="noprint">
&middot;
<a href="contact.html">Contact</a>
</span>
</div>
</body>
</html>