# App/Xtn/Mediawiki/Scribunto/Overview

From XOWA: the free, open-source, offline wiki application

## Background

Scribunto is a MediaWiki extension for embedding Lua code in wiki pages. Lua is used for programming constructs (conditional logic; loops) that were previously attempted by Templates.

For more information on Scribunto, see http://www.mediawiki.org/wiki/Extension:Scribunto

For the source code, see https://gerrit.wikimedia.org/r/gitweb?p=mediawiki/extensions/Scribunto.git;a=summary

## Status

The Wikimedia Foundation began rolling out Scribunto/Lua to its sites on 2013-02-15 and finished on 2013-03-13 (http://blog.wikimedia.org/2013/03/14/what-lua-scripting-means-wikimedia-open-source/ . Data dumps after 2013-02-15 will probably have {{#invoke}} in their wikitext, which requires a lua processor.

Beginning with v0.3.2, XOWA included preliminary support for Scribunto. As of v1.3.1, the functionality level is approximately 95%+.

## Engines

XOWA provides two engines for processing Lua statements:

- lua: the standard lua binary that is distributed with Scribunto. For MediaWiki developers, it is the LuaStandalone approach.

  advantages
  - standard: lua is the official reference standard
  - performance: lua is written in C which is highly performant. However...
  disadvantages
  - performance: lua needs every message to be serialized when communicating back and forth between the binary and Java (the same behavior as LuaStandalone). This can result in performance issues.
  - limited platform support: lua needs a binary compiled specifically for its OS. Although the major OSs are provided, some other OSs will require additional steps: See openSUSE 11.0 and Binaries below.
  - permission setup: lua needs to be granted execute permissions on Linux and Mac OS X. Although XOWA does this automatically, there may be complications. See Permissions below.

- luaj: an open-source Java implementation of lua.

  advantages
  - universal platform support: luaj is written in Java and will automatically run on any platform that XOWA runs on
  - consistent behavior: luaj will run the same on all platforms. In contrast, lua will run differently on Windows versus Linux / Mac OS X (see os.time and mktime)
  - easier customization: luaj can be easily customized. In contrast, lua requires experience with C, and recompiling the source for each platform
  - performance: luaj runs in the same memory space as XOWA, and doesn't require message serializations for every call. In addition, the lua binary may not perform consistently on every OS. For some OSs, this makes a considerable difference. For example, it is reported that luaj runs dramatically faster than lua on Windows Vista (seconds versus minutes). However...
  disadvantages
  - performance: luaj is written in Java which is not as performant as C

Luaj is the official Lua processor for XOWA.

## Lua

### Binaries

XOWA packages the same Lua binaries (v5.1) that come with Scribunto. Note the following:

- The Windows, Linux, Linux 64, Mac OS X and Mac OS X 64 binaries have all been tested.
- The Linux binaries may not work on older distributions. For example, the Linux 64 binary does not work on openSUSE 11.0. In these cases, you will need to get a lua binary for your distribution, or compile it manually.
- XOWA/Lua has been tested on a Windows 7 64-bit machine. Note that the Windows 32-bit Lua binary is included, not the 64-bit one.

### Permissions

Linux / Mac OS X users will need to grant Execute permission to the Lua binary. Note that XOWA tries to do this automatically. If it fails, you will need to handle it manually by doing any one of the following (note you will need to replace <OS> with your system):

- Run the setup shell script

  Run `sh /xowa/setup_<OS>.sh script`

- Manually setup lua

  Run `mv -f /xowa/bin/<OS>/lua/lua_install /xowa/bin/<OS>/lua/lua`
  Run `chmod 774 /xowa/bin/<OS>/lua/lua`

- Use a pre-existing lua

  Change the "Lua path" binary to one on your machine (which presumably has the correct permissions) (EX: /usr/bin/lua)

## Luaj

XOWA packages a modified version of the luaj-jse-3.0 jar. Note that 3.0 was selected as it is the latest code branch and it fixes errors in 2.0.3.

Several changes were made to the default 3.0 version to accomodate issues. These changes are itemized at /xowa/bin/any/java/luaj/readme.txt as well as App/Xtn/Mediawiki/Scribunto/Luaj. The modified source is available at https://github.com/gnosygnu/luaj_xowa

Additional files are also at `/xowa/bin/any/php/mediawiki/extensions/Scribunto/engines/Luaj/`

## Scribunto files

XOWA used the following files from Scribunto:

- The main Lua libraries: mw_main.lua, MWServer.lua

  `source: /mediawiki-1.21.11/extensions/Scribunto/engines/LuaStandalone/`
  `target: /xowa/bin/any/php/mediawiki/extensions/Scribunto/engines/LuaStandalone/`

- The lualib directory hive

  `source: /mediawiki-1.21.11/extensions/Scribunto/engines/LuaCommon/lualib/`
  `target: /xowa/bin/any/php/mediawiki/extensions/Scribunto/engines/LuaCommon/lualib/`

- The Lua binary for the appropriate OS

  `source: /mediawiki-1.21.11/extensions/Scribunto/engines/LuaStandalone/binaries/<OS>/`
  `target: /xowa/bin/<OS>/lua`

XOWA modifies many of the lua files in order to cache library data across multiple page loads (Scribunto reloads the libraries for every page)

## Links

- For Options see Options/Scribunto
- For Diagnostics see Diagnostics#Scribunto

### XOWA

- Main page
- Screenshots
- Download XOWA
- Download wikis

### Getting started

- Requirements
- Installation
- Simple Wikipedia
- English Wikipedia
- Other Wikipedias

### Android

- Setup

### Help

- About
- Contents
- Media
- Feedback

### Blog

- Current

### Links

- Wikimedia dumps
- XOWA @ archive.org
- English Wikipedia

### Donate

- archive.org
- Wikipedia