If you just want to use Mudlet, you can skip these steps, and use one of the already ready (pre-compiled) installers ready for download. These instructions are primarily aimed at those who wish to use the latest development branch features or contribute to Mudlet development.

Otherwise, hop in for new adventure!

Compiling

Compiling on Ubuntu

These instructions will get you setup compiling on Ubuntu. Need a hand? Join us on Mudlet's Discord or forums.

Ubuntu 25.04 & later

Following instructions will work on Ubuntu 22.04 as well as all its flavours and derivatives (such as KDE Neon, for example) Important thing is to have Universe repository enabled in your package manager. (on Ubuntu you will have all the repositories that you need already enabled by default.)

1. necessary dependencies

Majority of required dependencies can be obtained from repositories, and can be installed with following command:

 sudo apt install ubuntu-restricted-extras qtcreator build-essential git zlib1g-dev libhunspell-dev \
  libpcre2-dev libzip-dev libboost-dev libboost-all-dev libyajl-dev libpulse-dev libpugixml-dev \
  liblua5.1-0-dev lua-filesystem lua-zip lua-sql-sqlite3 luarocks ccache lua5.1 libsecret-1-dev \
  libglu1-mesa-dev mesa-common-dev libglib2.0-dev libgstreamer1.0-dev libqt5opengl5-dev cmake \
  qt6-multimedia-dev libqt6core5compat6 qt6-tools-dev qtkeychain-qt6-dev qt6-l10n-tools ninja-build \
  qt6-tools-dev-tools libqt6core5compat6-dev qttools5-dev qtmultimedia5-dev qt6-speech-dev libzstd-dev \
  libassimp-dev libcurl4-openssl-dev libssl-dev openssl ca-certificates

1.1 Ubuntu 24.04:

sudo apt install qt6-multimedia-dev

Few of required Lua modules are not available in official repositories, so they have to be installed using luarocks

 sudo luarocks install lcf
 sudo luarocks install luautf8
 sudo luarocks install lua-yajl
 sudo luarocks install lrexlib-pcre2
 sudo luarocks install lpeg

2. obtaining the source code

Obtain the latest in-development code with:

 git clone --recursive -b development https://github.com/Mudlet/Mudlet.git
 mkdir Mudlet/build
 cd Mudlet/build

3. compiling the code

 cmake .. -G Ninja
 ninja

4. installing compiled code

After successful code compilation, next few commands will install resulting binaries, desktop file for menus and appropriate icon.

 sudo cmake --install
 sudo cp ../mudlet.png /usr/share/pixmaps
 sudo cp ../mudlet.desktop /usr/share/applications

5. optional additional software

One of the major reasons for compiling Mudlet from source is the ability to unlock more features that are not enabled in official AppImage. Manual compilation will resolve the issues with sound by using system provided libraries, as well as enable more detailed theming of Mudlet application itself. However, do take note that Mudlet is a Qt based program, and that theming will not 'just work' in GTK based desktop environments (Gnome, XFCE, MATE, Budgie).

 sudo apt install qt5ct

will install a tool for configuration of look and feel of Qt programs inside those desktop environments. Users of Qt based Desktop environments (KDE Plasma, LXQT) can simply use settings provided by environment itself.

Many of Qt widget styles and color schemes are available in official repositories, and will make Mudlet better.

6. Mudlet on Wayland

Mudlet compiled like this will run and work on Wayland, however, there are a few quirks with Keybidings (Numpad may not work as expected). Until that is resolved you may wish to start mudlet with:

 QT_QPA_PLATFORM=xcb mudlet

(enter in terminal or simply change the Exec= line in /usr/share/applications/mudlet.desktop)

7. uninstallation

You can reverse the process described in this guide with following command:

 sudo rm -fr /usr/bin/mudlet /usr/share/mudlet /usr/share/applications/mudlet.desktop /usr/share/pixmaps/mudlet.png

Other Ubuntu Versions

Most of the installation instructions for 22.04 should work for older versions as well. Of note is the required version of Qt, which is 5.14. If your used version of Ubuntu only supplies older Qt versions, have a look at Stephan Binners PPAs, which supplies a whole range of packages for different Ubuntu versions. Be sure to read the installation and usage instructions as Qt is installed to /opt and requires sourcing a script to set up.

Compiling on Chrome OS

These instructions will get you setup compiling on Chrome OS. Need a hand? Join us on Mudlet's Discord or forums.

1. Install dependencies

sudo apt install git build-essential \
  lua5.1 liblua5.1-0-dev libpcre2-dev libboost-dev zlib1g-dev cmake \
  libhunspell-dev lua-rex-pcre2 lua-sql-sqlite3 lua-filesystem lua-zip libyajl-dev \
  libzip-dev libglu1-mesa-dev ccache libpugixml-dev mesa-common-dev qtcreator \
  libpulse-dev libglib2.0-dev luarocks libboost-all-dev libsecret-1-dev \
  ninja-build libsecret-1-dev qt6-tools-dev qt6-5compat-dev qt6-multimedia-dev libzstd-dev \
  libassimp-dev libcurl4-openssl-dev libssl-dev openssl ca-certificates
sudo luarocks install luautf8
sudo luarocks install lua-yajl
sudo luarocks install lpeg

3. Get Mudlet source

git clone --recursive https://github.com/Mudlet/Mudlet.git mudlet

4. Create a build directory

cd mudlet
mkdir build && cd build

5. Run the following command

cmake .. -G Ninja

