Converting an Existing mpackage to Muddler/GitHub/VS Code Project

Preface

This guide assumes you have a fundamental understanding of the technologies involved, such as VS Code, scripting in Mudlet, and package creation in Mudlet. It is designed to provide a step-by-step approach to setting up your development, testing, building, and committing processes using GitHub, VS Code, and Mudlet, along with the tools Muddler and DeMuddler. Note that Muddler can be used with any text editor; however, this guide uses VS Code for illustration. If you prefer using VI or another editor, adapt these steps accordingly.

Requirements

• Muddler (main repository): Ensure you have both muddle-shadow and Muddler.mpackage. Download the latest release.
• DeMuddler (main repository): Obtain the version suitable for your operating system. Download the latest release.
• Reading: Familiarize yourself with the following Muddler documentation:
  • Usage
  • Continuous Integration/Deployment with Muddler

Steps

Step 1: Create GitHub Project

Set up a new project on GitHub.

Step 2: Clone Your GitHub Project

Clone the repository to your local machine.

Step 3: Run DeMuddler on Your .mpackage File

Execute DeMuddler on your .mpackage file to extract its contents. Example command:

de-muddler -f ThreshBuffs.mpackage

Step 4: Copy De-Muddled Content to GitHub Repo

Copy the extracted files from the de-muddled package directory to your cloned GitHub repository.

Step 5: Open the Repo in VS Code

Launch VS Code and open your cloned repository.

Step 6: Configure Automatic .output File Creation

Edit your mfile to ensure all values are set correctly, especially setting outputFile from false to true to enable automatic package reloading in Mudlet:

outputFile = true

Step 7: Create .gitignore

Add a .gitignore file to exclude build artifacts and other unnecessary files from your repository:

# Ignore build directory and .output file
build/
.output

# Ignore any file starting with "muddle" in the project root directory
/muddle*

Step 8: Create a Symlink or Batch File for Muddler

Create a symlink, batch file, or bash script to run Muddler. For VS Code users with Bash for Git, create an executable bash script named muddle. This script calls Muddler and uses the -w flag to watch and re-compile using Muddler every time there's a change in the source file. This file should be added to .gitignore to avoid including developer-specific configurations in the repository:

#!/usr/bin/bash
/d/muddler/muddle-shadow-1.1.0/muddle-shadow-1.1.0/bin/muddle -w

Step 9: Configure Automatic Recompilation and Releases

To enable automatic recompilation and releases upon pushing to GitHub, add a workflow configuration file (release.yml) under .github/workflows. Refer to this gist for an example.

Step 10: Add Muddler Package in Mudlet

In Mudlet, add the Muddler.mpackage.

Step 11: Create Standalone Script in Mudlet

In Mudlet, create a standalone script following the Muddler package. Refer to the Continuous Integration/Deployment with Muddler page or other sources for examples. My sample script.

Important: This script must be located after the Muddler package or it will not automatically reload in Mudlet.

Step 12: Run Muddler in VS Code

Open the terminal in VS Code and run Muddler:

muddle

Verify everything works correctly, commit your changes to GitHub, and check if the build and deployment processes function as expected.

Conclusion

Following these steps will help you set up an efficient development environment integrating GitHub, VS Code, and Mudlet, leveraging Muddler and DeMuddler for streamlined package management and deployment.