mudlet-muddler-luarocks-starter

Local Development Environment

Preliminaries

Before starting, ensure the following tools are installed and available in your system PATH:

• Lua 5.1 is installed and accessible as lua in your PATH (or project root when using luaver).
• LuaRocks is installed and accessible as luarocks in your PATH (or project root when using luaver).
• muddler is installed, executable, and available on your PATH as muddler (or ensure you know the path to the JAR if running directly).

You can verify each with:

lua -v
luarocks --version
muddler --version # or: java -jar /your/path/to/muddle-1.1.0-all.jar --version

Initialize luarocks

From the project root:

luarocks init --lua-versions "5.1"

Running Lua code

Use the set_paths.lua helper to run src/ code directly:

From the project root:

./lua -l set_paths src/path/to/your/script

Running tests

From the project root:

1. Install busted:

   ./luarocks install --tree=lua_modules busted
   

2. Run tests:

   ./lua_modules/bin/busted tests
   

Note:
mudlet-package-dev-1.rockspec defines runtime dependencies. Only pure-Lua, runtime dependencies should be listed in the .rockspec. Install dev dependencies like busted manually into your preferred scope, like shown above.

Building the Mudlet package

From the project root:

(cd muddler && \
  ../scripts/compose_build_context.sh && \
  muddler)

The built package is located at:

muddler/build/muddler_luarocks_starter.mpackage

Notes on build context composition

The compose_build_context.sh script sets up the build context in the existing muddler/ folder:

1. Installs runtime dependencies
   from your .rockspec into a clean lua_modules directory inside the build context. This ensures runtime-only dependencies are packaged, while e.g. tests run against the broader set of development dependencies (which may include binaries like busted).
2. Copies src contents
   Source files are placed into the build context.

Resulting structure after the build completes:

├── muddler
│   ├── build                    # build directory (owned by muddler)
│   ├── .gitignore
│   ├── .output                  # build related metadata (owned by muddler)
│   ├── mfile
│   ├── README.md
│   └── src
│       ├── (...)
│       ├── resources
│       │  └── lua
│       │      ├── lua_modules   # deps from mudlet-package-dev-1.rockspec
│       │      └── scripts       # src contents
│       │          ├── boot.lua
│       │          └── test
│       │              ├── TestableClass_spec.lua
│       │              └── TestableClass.lua
│       ├── (...)

Note:
The .output file is a build output metadata file generated by muddler. It records the name and path of the most recent package build and is used by the helper script to detect changes and trigger automatic (re)installation.

Setting up muddler’s automatic package installation for local development

To enable automatic (re)installation in Mudlet for a given profile during development:

1. Install muddler’s helper package
   Add muddler.mpackage to the Mudlet profile.
2. Install the helper script:
   Copy the contents of integration/auto_install_helper.lua into a script in the profile. Place this script after the muddler package folder in the profile scripts list.
3. Follow the usage instructions:
   Follow the usage notes in auto_install_helper.lua for environment-specific setup.

This automates package updates when rebuilding locally. Every time the package is rebuilt, Mudlet will detect the change and (re)install the latest version into the profile. ```

This site is open source. Improve this page.