then:

ninja -j 2

5. Start the application you have just compiled - enjoy

src/mudlet

Compiling on macOS

These instructions will get you setup compiling on macOS. Need a hand? Join us on Mudlet's Discord server or forums otherwise.

1. Install prerequisites

Install XCode, command line tools for XCode, and HomeBrew.

Once everything is installed, do:

 brew doctor
 brew update
 brew install git
 brew install qt6
 brew install zstd
 brew install assimp
 brew install curl
 brew install openssl
 brew install llvm

2. Get Mudlet source

 git clone --recursive https://github.com/Mudlet/Mudlet.git

3. Go to the parent of the mudlet "src" folder and create (if necessary) a build subdirectory (this is so that we can build out of source which keeps the source code clean)

 cd Mudlet && mkdir build

3. Setup your environment

 ./CI/osx.before_install.sh
 ./CI/osx.install.sh

 luarocks config lua_version 5.1
 eval `luarocks path --lua-version=5.1`

For the following, one may have to add _DIR="/opt/homebrew/" such as PCRE2_DIR="/opt/homebrew/" or ZIP_DIR="/opt/homebrew/" if the installation could not find header files.

 luarocks --lua-version=5.1 --lua-dir=`brew --prefix [email protected]` install lrexlib-pcre2 PCRE2_DIR=`brew --prefix pcre2`
 brew install sqlite
 luarocks --lua-version=5.1 --lua-dir=`brew --prefix [email protected]` install luasql-sqlite3 SQLITE_DIR=`brew --prefix sqlite`
 luarocks --lua-version=5.1 --lua-dir=`brew --prefix [email protected]` install luautf8
 luarocks --lua-version=5.1 --lua-dir=`brew --prefix [email protected]` install luafilesystem
 luarocks --lua-version=5.1 --lua-dir=`brew --prefix [email protected]` install lua-zip ZIP_DIR=`brew --prefix libzip`
 luarocks --lua-version=5.1 --lua-dir=`brew --prefix [email protected]` install lpeg

 brew install boost

OK to answer yes to delete files if prompted for the rm command above.

4. Run the following commands

 cd build
 cmake ../../Mudlet -DCMAKE_PREFIX_PATH=`brew --prefix qt6`
 make -j `sysctl -n hw.ncpu`

5. Enjoy

The mudlet.app is now available in src/ for launching:

 open src/Mudlet.app

6. Qt Creator setup

No Lua installation is found, despite it existing on your system? Launch Qt Creator by doing open /Applications/Qt Creator.app (location depends on how you installed it).

Receiving a No rule to make target ... libQt5UiTools_debug.a error? A workaround is to symlink a file.

Mudlet in Qt Creator is not launching due to dyld: Symbol not found: __cg_jpeg_resync_to_restart? See here for a workaround.

7. (Optional) Discord Integration on ARM64

ARM64 binaries are not available libdiscord-rpc so you need to compile and combine it with the existing x86_64 binary into a universal binary.

git clone --single-branch --branch v3.3.0 https://github.com/discord/discord-rpc.git
cd discord-rpc
python build.py libs --shared
lipo ./builds/install/osx-dynamic/lib/libdiscord-rpc.dylib /path/to/existing/x86_64/libdiscord-rpc.dylib -output libdiscord-rpc.dylib -create
// verify that it's a universal binary:
otool -L libdiscord-rpc.dylib
// check it in to source control

8. Troubleshooting

If you get lua errors about translations at runtime,

Lua syntax error:.../mudlet-lua/lua/geyser/GeyserAdjustableContainer.lua:605: attempt to index field 'Locale' (a nil value)

have issues compiling yajl with homebrew, or see these messages in your build logs

warning: lua-yajl not available - translation statistics in settings won't be shown.
Error loading yajl was: module 'yajl' not found:
        no field package.preload['yajl']
        no file './yajl.lua'
        no file '/opt/homebrew/share/lua/5.1/yajl.lua'
        no file '/opt/homebrew/share/lua/5.1/yajl/init.lua'
        no file '/opt/homebrew/lib/lua/5.1/yajl.lua'
        no file '/opt/homebrew/lib/lua/5.1/yajl/init.lua'
        no file './yajl.so'
        no file '/opt/homebrew/lib/lua/5.1/yajl.so'
        no file '/opt/homebrew/lib/lua/5.1/loadall.so'

clone from the YAJL repository then ./configure && sudo make install.

Compiling on Debian

1. Install required packages from main repo.

sudo apt-get install build-essential git libglu1-mesa-dev liblua5.1-0-dev zlib1g-dev libhunspell-dev libpcre2-dev \
libzip-dev libboost-dev libyajl-dev libpulse-dev libsecret-1-dev lua-rex-pcre2 lua-filesystem lua-zip \
lua-sql-sqlite3 libxkbcommon-dev qt6-multimedia-dev qt6-tools-dev qtkeychain-qt6-dev luarocks ccache \
libpugixml-dev libqt6core5compat6-dev qt6-speech-dev libqt6opengl6-dev ninja-build cmake libzstd-dev \
libassimp-dev clang libcurl4-openssl-dev libssl-dev openssl ca-certificates

sudo luarocks install luautf8
sudo luarocks install lua-yajl
sudo luarocks install lrexlib-pcre2
sudo luarocks install lpeg

2. Grab latest Mudlet source.

mkdir ~/Workspace
cd ~/Workspace
git clone --recursive -b development https://github.com/Mudlet/Mudlet.git

