From ddae8878786a310f2e6cbe2a1d602a17ea28bb11 Mon Sep 17 00:00:00 2001 From: Mike Pall Date: Tue, 5 Oct 2010 01:36:54 +0200 Subject: [PATCH] Update docs for PPC port. Clarify and extend install instructions. --- Makefile | 9 +-- doc/faq.html | 6 +- doc/install.html | 155 +++++++++++++++++++++++++++++++++++++++-------- doc/luajit.html | 15 +++-- doc/running.html | 2 +- doc/status.html | 64 +++++++++---------- src/Makefile | 2 + src/ljamalg.c | 2 +- 8 files changed, 185 insertions(+), 70 deletions(-) diff --git a/Makefile b/Makefile index 2cf786d5..7728865d 100644 --- a/Makefile +++ b/Makefile @@ -1,13 +1,14 @@ ############################################################################## # LuaJIT top level Makefile for installation. Requires GNU Make. # +# Please read doc/install.html before changing any variables! +# # Suitable for POSIX platforms (Linux, *BSD, OSX etc.). # Note: src/Makefile has many more configurable options. # -# ##### This Makefile is NOT useful for installation on Windows! ##### +# ##### This Makefile is NOT useful for Windows! ##### # For MSVC, please follow the instructions given in src/msvcbuild.bat. # For MinGW and Cygwin, cd to src and run make with the Makefile there. -# NYI: add wininstall.bat # # Copyright (C) 2005-2010 Mike Pall. See Copyright Notice in luajit.h ############################################################################## @@ -22,8 +23,8 @@ NODOTABIVER= 51 ############################################################################## # -# Change the installation path as needed and modify src/luaconf.h accordingly. -# Note: PREFIX must be an absolute path! +# Change the installation path as needed. This automatically adjusts +# the paths in src/luaconf.h, too. Note: PREFIX must be an absolute path! # export PREFIX= /usr/local ############################################################################## diff --git a/doc/faq.html b/doc/faq.html index 90f37cef..9404f788 100644 --- a/doc/faq.html +++ b/doc/faq.html @@ -126,7 +126,7 @@ running inside a C function under the Lua interpreter.
Q: Why doesn't my favorite power-patch for Lua apply against LuaJIT?
Because it's a completely redesigned VM and has very little code in common with Lua anymore. Also, if the patch introduces changes to -the Lua semantics, this would need to be reflected everywhere in the +the Lua semantics, these would need to be reflected everywhere in the VM, from the interpreter up to all stages of the compiler.
Please use only standard Lua language constructs. For many common needs you can use source transformations or use wrapper or proxy functions. @@ -139,8 +139,8 @@ The compiler will happily optimize away such indirections.
machine code. This means the code generator must be ported to each architecture. And the fast interpreter is written in assembler and must be ported, too. This is quite an undertaking.
Currently only -x86 and x64 CPUs are supported. Other architectures will follow based -on sufficient user demand and/or sponsoring. +x86, x64 and PPC/e500v2 CPUs are supported. Other architectures will follow +based on sufficient user demand and/or sponsoring.
diff --git a/doc/install.html b/doc/install.html index 45925e7a..b0c806db 100644 --- a/doc/install.html +++ b/doc/install.html @@ -11,16 +11,20 @@ @@ -68,35 +72,40 @@ For the impatient (on POSIX systems): make && sudo make install

-LuaJIT currently builds out-of-the box on most x86 or x64 systems. +LuaJIT currently builds out-of-the box on most systems. Here's the compatibility matrix for the supported combinations of operating system, CPU and compilers:

- + + - + + - + + - + + - + +
Operating systemOS / CPU x86 (32 bit) x64 (64 bit)PPC/e500v2
LinuxLinux GCC 4.x
GCC 3.4		 GCC 4.xGCC 4.3+
Windows 98/XP/Vista/7Windows
98/XP/Vista/7		 MSVC (EE)
Windows SDK
MinGW (GCC)
Cygwin (GCC)		 MSVC + SDK v7.0
Windows SDK v7.0		 
OSX 10.3-10.6OSX 10.3-10.6 GCC 4.x
GCC 3.4		 GCC 4.x 
*BSD, other*BSD, other GCC 4.x
GCC 3.4		 (not supported) 
@@ -147,10 +156,12 @@ which is probably the default on your system, anyway. Simply run: make

-This always builds a native x86 or x64 binary, depending on your OS. +This always builds a native x86, x64 or PPC binary, depending on the host OS +you're running this command on. Check the section on +cross-compilation for more options.

-By default modules are only searched under the prefix /usr/local. +By default, modules are only searched under the prefix /usr/local. You can add an extra prefix to the search paths by appending the PREFIX option, e.g.:

@@ -283,7 +294,7 @@ directory where luajit.exe is installed (see src/luaconf.h).

-

Cross-compiling LuaJIT

+

Cross-compiling LuaJIT

