MGCInts readme

README.md

MGCInts

MGCInts (MML Generic Compiler Interfaces) is a Lua framework for creating binary music compilers with a uniform Music Macro Language syntax. It also contains a frontend to compile its own MML files directly.

MGCInts is licensed under Mozilla Public License Version 2.0.

Features

• One frontend, multiple target music drivers
• Single syntax scheme for almost all MML commands
• Simple, system-agnostic construction of MML grammar definitions
• (TODO) Support for single-song or soundtrack generation
• Utility for rudimentary music stream decompilation
• 100% vanilla Lua (with optional dependencies requiring C compiler)

Prerequisites

• Lua 5.1 or above (required; should be accessible as lua at the command prompt)
• LuaRocks (required for complete installation which also installs Lua-iconv and LuaSocket)
• Lua-iconv (optional; for supporting character encodings other than UTF-8)
• LuaSocket (optional; for fetching external MML engine definitions)
• LDoc (not required; for generating HTML document)
• busted (not required; for framework test scripts)

Installation

$ luarocks install mgcints

Instructions for manual installation are available in INSTALL.md.

Synopsis

To insert a single song:

$ mgcfront my_engine my_song.mml output.bin

To insert multiple songs into a soundtrack output file:

$ mgcfront my_engine -l soundtrack.txt output.bin

Alternatively, on Linux systems MML files may be directly "executed":

$ cat my_song.mml
#!/usr/bin/env mgcfront my_engine
/* ... */
$ ./my_song.mml         # no output specified, uses "my_song.bin" as default

Sound engines either erase the contents of the output file before compiling, or require an existing file for patching. The full usage text is available with mgcfront --help.

Directory

Below is the structure of this repository: (a LuaRocks installation will certainly have a different structure)

• README.md: This file
• INSTALL.md: Installation manual
• CHANGES.md: Change log
• HOWTO.md: Introduction to MGCFront and frequently asked questions
• COPYING: The software license (MPL-2.0)
• MGCInts-xxx.rockspec: LuaRocks specification
• installer.bat: Installer batch script for Windows
• installer.sh: Installer shell script for Linux
• bin/: System-dependent launchers
• doc/: LDoc-generated guide and manual
• etc/: Miscellaneous utility scripts
• include/: Tentative MML grammar definitions
• mml/: Example MML scripts
• src/mgcints/: The framework source scripts
  • default/: Default definitions
  • engine/: Complete MML grammar definitions
  • mml/: MML processing module
  • music/: Music data representation module
  • util/: Helper classes
• src/mgcfront.lua: The frontend script
• test/: Framework test scripts

Contributing

• Source code: Create a fork and pull request on Github for this repository. It must contain also at least one test script.
• Sound engine: Submit all the required Lua scripts to MantisBT under the appropriate category.