3. Make Mudlet.

mkdir ~/Workspace/Mudlet/build
cd ~/Workspace/Mudlet/build
cmake .. -G Ninja

Build Mudlet.

Use a number of CPU's tailored to your system with the -j option for ninja, or just let it use all available resources with no option.

#ninja
#ninja -j $(expr `nproc` - 1)
ninja -j 2

(Optional) Install Mudlet

Installation isn't required, you can simply run the `mudlet` executable found in `~/Workspace/Mudlet/build/src`.

Otherwise;

sudo cmake --install

4. (Optional) Discord library

If you get the following error when starting Mudlet;

Could not find Discord library - searched in:

you need to specify the discord library in your build. Run the following, changing the path where necessary;

export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:~/Workspace/Mudlet/3rdparty/discord/rpc/lib/

and recompile. You should see

Discord integration loaded. Using functions from: "libdiscord-rpc.so"

Compiling on Raspberry Pi OS

These instructions will get you compiling and running Mudlet on Raspberry Pi OS (Buster). Need a hand? Join us on Mudlet's Discord or forums.

1.a Install apt dependencies

sudo apt-get update
sudo apt-get install build-essential git liblua5.1-dev zlib1g-dev libhunspell-dev libpcre2-dev \
  libzip-dev libboost-graph-dev libyajl-dev libpulse-dev lua-rex-pcre2 lua-filesystem lua-zip \
  lua-sql-sqlite3 qt5-assistant qtmultimedia5-dev qttools5-dev luarocks ccache libpugixml-dev cmake ninja-build libzstd-dev \
  libassimp-dev libcurl4-openssl-dev libssl-dev openssl ca-certificates

installing apt dependencies

1.b Install luarocks dependencies

sudo luarocks install luautf8
sudo luarocks install lrexlib-pcre2
sudo luarocks install lua-yajl YAJL_LIBDIR=`find /usr -name "libyajl.so" -printf '%h\n'` YAJL_INCDIR=/usr/include
sudo luarocks install lpeg

after luarocks dependencies

2. Get Mudlet source

mkdir ~/source && cd ~/source
git clone --recursive -b development https://github.com/Mudlet/Mudlet.git

After cloning

3. Create a build directory

 cd Mudlet && mkdir build && cd build

4. Run the following commands to build

cmake -G Ninja -DWITH_UPDATER=NO -DWITH_3DMAPPER=NO ..

After cmake

THEN:

For the fastest compile time while still being able to use the system at all (~35min on a RPi4 with 4GB of ram)

ninja -j $(expr `nproc` - 1)

OR:

Use this if you have an older Raspberry Pi. Be prepared for it to take a while (over an hour) - it is not recommended to try to more than one compilation task at a time on the older systems with the -j option as they will only have a system memory with enough space for one of those tasks:

ninja

Success!

4. Install the application you have just compiled

sudo ninja install

Installed now

5. Enjoy!

# mudlet is in the path, can just run it
mudlet

Compiling on Arch Linux

Note: Instructions below are out of date. Feel free to update them to compile latest development, using cmake.

AUR Install and Compile

Mudlet is available in the Arch User Repository. (If the AUR has become unmaintained/orphaned, then skip below to Manual install.)

To install it use your favourite AUR helper (helper tool will automatically resove dependancies); example using yay :

yay -S mudlet

For more info on this process, visit Arch User Repository - ArchWiki.

Note: For the most recent development version of Mudlet, replace 'mudlet' with 'mudlet-git' in the above commands and proceed as described.

Built in fonts have been disabled, but are available in packages listed as optional dependancies.

Discord support in Mudlet depends on an external library provided by discord-rpc-api, which is also available in AUR, choose whichever variant suits you best.

Manual Install and Compile

These instructions will get you setup compiling on Arch. Need a hand? Join us on Mudlet's Discord or forums.

1. necessary dependencies

Majority of required dependencies can be obtained from repositories, and can be installed with following command:

 sudo pacman -S --needed cmake ninja qt5-multimedia hunspell libzip lua51-filesystem qt5-gamepad lua51-luautf8 pugixml \
  ttf-font qtkeychain-qt5 boost qt5-tools ttf-bitstream-vera ttf-ubuntu-font-family noto-fonts-emoji glu luarocks zstd \
  assimp curl openssl ca-certificates lua51-lpeg

Few of required Lua modules are not available in official repositories, so they have to be installed using luarocks

 sudo lua5.1 /usr/bin/luarocks install lcf
 sudo lua5.1 /usr/bin/luarocks install luautf8
 sudo lua5.1 /usr/bin/luarocks install lua-yajl
 sudo lua5.1 /usr/bin/luarocks install lrexlib-pcre2
 sudo lua5.1 /usr/bin/luarocks install luasql-sqlite3
 sudo lua5.1 /usr/bin/luarocks install lua-zip

There is an optional dependency for discord integration:

 git clone https://github.com/discord/discord-rpc
 cd discord-rpc
 mkdir build
 cd build
 cmake .. -DCMAKE_INSTALL_PREFIX=/usr
 sudo cmake --build . --config Release --target install

2. obtaining the source code

Obtain the latest in-development code with:

 git clone --recursive -b development https://github.com/Mudlet/Mudlet.git
 mkdir Mudlet/build
 cd Mudlet/build

3. compiling the code

There below are two ways to build with cmake, the first is for general use, the second is for developers:

 cmake -G Ninja ..

*OR*

 cmake -G Ninja -DCMAKE_BUILD_TYPE=Debug ..

Now finish compiling:

 ninja

4. installing compiled code

After successful code compilation, next few commands will install resulting binaries, desktop file for menus and appropriate icon.

 sudo ninja install
 sudo cp ../mudlet.png /usr/share/pixmaps
 sudo cp ../mudlet.desktop /usr/share/applications

5. optional additional software

One of the major reasons for compiling Mudlet from source is the ability to unlock more features that are not enabled in official AppImage. Manual compilation will resolve the issues with sound by using system provided libraries, as well as enable more detailed theming of Mudlet application itself. However, do take note that Mudlet is a Qt based program, and that theming will not 'just work' in GTK based desktop environments (Gnome, XFCE, MATE, Budgie).

 sudo pacman -S install qt5ct

will install a tool for configuration of look and feel of Qt programs inside those desktop environments.↵Users of Qt based Desktop environments (KDE Plasma, LXQT) can simply use settings provided by environment itself.

Many of Qt widget styles and color schemes are available in official repositories, and will make Mudlet better.

6. Mudlet on Wayland

Mudlet compiled like this will run and work on Wayland, however, there are a few quirks with Keybindings (Numpad may not work as expected). Until that is resolved you may wish to start mudlet with:

 QT_QPA_PLATFORM=xcb mudlet

(enter in terminal or simply change the Exec= line in /usr/share/applications/mudlet.desktop)

7. uninstallation

You can reverse the process described in this guide with following command:

 sudo rm -fr /usr/bin/mudlet /usr/share/mudlet /usr/share/applications/mudlet.desktop /usr/share/pixmaps/mudlet.png

Compiling on Fedora (aarch64)

1. Install dependencies

sudo dnf group install "development-tools" "development-libs"

sudo dnf install compat-lua compat-lua-devel compat-lua-libs hunspell-devel lua5.1-filesystem luarocks pugixml-devel bitstream-vera-fonts-all ccache qt-creator yajl-devel qtchooser zziplib-devel pcre2-devel libzip-devel sqlite-devel qt6-qt5compat-devel qt6-qtmultimedia-devel qt6-qttools-devel qtkeychain-qt6-devel libasan cmake ninja-build libzstd-devel assimp-devel libcurl-devel openssl-devel ca-certificates

sudo luarocks --lua-version 5.1 --tree=/usr install luazip
sudo luarocks --lua-version 5.1 --tree=/usr install luasql-sqlite3
sudo luarocks --lua-version 5.1 --tree=/usr install lcf
sudo luarocks --lua-version 5.1 --tree=/usr install luautf8
sudo luarocks --lua-version 5.1 --tree=/usr install lua-yajl
sudo luarocks --lua-version 5.1 --tree=/usr install lrexlib-pcre2
sudo luarocks --lua-version 5.1 --tree=/usr install lpeg

In your user's home directory:

If you use a bash shell:

luarocks --lua-version 5.1 path --no-bin >> .bashenv
source .bashenv

If you use a zsh shell:

luarocks --lua-version 5.1 path --no-bin >> .zshenv
source .zshenv

If you use a csh shell:

luarocks --lua-version 5.1 path --no-bin >> .cshenv
source .cshenv

This should cover paths, but you may want to reboot to be sure.

2. Obtain the source code

git clone --recursive --branch=development https://github.com/Mudlet/Mudlet.git mudlet

3. Create and move into build directory

mkdir mudlet/build && cd mudlet/build

4. Compile

Run this in the build directory:

cmake .. -G Ninja

Once complete, run the following:

ninja

5. Start the application you have just compiled - enjoy

src/mudlet

To ensure you can see qDebug() output, disable a default Fedora rule:

export QT_LOGGING_RULES='*.debug=true'

Compiling on FreeBSD

This has been verified on FreeBSD-14 and FreeBSD-15 (Feb 2024.) Please reach out to erikarn ([email protected]) if you have any updates / questions!

As root, install pre-requisite packages

# pkg install git lua51 lua51-luarocks cmake gmake qt6 pugixml sqlite3 yajl boost-libs qtkeychain-qt6 zstd assimp curl

1. As root, install lua packages

# luarocks51 install luautf8
# luarocks51 install luafilesystem
# luarocks51 install lua-zip
# luarocks51 install luasql-sqlite3
# luarocks51 install lrexlib-pcre2
# luarocks51 install lua-yajl
# luarocks51 install lpeg

2. As a user, check out the source code

$ git clone --recursive --branch=development https://github.com/Mudlet/Mudlet.git

3. As a user, create the build directory, run cmake and build

$ mkdir Mudlet/build
$ cd Mudlet/build
$ cmake ..
$ gmake

4. As root, install!

# gmake install

Compiling on Gentoo

An overlay containing Mudlet is available for compiling Mudlet on Gentoo.

Compiling on Windows

Install MSYS2: https://www.msys2.org

At the end of installation uncheck run msys2 now and click finish

Run MSYS2 MINGW64 from the start menu

Run the following in the opened MSYS2 terminal (you right-click in order to paste):

pacman --files --refresh
pacman --sync git mingw-w64-x86_64-qt-creator mingw-w64-x86_64-cmake mingw-w64-x86_64-ninja mingw-w64-x86_64-clang-libs mingw-w64-x86_64-zstd mingw-w64-x86_64-assimp mingw-w64-x86_64-curl mingw-w64-x86_64-openssl mingw-w64-x86_64-ca-certificates mingw-w64-x86_64-lua51-lpeg --noconfirm