The build system has limited support for cross-compilation. For details check the comments in src/Makefile. Here are some popular examples: @@ -303,36 +314,130 @@ installing the mingw32 package and running: 

 make HOST_CC="gcc -m32" CROSS=i586-mingw32msvc- TARGET_SYS=Windows
+

+You can cross-compile for a PPC/e500v2 target on an x86 or x64 host system +using a standard GNU cross-compile toolchain (Binutils, GCC, EGLIBC). +The CROSS prefix may vary depending on the --target +of the toolchain: +

+
+make HOST_CC="gcc -m32" CROSS=powerpc-e500v2-linux-gnuspe- TARGET=ppcspe
+
-

Embedding LuaJIT

+

Embedding LuaJIT

LuaJIT is API-compatible with Lua 5.1. If you've already embedded Lua into your application, you probably don't need to do anything to switch -to LuaJIT, except link with a different library. Additional hints: +to LuaJIT, except link with a different library:

+

Additional hints for initializing LuaJIT using the C API functions:

+ + +

Hints for Distribution Maintainers

+

+The LuaJIT build system has extra provisions for the needs of most +POSIX-based distributions. If you're a package maintainer for +a distribution, please make use of these features and +avoid patching, subverting, autotoolizing or messing up the build system +in unspeakable ways. +

+

+There should be absolutely no need to patch luaconf.h or any +of the Makefiles. And please do not hand-pick files for your packages — +simply use whatever make install creates. There's a reason +for all of the files and directories it creates. +

+

+The build system uses GNU make and autodetects most settings based on +the host you're building it on. This should work fine for native builds, +even when sandboxed. You may need to pass some of the following flags to +both the make and the make install command lines +for a regular distribution build: +

+

-64 bit applications on OSX must be linked with these options -(only the main executable): +The build system has a special target for an amalgamated build, i.e. +make amalg. This compiles the LuaJIT core as one huge C file +and allows GCC to generate faster and shorter code. Alas, this requires +lots of memory during the build. This may be a problem for some users, +that's why it's not enabled by default. But it shouldn't be a problem for +most build farms. It's recommended that binary distributions use this +target for their LuaJIT builds. +

+

+The tl;dr version of the above: 

--pagezero_size 10000 -image_base 100000000
+make amalg PREFIX=/usr && \
+make install PREFIX=/usr DESTDIR=/tmp/buildroot

-It's recommended to rebase all (self-compiled) shared libraries -which are loaded at runtime on OSX/x64 (e.g. C extension modules for Lua). -See: man rebase +Finally, if you encounter any difficulties, please +contact me first, instead of releasing a broken +package onto unsuspecting users. Because they'll usually gonna complain +to me (the upstream) and not you (the package maintainer), anyway.


diff --git a/doc/luajit.html b/doc/luajit.html index 90cd9997..71e6a19f 100644 --- a/doc/luajit.html +++ b/doc/luajit.html @@ -65,7 +65,8 @@ standard Lua interpreter and can be deployed as a drop-in replacement.

LuaJIT offers more performance, at the expense of portability. It currently runs on all popular operating systems based on -x86 or x64 CPUs (Linux, Windows, OSX etc.). +x86 or x64 CPUs (Linux, Windows, OSX etc.) or embedded Linux +systems based on PPC/e500v2 CPUs. Other platforms will be supported in the future, based on user demand and sponsoring.

@@ -76,7 +77,7 @@ LuaJIT has been successfully used as a scripting middleware in games, 3D modellers, numerical simulations, trading platforms and many other specialty applications. It combines high flexibility with high performance and an unmatched low memory footprint: less than -120K for the VM plus less than 80K for the JIT compiler. +120K for the VM plus less than 80K for the JIT compiler (on x86).

LuaJIT has been in continuous development since 2005. It's widely @@ -96,9 +97,13 @@ written in assembler, with a state-of-the-art JIT compiler. An innovative trace compiler is integrated with advanced, SSA-based optimizations and a highly tuned code generation backend. This allows a substantial reduction of the overhead associated with dynamic -language features. It's destined to break into the -» performance range -traditionally reserved for offline, static language compilers. +language features. +

+

+It's destined to break into the » performance +range traditionally reserved for offline, static language compilers. +Have look at these » cross-language benchmarks +to see how it ranks against the competition.

More ...

diff --git a/doc/running.html b/doc/running.html index e3a2a4b0..e337d535 100644 --- a/doc/running.html +++ b/doc/running.html @@ -126,7 +126,7 @@ systems.

-O[level]
--O[+]flag -O-flag
+-O[+]flag   -O-flag
-Oparam=value

This options allows fine-tuned control of the optimizations used by diff --git a/doc/status.html b/doc/status.html index 3da8fe78..a2de90ab 100644 --- a/doc/status.html +++ b/doc/status.html @@ -67,30 +67,31 @@ This is a list of the things you should know about the LuaJIT 2.0 beta test: