ChunkSpy: A Lua 5 Binary Chunk Disassembler

Description

LuaForge Project Page: http://luaforge.net/projects/chunkspy/

ChunkSpy is a tool to disassemble a Lua 5 binary chunk into a verbose listing that can then be studied. Its output bears a resemblance to the output listing of assemblers. I wanted something that can tell me in great detail what goes on inside a Lua binary chunk file, not just the instructions. It is intended to be a tool for learning Lua internals as well.

ChunkSpy is contained in a single Lua file, ChunkSpy.lua, so that it is very portable and very customizable; there are no C source files to compile. All you need is a copy of the Lua command line executable, lua, plus optionally the binary chunk compiler, luac, to generate those binary chunk files.

I have also written a brief guide to all Lua 5 virtual machine instructions, for those who need such things: A No-Frills Introduction to Lua 5.1 VM Instructions (available for version 5.0.2 and version 5.1; please follow the document links on the page for the PDF and ODT files.) ChunkBake is a Lua 5 assembler which complements ChunkSpy.

If you want to disassemble to source code, try LuaDec by Hisham Muhammad.

Features

ChunkSpy can do the following:

• Generate a detailed listing from a Lua 5 binary chunk or a Lua 5 source file.
• Separate files provide complete support for Lua 5.0.2 and Lua 5.1.
• Instruction disassembly with comments.
• Merge a specified source listing with disassembled instructions.
• Detailed or brief listing mode. Optional stats (sizes) information.
• Validation or auto-detection of binary chunk profile or platform.
• Interactive mode: get instant feedback.
• Write out (convert) a binary chunk to a custom profile.
• Load and execute a binary chunk with a non-local format or profile.

This is a beta release, so it is NOT bug-free. Everything was done on self-compiled Lua 5.0.2 and Lua 5.1 executables, on Win32. Bug reports are welcome, as are enhancements. Please see the README in the release for more information on its features and limitations. Feedback and contributions are welcome.

Download

You can get all the ChunkSpy files at LuaForge: http://luaforge.net/projects/chunkspy/

Latest version: ChunkSpy 0.9.8 (66KB zip) is the Lua version.
Win32 binary (143KB zip) available for version 0.9.7 at the moment.

Changes

2006-03-13: ChunkSpy 0.9.8. Complete support for Lua 5.1.
2006-03-13: Added A No-Frills Introduction to Lua 5.1 VM Instructions (in ODT or PDF)
2006-02-21: Updated A No-Frills Introduction to Lua 5 VM Instructions (in ODT or PDF)
2005-06-05: ChunkSpy 0.9.7. Experimental support for Lua 5.1wk6.
2005-03-25: ChunkSpy 0.9.6. Fixed OP_NEWTABLE decoding for Lua 5.1wk5 disassembler.
2005-03-03: ChunkSpy 0.9.5. Experimental support for Lua 5.1wk4. Upcoming Lua 5.1 support will be in the form of a separate script.
2004-11-28: Added A No-Frills Introduction to Lua 5 VM Instructions (in SXW or PDF), available from the Document Manager tab in ChunkSpy's LuaForge Project Page.
2004-11-21: ChunkSpy 0.9.4. Added comments for some instructions, and a Win32 stand-alone binary.
2004-11-14: ChunkSpy 0.9.3. Added binary chunk rewriting (--rewrite "plat") option, and non-native binary chunk load and execute (--run) option.
2004-11-09: ChunkSpy 0.9.2. Added interactive mode (--interact), brief listings (--brief), output file specification (-o <file>), and source to listing mode (--source <file>).
2004-11-07: ChunkSpy 0.9.1. Basic features, initial release on LuaForge.

Acknowledgements