Run the following from the MSYS2 terminal:

git clone --recursive -b development https://github.com/Mudlet/Mudlet.git

Setup the development environment (~5-10min) by running:

./Mudlet/CI/setup-windows-sdk.sh

Take note of the message at the end to add the variables to your environment once you have opened the project in Qt Creator. (WITH_MAIN_BUILD_SYSTEM, MINGW_BASE_DIR, LUA_PATH, LUA_CPATH)

Note: This might not work on windows arm64, pacman freezes.

Open Qt Creator. You will need to open it via MSYS2 every time:

/mingw64/bin/qtcreator.exe

Press link with Qt on the bottom right of Qt Creator

Choose C:/msys64/mingw64 as the location then restart Qt Creator

Open project; C:/msys64/home/<user>/Mudlet/src/mudlet.pro

In Build Environment details, set environment variables to what was stated in the sdk-setup script above.

Build Mudlet (Ctrl+B)
Run Mudlet (Ctrl+R)

Contributing changes

Once you're all done with your changes, contribute them to Mudlet using a pull request. Thanks for improving open-source!

Compiling on Github Codespaces

Github Codespaces allow you to code and run Mudlet all from the browser - makes it a lot easier to get started. It also allows you to code Mudlet itself from any computer in the world!

1. Create a new codespace

Create a new Codespace by going to https://github.com/Mudlet/Mudlet using Google Chrome or Microsoft Edge (Firefox at the time of the writing doesn't have working copy/paste). There, click the green "Code" button, select the "Codespaces" tab and click "New codespace".

2. Wait for it to load

This will take a while (~5min) so grab a tea:

3. Connect to the environment

Go to the Ports section at the bottom and change the Port Privacy of the Open Mudlet port to Public:

Then connect to your online Linux desktop with mudlet as the password by clicking on the web icon.

In case it can't connect, make sure the port privacy is set to Public. If it still can't connect, try 4-5 more times - eventually it'll work.

We chose a retro 90's look here to fit with the whole hacking theme, so if you see this you're good 😉

4. Build Mudlet

In Codespaces, hit F7 and select Let CMake guess...

It will then start building Mudlet automatically. Using the Basic instance (only kind available in beta) the first-time build will take ~25min, so take a break here - you've made excellent progress. All follow-up compiles after this will be quicker, by the way.

5. Run Mudlet

Hit the little play button at the bottom of the screen, and Mudlet will now launch in the remote connection tab. Not working? We can help. Otherwise, enjoy!

Note: When the codespace is unused for a while, it will disconnect. It'll never disconnect while you're actively using it. See Github issue for details.

Developing with Docker

Docker is a system designed for more reproducible and isolated builds. A docker setup exists and has been tested using Pop OS! 20.04 (which is derived from Ubuntu 20.04). First, follow the instructions to install both docker and docker-compose.

Clone the development branch

 git clone --recursive -b development https://github.com/Mudlet/Mudlet.git
 cd Mudlet/docker

Make a local copy of the .env.template file:

 cp .env.template .env

If you wish to customize things like the number of cores to use for building mudlet, feel free to change the corresponding values in the .env file.

To run Qt-Creator and develop Mudlet, run docker-compose up dev.

To run Mudlet, run docker-compose up mudlet. Note: At the moment, the mudlet build will not persist settings past container rebuilds.

Setting up IDEs

CLion

Qt not detected

If you'd like to use CLion and it is giving the following error:

    By not providing "FindQt5Core.cmake" in CMAKE_MODULE_PATH this project has
    asked CMake to find a package configuration file provided by "Qt5Core", but
    CMake did not find one.

    ...

You can fix this by setting -DCMAKE_PREFIX_PATH=<your Qt + version + compiler location>. For example: -DCMAKE_PREFIX_PATH=/home/vadi/Programs/Qt/6.8.1/gcc_64/

CLion setup on Windows

After running setup-windows-sdk.ps1 make sure to set Cmake options to:

-DCMAKE_PREFIX_PATH=C:\Qt\Tools\mingw730_32;C:\Qt\5.14.2\mingw73_32 -DBoost_INCLUDE_DIR=C:\Libraries\boost_1_77_0

Directories might vary slightly, when different Qt, Boost or MinGW version will be used.

You will need 32 bit version of MinGW. Set it in the Toolset field to:

C:\Qt\Tools\mingw730_32

Directory may be slightly different if MinGW version used will change.

Clang Tidy

Ensure that CLion is set to run the project's .clang-tidy checks with the Prefer .clang-tidy files over IDE settings option:

This helps us catch any issues just a bit earlier.

Checking memory leaks & other issues (sanitizers)

Besides clang-tidy, it's also possible to enable clang sanitizers to double-check for issues:

LeakSanitizer for detecting memory leaks
AddressSanitizer for detecting most issues dealing with memory, such as out of bounds accesses to heap, stack, global and more
UndefinedBehaviourSanitizer for detecting the use of various features of C/C++ that are explicitly listed as resulting in undefined behaviour (such as using misaligned or null pointer, conversion to, from, or between floating-point types which would overflow the destination, division by zero, etc)
MemorySanitizer for detecting reading uninitialised memory
ThreadSanitizer for detecting threading issues

To use the sanitisers, set the USE_SANITIZER CMake variable to one or several variables (separate by comma): Address, Memory, MemoryWithOrigins, Undefined, Thread, or Leak

