1 unstable release

0.1.0 Jul 10, 2021

#554 in Debugging

MIT license

695KB
17K SLoC

C 10K SLoC // 0.1% comments Rust 5K SLoC // 0.1% comments Python 835 SLoC // 0.2% comments Objective-C 445 SLoC // 0.1% comments

Glulxtoc - Glulx to C decompiler

Glulxtoc logo

Glulxtoc will decompile your Glulx storyfile into C code which you can then compile against any Glk library.

To get it, first install Rust and then install glulxtoc with cargo:

cargo install glulxtoc

Usage

glulxtoc <path> [FLAGS] [OPTIONS]

Required option:

  • path to storyfile

Flags:

  • -d, --disassemble: Disassembler mode - only disassemble, do not optimise or generate structured code

Options:

  • --debug-file: path to an Inform debug file for the storyfile
  • --out-dir: Output folder. If not given will make a folder based on the storyfile's name with .decompiled added to the end
  • --stack-size: Stack size in MB (default 8), for the glulxtoc app (not the stack of the Glulx file being decompiled.) Very large storyfiles may cause the glulxtoc app to have a stack overflow, in which case pass this option.
  • --safe-function-overrides: An array of function addresses to forcibly set as safe, overriding the decompiler's heuristics. Example, --safe-function-overrides=1234,5678
  • --unsafe-function-overrides: An array of function addresses to forcibly set as unsafe, overriding the decompiler's heuristics.

Compiling the output code

Glulxtoc produces several C files and provides a CMake CMakeLists.txt. You must pass in the Glk library's path to CMake. For example:

glulxtoc advent.ulx
cd advent.ulx.decompiled
mkdir remglk
cmake -DGlkLibPath=../../remglk . -B remglk
cd remglk
make

Limitations

In general Glulxtoc is likely to have problems with any Glulx files that weren't compiled with Inform.

  • No functions in RAM
  • Functions and strings can't be interleaved - will stop decoding once the first string is found
  • No 1 and 2 byte locals
  • Inter-function branches are only supported when you manually set the target function as unsafe
  • State changing opcodes (save, restart, etc) within functions called by strings

Troubleshooting

  • If you get an error in the decompilation stage (such as an unknown opcode), try passing in an Inform debug file. If you provide one, consider using the reduce-debug-xml.sh tool to cut back the debug data to only what Glulxtoc makes use of. This is not required, but will make Glulxtoc run faster.
  • If the make stage of compilation is very slow, try Clang. GCC has a bug which makes Glulxtoc's output compile very slowly.
  • If it compiles without error, but does not run properly, see if switching Glulxtoc to the disassembler mode (-d) fixes things. If it does then that indicates a bug in Glulxtoc's decompilation optimisation code.

If you do get an error, please post a bug report with as much detail as you can provide, and ideally with your storyfile.

Dependencies

~5.5MB
~104K SLoC