To use them in CLion, adjust the CMake settings:

Not all sanitisers can be used with each other - in that case the cmake configuration won't allow you to continue.

Clang Format

Ensure that CLion is set to use the .clang-format formatting style:

This helps keep the look'n'feel of the source code in a consistent manner, even with many people contributing to Mudlet.

Developing with CLion and WSL

There are two main ways to utilize the Windows Subsystem for Linux (WSL) for development with CLion:

Running the IDE on Windows while building Mudlet inside the WSL environment.
Using a remote toolchain with a thin client.

The second option is well covered in the official JetBrains documentation: in WSL with CLion Below we cover Mudlet-specific details for both approaches.

Preparing WSL Environment

This step is required for both approaches.*

It is recommended to install WSL with the Ubuntu distribution, as this allows you to follow the same environment preparation steps as on a regular Ubuntu system.

At the time of writing (17 October 2025), the Ubuntu repositories do not provide the latest Qt version, nor the version required by Mudlet.

To install Qt manually, run the following commands:

curl -O -L https://download.qt.io/official_releases/online_installers/qt-online-installer-linux-x64-online.run
chmod +x qt-online-installer-linux-x64-online.run
./qt-online-installer-linux-x64-online.run

If the above instructions become outdated, refer to the Qt installation guide for the latest installer.

Configuring CLion for Remote WSL development

Once Qt installation and all required dependencies are complete, and you have checked out the repository inside the WSL file system, you can open the project from the Remote Development tab in CLion and select WSL.

Don't forget to set the CMAKE_PREFIX_PATH:

Configuring CLion for WSL building

This requires two steps, setting up WSL toolchain and setting up CMake to use it.

Visual Studio Code

To set the path in Visual Studio Code, open settings, search for cmake environment and set the CMAKE_PREFIX_PATH to your path, such as /home/vadi/Programs/Qt/5.15.2/gcc_64:

Clang Tidy

clang-tidy catches common programming issues, run it by selecting 'Analysis' from the command palette (Ctrl+Shift+P by default):

It is also possible check status of analysis and cancel if needed.

Checking memory leaks & other issues (sanitizers)

Besides clang-tidy, it's also possible to enable clang sanitizers to double-check for issues:

LeakSanitizer for detecting memory leaks
AddressSanitizer for detecting most issues dealing with memory, such as out of bounds accesses to heap, stack, global and more
UndefinedBehaviourSanitizer for detecting the use of various features of C/C++ that are explicitly listed as resulting in undefined behaviour (such as using misaligned or null pointer, conversion to, from, or between floating-point types which would overflow the destination, division by zero, etc)
MemorySanitizer for detecting reading uninitialised memory
ThreadSanitizer for detecting threading issues

To use the sanitisers, set the USE_SANITIZER CMake variable to one or several variables (separate by comma): Address, Memory, MemoryWithOrigins, Undefined, Thread, or Leak

To use them in VSCode, set the cmake.configureSettings variable:

Not all sanitisers can be used with each other - in that case the cmake configuration won't allow you to continue.

Qt Creator

Clang Tidy and Clazy

Configure Mudlet-specific checks for clang-tidy and clazy tools help catch any issues early on. See Qt Creator's instructions for setting this up - clang-tidy can use the .clang-tidy file that's available at the root of the repository, and for clazy enable level0 and level1 checks.

Checking memory leaks & other issues (sanitizers)

Besides clang-tidy, it's also possible to enable clang sanitizers to double-check for issues:

LeakSanitizer for detecting memory leaks
AddressSanitizer for detecting most issues dealing with memory, such as out of bounds accesses to heap, stack, global and more
UndefinedBehaviourSanitizer for detecting the use of various features of C/C++ that are explicitly listed as resulting in undefined behaviour (such as using misaligned or null pointer, conversion to, from, or between floating-point types which would overflow the destination, division by zero, etc)
MemorySanitizer for detecting reading uninitialised memory
ThreadSanitizer for detecting threading issues

To use the sanitisers, set the USE_SANITIZER CMake variable to one or several variables (separate by comma): Address, Memory, MemoryWithOrigins, Undefined, Thread, or Leak

To use them in Qt creator, head to Projects - Build:

Not all sanitisers can be used with each other - in that case the cmake configuration won't allow you to continue.

Clang Format

Ensure that Qt Creator is set to use the .clang-format formatting style in the C++ settings. Turn on Format instead of indenting for Ctrl+I to format code, and ensure Override Clang Format configuration file is disabled:

This helps keep the look'n'feel of the source code in a consistent manner, even with many people contributing to Mudlet.

Building with multiple versions of Lua

Mudlet uses Lua 5.1 only, so if you are compiling on a system that also has later versions installed, you might get the following error: 'LUA_GLOBALSINDEX' was not declared in this scope.

To fix this, pass the path to Lua headers explicitly. For CMake: -DLUA_INCLUDE_DIR=/usr/include/lua5.1 (adjust as needed).

Key contributing information

Clang format is used to automatically format code submissions using the src/.clang-format style. See here how to enable clang-format with Qt Creator - and make sure to specify the 'File' option for the configuration style.

Branches:

development is the development branch where new features can go.

Workflow:

Fork and submit a PR with your changes (Github tutorial).

Here is a list of package versions delivered with different Linux distros. You may want to upgrade these: https://repology.org/project/mudlet/versions

Testing in-progress PRs

If you are testing Mudlet PRs and find yourself downloading test Mudlet builds often, there are a couple of scripts available to help you automate this. The idea is that you can run these scripts on a regular basis, and you'll have all of the PRs that can be tested already built or downloaded - so you can go through them in bulk without having to download each one by hand.

1. Create a new, separate checkout of the Mudlet git repository. This needs to be separate from your usual development checkout:

 git clone https://github.com/Mudlet/Mudlet.git

2. Install Github CLI

3. Login using Github CLI:

 gh auth

4a. Choose if you'd like to compile all Mudlet PRs (pick this if you have a slow / metered internet connection, or a fast computer): build-pr-worktrees.sh

4b. Choose if you'd like to download pre-built Mudlet PRs (pick this if you have a fast / unmetered internet connection, or a slow computer): download-pr-artifacts.sh

5a. Run the build script. Ready to use Mudlets will be available in ./builds/pr-<number>/:

# build all ready for review PRs
./build-pr-worktrees.sh

# build all ready for review and draft PRs
 ./build-pr-worktrees.sh --include-drafts

# if some PRs got merged, clean up their folders
 ./build-pr-worktrees.sh --cleanup

5b. Run the download script. Ready to use Mudlets will be available in ./artifacts/pr-<number>/:

# download all ready for review PRs
./download-pr-artifacts.sh

# download all ready for review and draft PRs
 ./download-pr-artifacts.sh --include-drafts

# if you have a fast connection, download N artifacts at a time (default is 8):
./download-pr-artifacts.sh --include-drafts --jobs 20

# if some PRs got merged, clean up their folders
 ./download-pr-artifacts.sh --cleanup

Lua & Luarocks

Mudlet includes a Lua (version 5.1) scripting system for the end-user, which you, as a reader of this Wiki, may already be aware of! If not, you might wish to (after you have got your hands on a working Mudlet) take a look at Mudlet Lua API as that is the recommended place to find out the details of all the functions that Mudlet provides on top of the core Lua functionality.

Some of that ability comes from extra code that is not built-in to Lua but is in the form of external modules either in the form of script (text) files written in the Lua language itself or binary (library) files compiled from (usually but not exclusively 'C') source code. In order to have that functionality Mudlet makes use of several of these modules which can most readily (if not already available as "packages" for a particular Operating System) be obtained as rocks from the public Luarocks collection. Such a rock actually consists of a rockspec file that gives instructions to the Luarocks tool how to obtains the (source) code, compile it on any supported OS into the form that a Lua interpreter (including the one included in each running Mudlet profile) can use, and where and what it will be placed and called when it has been made. After that it should be available to Lua via the require command.

Anyone compiling Mudlet for themselves will find it desirable to ensure they have a usable Luarocks installation and have the lua-yajl module installed before commencing to compile Mudlet itself; this is because a Lua (version 5.1) interpreter and that module are used within the build process of making the executable code that is the Mudlet application.

Included Modules

luautf8 (manual in README)
lcf (customised version)
luafilesystem (manual)
lrexlib-pcre2 (manual)
luasql-sqlite3 (http://lunarmodules.github.io/luasql/manual.html manual)
lua-yajl (manual in GitHub README manual)
lua-zip (manual in GitHub README manual)

Adding Luarocks

Here's a rundown on checking you can use luarocks. Here we will use the bit32 module as an example.

1. Install via luarocks

> luarocks install bit32

2. Check where luarocks installs the modules. Note the modules section.

> luarocks show bit32

bit32 5.3.5.1-1 - Lua 5.2 bit manipulation library

bit32 is the native Lua 5.2 bit manipulation library, in the version from Lua 5.3; it is compatible with Lua 5.1, 5.2, 5.3 and 5.4.

License:        MIT
Homepage:       http://www.lua.org/manual/5.2/manual.html#6.7
Installed in:   /usr/local

Modules:
        bit32 (/usr/local/lib/lua/5.1/bit32.so)

Depends on:
        lua >= 5.1, < 5.5 (using 5.1-1)

3. Recompile mudlet. You may need to adjust lua path and cpath information for your environment. You can use the following commands to help find this information.

> luarocks --lua-version 5.1 path --no-bin
export LUA_PATH='./?.lua;/usr/local/share/lua/5.1/?.lua;/usr/local/share/lua/5.1/?/init.lua;/usr/local/lib/lua/5.1/?.lua;/usr/local/lib/lua/5.1/?/init.lua;/usr/share/lua/5.1/?.lua;/usr/share/lua/5.1/?/init.lua;/home/username/.luarocks/share/lua/5.1/?.lua;/home/username/.luarocks/share/lua/5.1/?/init.lua'
export LUA_CPATH='./?.so;/usr/local/lib/lua/5.1/?.so;/usr/lib/x86_64-linux-gnu/lua/5.1/?.so;/usr/lib/lua/5.1/?.so;/usr/local/lib/lua/5.1/loadall.so;/home/username/.luarocks/lib/lua/5.1/?.so

Or from within mudlet itself you can issue these commands to double check the correct paths are being used.

> lua print(package.path)
/home/username/.config/mudlet/profiles/localhost/?.lua;/home/zooka/.config/mudlet/profiles/localhost/?/init.lua;./?.lua;/usr/local/share/lua/5.1/?.lua;/usr/local/share/lua/5.1/?/init.lua;/usr/local/lib/lua/5.1/?.lua;/usr/local/lib/lua/5.1/?/init.lua;/usr/share/lua/5.1/?.lua;/usr/share/lua/5.1/?/init.lua;/home/username/.luarocks/share/lua/5.1/?.lua;/home/username/.luarocks/share/lua/5.1/?/init.lua

> lua print(package.cpath)
/home/username/.config/mudlet/profiles/localhost/?.so;/home/username/Workspace/mudlet-dev/Mudlet/build/lib/?.so;./?.so;/usr/local/lib/lua/5.1/?.so;/usr/lib/x86_64-linux-gnu/lua/5.1/?.so;/usr/lib/lua/5.1/?.so;/usr/local/lib/lua/5.1/loadall.so;/home/username/.luarocks/lib/lua/5.1/?.so

4. Recompile and run a test script using the require command to load in the necessary library.

bit32 = require("bit32")

function bit32_test()
  bit32.band(0,1)
end

Enabling Debug Build

To enable a debug build that can be run through GDB:

follow all steps until cmake
modify the cmake line by setting the build type to Debug, e.g.:

 cmake -G Ninja -DCMAKE_BUILD_TYPE=Debug ..

compile as normal
attach gdb to mudlet

 gdb ./mudlet

within gdb command line start mudlet running by:

run

proceed to crash mudlet then type

bt

submit the output with your bug reports.

Static Analysis

Static analysis helps detect bugs, performance issues, and code quality problems during compilation. Mudlet includes integration with clang-tidy and cppcheck that can be optionally enabled.

Installing Dependencies

macOS

brew install llvm

Linux (Ubuntu/Debian)

sudo apt install clang-tidy cppcheck

Linux (Arch)

sudo pacman -S clang cppcheck

Linux (Fedora)

sudo dnf install clang-tools-extra cppcheck

Windows (MSYS2)

pacman -S mingw-w64-x86_64-clang-tools-extra mingw-w64-x86_64-cppcheck

Running Static Analysis

Static analysis is controlled by a CMake flag and runs during normal compilation:

1. Reconfigure cmake with static analysis enabled:

cd /path/to/Mudlet/build
cmake -DENABLE_STATIC_ANALYSIS=ON ..

2. Build with output capture:

On macOS:

make -j `sysctl -n hw.ncpu` 2>&1 | tee mudlet_static_analysis.log

On Linux:

cmake --build . 2>&1 | tee mudlet_static_analysis.log

On Windows (PowerShell):

cmake --build . 2>&1 | Tee-Object -FilePath mudlet_static_analysis.log

3. Filter results to Mudlet source code only:

grep -E "warning:" mudlet_static_analysis.log | grep -v "3rdparty" | grep -v "ld: warning" | sort -u

Static analysis warnings will appear during compilation but won't fail the build. Review the filtered output to identify issues specific to Mudlet's source code.

Checks Performed

The static analysis performs the following checks:

performance-* - Performance optimizations and unnecessary copies
bugprone-* - Common programming errors and bugs
clang-analyzer-* - Deep static analysis from Clang Static Analyzer

These checks are defined in the Template:Code configuration file at the root of the repository.

Compile Time Flags

DEBUG_UTF8_PROCESSING - for decoding the UTF-8 (1 byte with the MSB set or 2, 3 or 4 bytes) encoding
DEBUG_GB_PROCESSING - for decoding the GBK (2 bytes) or GB18030 (2 or 4 bytes) encodiing
DEBUG_BIG5_PROCESSING - for decoding the Big5-ETEN or Big5-HKSCS encodings
DEBUG_EUC_KR_PROCESSING - for decoding the EUC_KR encoding
DEBUG_SGR_PROCESSING - decoding the <ESC>[ codes (that pair of bytes being the CSI "Control Sequence Introducer" - including the one ending in m which is the "Set Graphics Rendition" that Mudlet (and other MUD clients and other things) use to control colours and other font effects.
DEBUG_OSC_PROCESSING - decode the <ESC>] codes (that MUST end with a <ESC>\) - currently Mudlet only handles a couple of these OSC "Operating System Commands".
DEBUG_MXP_PROCESSING - stuff to do with the MXP protocol - which uses a <ESC> ... z sequence of characters to do some things...

Compiling Mudlet

Compiling

Compiling on Ubuntu

Ubuntu 25.04 & later

Other Ubuntu Versions

Compiling on Chrome OS

Compiling on macOS

Compiling on Debian

Compiling on Raspberry Pi OS

Compiling on Arch Linux

AUR Install and Compile

Manual Install and Compile

Compiling on Fedora (aarch64)

Compiling on FreeBSD

Compiling on Gentoo

Compiling on Windows

Contributing changes

Compiling on Github Codespaces

Developing with Docker

Setting up IDEs

CLion

Qt not detected

CLion setup on Windows

Clang Tidy

Checking memory leaks & other issues (sanitizers)

Clang Format

Developing with CLion and WSL

Preparing WSL Environment

Configuring CLion for Remote WSL development

Configuring CLion for WSL building

Visual Studio Code

Clang Tidy

Checking memory leaks & other issues (sanitizers)

Qt Creator

Clang Tidy and Clazy

Checking memory leaks & other issues (sanitizers)

Clang Format

Building with multiple versions of Lua

Key contributing information

Testing in-progress PRs

Lua & Luarocks

Included Modules

Adding Luarocks

Enabling Debug Build

Static Analysis

Installing Dependencies

macOS

Linux (Ubuntu/Debian)

Linux (Arch)

Linux (Fedora)

Windows (MSYS2)

Running Static Analysis

Checks Performed

Compile Time Flags

Navigation menu

Search