Compiling Mudlet

If you just want to use Mudlet, you can skip these steps, and use one of the pre-compiled installers ready for download here: https://www.mudlet.org/download/

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).

Note:

if you've previously compiled Mudlet - src/src.pro has been renamed to src/mudlet.pro in Mudlet 3.3.

Continuous Integration

Mudlet is hosted on Github it uses Travis and AppVeyor for continuous integration by building on a Ubuntu 14.04 LTS Linux and a macOS 10.11 platforms (Travis) and a Visual Studios 2015 on a MicroSoft Windows Server 2012 R2 platform (AppVeyor) repectively. This means that every push to the Git repository is test compiled on Linux (Ubuntu), Mac OSX and Microsoft Windows.

Travis integration is defined in a .travis.yml file and AppVeyor integration by .appveyor.yml file, in our case, they reference shell/PowerShell scripts in the CI directory, which handle things like installing dependencies and building mudlet.

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 18.04 setup

For Ubuntu 18.04 see the instructions for Compiling on Debian 9 'Stretch' (tested working perfectly).

1. Ubuntu 18.04 setup

If you're on Ubuntu 18.04 (Bionic Beaver), install the following. If you're on a newer Ubuntu, skip this step and go to 2. Install dependencies.

 sudo add-apt-repository ppa:beineri/opt-qt-5.12.3-bionic
 sudo apt update
 sudo apt install qt512-meta-full qt512creator
 source /opt/qt512/bin/qt512-env.sh

2. Install dependencies

sudo apt install git build-essential qt5-default qtmultimedia5-dev qttools5-dev \
  lua5.1 liblua5.1-0-dev libpcre3-dev libboost-dev zlib1g-dev cmake \
  libhunspell-dev lua-rex-pcre lua-sql-sqlite3 lua-filesystem lua-zip libyajl-dev \
  libzip-dev libgstreamer0.10-0 libglu1-mesa-dev ccache libpugixml-dev \
  mesa-common-dev qtcreator libpulse-dev libglib2.0-dev luarocks libboost-all-dev
sudo apt install gstreamer0.10-fluendo-mp3 # may not work on newer Ubuntu
sudo luarocks install luautf8
sudo luarocks install lua-yajl

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 commands, depending on which build system you want to use

EITHER:

cmake ..

OR:

qmake CONFIG+=debug ../src/mudlet.pro

THEN:

make -j `nproc`

5. Start the application you have just compiled - enjoy

cd src
./mudlet

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 qt5-default qtmultimedia5-dev qttools5-dev \
  lua5.1 liblua5.1-0-dev libpcre3-dev libboost-dev zlib1g-dev cmake \
  libhunspell-dev lua-rex-pcre 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
sudo luarocks install luautf8
sudo luarocks install lua-yajl

You'll also need to download a few files from the web and install them locally.

libgstreamer0.10 - gstreamer0.10-fluendo-mp3 - liboil0.3

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

qmake CONFIG+=debug ../src/mudlet.pro

THEN:

make -j `nproc`

5. Start the application you have just compiled - enjoy

./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, HomeBrew and CocoaPods (we'll need packages from both).

Once everything is installed, do:

 brew doctor
 brew update
 brew install git

2. Get Mudlet source

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

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)

 mkdir build

3. Setup your environment you only need the first three lines if your system cannot find the right Qt libraries or tools, the added directories might be different if you have installed them differently

 export PATH="/usr/local/opt/qt5/bin:$PATH"
 export LDFLAGS=" -L/usr/local/opt/qt5/lib ${LDFLAGS}"
 export CPPFLAGS=" -I/usr/local/opt/qt5/include ${CPPFLAGS}"
 CI/travis.osx.before_install.sh
 CI/travis.osx.install.sh

 luarocks config lua_version 5.1
 eval `luarocks path`

 luarocks --lua-version=5.1 --lua-dir=`brew --prefix lua@5.1` install lrexlib-pcre
 luarocks --lua-version=5.1 --lua-dir=`brew --prefix lua@5.1` install luasql-sqlite3 SQLITE_DIR=`brew --prefix sqlite` 
 luarocks --lua-version=5.1 --lua-dir=`brew --prefix lua@5.1` install luautf8
 luarocks --lua-version=5.1 --lua-dir=`brew --prefix lua@5.1` install lua-yajl
 luarocks --lua-version=5.1 --lua-dir=`brew --prefix lua@5.1` install luafilesystem

4. Go to the mudlet build folder

 cd build

5. Run the following commands

 qmake ../src/mudlet.pro

 make -j `sysctl -n hw.ncpu`

6. Enjoy

The Mudlet.app is now available in src/ for launching.

Compiling on Debian 'Sid'

1. Install required packages from main repo.

sudo apt-get install build-essential git liblua5.1-dev zlib1g-dev libhunspell-dev libpcre3-dev \
libzip-dev libboost-dev libyajl-dev libpulse-dev lua-rex-pcre lua-filesystem lua-zip \
lua-sql-sqlite3 qt5-default qtmultimedia5-dev qttools5-dev luarocks ccache libpugixml-dev

sudo luarocks install luautf8
sudo luarocks install lua-yajl

2. Grab latest Mudlet source.

mkdir ~/projects && cd ~/projects && git clone --recursive https://github.com/Mudlet/Mudlet.git mudlet

3. Build Mudlet.

cd ~/projects/mudlet/src

qmake

make

sudo make install

Compiling on Debian 9 'Stretch'

1. Install required packages.

sudo apt-get install build-essential git liblua5.1-dev zlib1g-dev libhunspell-dev libpcre3-dev \
libzip-dev libboost-dev libyajl-dev libpulse-dev lua-rex-pcre lua-filesystem lua-zip \
lua-sql-sqlite3 qt5-default qtmultimedia5-dev qttools5-dev luarocks ccache libpugixml-dev

sudo luarocks install luautf8  
sudo luarocks install lua-yajl

2. Get Mudlet source.

mkdir ~/source && cd ~/source

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

Note: the line above will check out `development` branch source code, and this might not always be stable. You can check out the latest release source code using this command:

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

3. Build Mudlet.

mkdir ~/source/Mudlet/build && cd ~/source/Mudlet/build

qmake ../src/mudlet.pro

make -j `nproc`

sudo make install

After these steps you can run Mudlet by typing:

mudlet

Compiling on Raspberry Pi (raspbian buster)

These instructions will get you compiling and running Mudlet on raspbian 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 libpcre3-dev \
  libzip-dev libboost-graph-dev libyajl-dev libpulse-dev lua-rex-pcre lua-filesystem lua-zip \
  lua-sql-sqlite3 qt5-default qtmultimedia5-dev qttools5-dev luarocks ccache libpugixml-dev cmake

installing apt dependencies

1.b Install luarocks dependencies

sudo luarocks install luautf8  
sudo luarocks install lua-yajl YAJL_LIBDIR=/usr/lib/arm-linux-gnueabihf/ YAJL_INCDIR=/usr/include

after luarocks dependencies

2. Get Mudlet source

mkdir ~/source && cd ~/source 
git clone 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

WITH_UPDATER=NO WITH_3DMAPPER=NO qmake ../src/mudlet.pro

If you get a response along the lines of:

qmake: could not find a Qt installation of 

then you likely have qtchooser present in your system that allows for both Qt4 and Qt5 (or more than one Qt5 version) and it modifiers qmake and some other Qt development programs to take an additional argument to specify which version to use. In that case you should use:

WITH_UPDATER=NO WITH_3DMAPPER=NO qmake -qt=qt5 ../src/mudlet.pro

After qmake

THEN:

For the fastest compile time, 15-20min on a RPi4 with 4GB of ram

make -j `nproc`

OR:

If you want to use your pi while it builds or 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 some of those tasks:

make

Success!

4. Install the application you have just compiled

sudo make install

Installed now

5. Enjoy!

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

Compiling on ArchLinux

Mudlet is available in the Arch User Repository.

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 extrenal library provided by discord-rpc-api, which is also available in AUR, choose whichever variant suits you best.

Compiling on Gentoo

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

Compiling on Windows 7+

These instructions will get you setup compiling on Windows.

Need a hand? Join us on the Mudlet Discord server or forums.

1. Download Mudlet source code

1. Install Github Desktop.
2. Clone (instructions) Mudlet's repository to your local drive.

Note: You must use a location on C:\ without any spaces in folder names!

2. Perform a one-time setup

Right-click on setup-windows-sdk.ps1 and select Run with PowerShell. This will automatically download all of the requires tools (including Python 2) and libraries, set them up for you, build Mudlet, and launch it! If this script exits immediately, please upgrade your PowerShell version first.

Note: Depending on your Internet connection and computer speed, this one-time setup will take 30 minutes or more - so grab a cup of tea or coffee.

Sometimes the output will get stuck and not progress - just press Enter to make it continue. This is a well-known Powershell bug.

During the installation, you'll see the Qt installer window pop-up - this is normal:

The Qt installer might ask you about your data collection preferences - answer as you wish and the automated install will continue:

The installer's final step will be compiling all of the source code, which looks like this:

After it's all done, a Mudlet version ending in "-dev" will launch automatically:

Coding on Mudlet

Open C:\<path to repository>\src\mudlet.pro in Qt Creator, which resides here: C:\Qt\Tools\QtCreator\bin\qtcreator.exe. Then enable Debug and Release builds and hit Configure Project:

Press Ctrl+5 and update project settings. Check how many logical processors are available in your system with the Task Manager:

2 processors are available in this example

And set this amount in Qt Creator:

Hit run:

Click on Compile Output to see progress on compiling:

When it's all ready, the new Mudlet with your changes will launch. You're all done!

Contributing changes

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

Uninstalling

To get rid of everything, uninstall Qt using the C:\Qt\MaintenanceTool.exe and remove the following folders:

C:\Libraries
C:\LuaRocks
C:\MinGW
C:\Python27
C:\Qt
C:\src

Compiling on Windows 7+ (MSYS2 Alternative)

INCOMPLETE, IN PROGRESS

Go to http://www.msys2.org/ to download the 64 (or 32) bit MSYS2 package and follow the installation instructions (Steps 1 to 8 on that page), these instructions assume that "C:\msys64" or "C:\msys32" is used depending on the bitness of the system it is being installed on.

Install the following packages (using "pacman -S packageName"), the ones with a -i686- in the middle are the ones for 32-bit (i686) targets and -x86_64- are for 64-bit one - it is possible to install both for building Mudlet for PCs of both bitnesses!

32-bit target	64-bit target
base-devel	base-devel
git	git
mercurial	mercurial
cvs	cvs
wget	wget
ruby	ruby
zip	zip
p7zip	p7zip
python2	python2
mingw-w64-i686-toolchain	mingw-w64-x86_64-toolchain
mingw-w64-i686-qt-creator	mingw-w64-x86_64-qt-creator
mingw-w64-i686-libzip	mingw-w64-x86_64-libzip
mingw-w64-i686-pugixml	mingw-w64-x86_64-pugixml
mingw-w64-i686-lua51	mingw-w64-x86_64-lua51
mingw-w64-i686-lua51-lpeg	mingw-w64-x86_64-lua51-lpeg
mingw-w64-i686-lua51-lsqlite3	mingw-w64-x86_64-lua51-lsqlite3
mingw-w64-i686-lua51-luarocks	mingw-w64-x86_64-lua51-luarocks
mingw-w64-i686-hunspell	mingw-w64-x86_64-hunspell
mingw-w64-i686-zziplib	mingw-w64-x86_64-zziplib
mingw-w64-i686-boost	mingw-w64-x86_64-boost
mingw-w64-i686-yajl	mingw-w64-x86_64-yajl
mingw-w64-i686-Cairo	mingw-w64-x86_64-Cairo
mingw-w64-i686-clang	mingw-w64-x86_64-clang
mingw-w64-i686-cmake	mingw-w64-x86_64-cmake
mingw-w64-i686-SDL	mingw-w64-x86_64-SDL
unzip	unzip

Note that this will install the MSYS2 builds of the Qt Libraries and Creator IDE - THE ON/OFF-LINE INSTALLER OF THE QT LIBRARIES AND CREATOR VIA DOWNLOADS FROM QT ARE NOT USEFUL IN THIS SETUP!

From the Windows Start menu start a shell appropriate for the target with the bitness to be built for i.e. "MSYS2 Mingw 32-Bit" or "MSYS2 Mingw 64-Bit". This will likely position the current directory to the root directory of the MSYS2 environment, the text about the prompt line (the one with the "$") will contain three different bits of colored text username@computername; one of MSYS2/MINGW32/MINGW depending on the type of shell you currently in use and / representing the root directory (which will actually be the directory MSYS2 was installed to, for example on the author's system this is "C:/msys64"). Change to the home directory in MYSY by entering "cd" on its own with no argument (it will show up as ~ and it would work out to be, for user to be C:/home/user (if both bitnessess are to be built it will be necessary to repeat the following step twice, one for each) install the following luarocks:

rockname
lrexlib-pcre
lua-yajl
luafilesystem
luasql-sqlite3
luautf8
luazip

by using:

MINGW64 user@computer ~
$ luarocks install rockname

Currently there seems to be a bug (reported upstream as msys2/MINGW-packages Issue #5928) where the 32-Bit Luarocks version messes up a couple of configuration files on installation and luarocks is unable to work without editing them:

Edit /mingw32/share/lua/5.1/luarocks/site_config.lua by changing the six lines with paths (in [[...]]) that start with /mingw32 to prepend the drive and path of the MSYS2 install {e.g. C:/msys64 or C:/msys32 if following the previous directions), e.g. the line:

 site_config.LUAROCKS_PREFIX=[[/mingw32]]

on 64-bit systems should be changed to:

 site_config.LUAROCKS_PREFIX=[[C:/msys64/mingw32]]

Also change the line:

 site_config.LUAROCKS_ROCKS_SUBDIR=[[/lib/luarocks/rocks]]

to:

 site_config.LUAROCKS_ROCKS_SUBDIR=[[/lib/luarocks/rocks-5.1]]

Edit /mingw32/etc/luarocks/config-5.1.lua in one place where the path is wrong in the same manner as above, so change:

 { name = [[system]], root = [[/mingw32]] }

to (on 64-bit systems):

 { name = [[system]], root = [[C:/msys64/mingw32]] }]

Now create somewhere to work on the Mudlet source, assuming that other software coding with other pieces of software will be done, create a sub-directory in the home directory, and then make one just for Mudlet under that:

MINGW64 user@computer ~
$ mkdir ./src

MINGW64 user@computer ~
$ mkdir ./src/mudlet

Change to that directory and get the source code:

MINGW64 user@computer ~
$ cd ./src/mudlet

MINGW64 user@computer ~/src/mudlet
$ git clone git://github.com/Mudlet/Mudlet.git .

If you are planning to contribute to the Mudlet code you will want to visit Github and create your own GitHub repository, you can then push commits (changes to the code) to there and raise a Pull Request for a Mudlet Maker to drag the changes over to the above repository. You will want to add your repository and perhaps those of some other contributors so you can track what they are doing and see/try/experiment with their PRs before they get merged. Therefore you will want to add some other repositories into the mix. The names you use to identify those other repositories will show up in any utility that works with the repository you have just created in the above "clone" operation and can be anything you like but it makes sense to have clear names. So to add "myName", and those of the leading active contributors to the Mudlet codebase you will use:

MINGW64 user@computer ~/src/mudlet
$ git remote add Mine https://github.com/myName/Mudlet.git

MINGW64 user@computer ~/src/mudlet
$ git remote add Vadim https://github.com/vadi2/Mudlet.git 

MINGW64 user@computer ~/src/mudlet
$ git remote add SlySven https://github.com/SlySven/Mudlet.git

MINGW64 user@computer ~/src/mudlet
$ git remote add Kebap https://github.com/Kebap/Mudlet.git

Now obtain all the versions of the code with:

MINGW64 user@computer ~/src/mudlet
$ git fetch --all

This will produce a lot of lines of output the first time and it might take a little while on a slow connection...

{Section missing - it turns out that the default GUI git tools that the author of this section would normally use: "gitk" and "git gui" have some problems in the versions currently supplied from the MSYS2 system - and it was necessary to import them from the set that the Git4Win have patched - see https://github.com/git-for-windows/git/wiki/Install-inside-MSYS2-proper }

Checkout a branch and then work on it with Qt Creator:

MINGW64 user@computer ~/src/mudlet
$ qtcreator &

Load in the mudlet.pro qmake project file in the src subdirectory (e.g. for this example: c:/msys64/home/user/src/mudlet/src/mudlet.pro) and get hacking...

{At present there are some deficits in the qmake project file that mean that some libraries and include files will not be found - the MINGW_BASE_DIR qmake variable will need to be adjusted from C:\\Qt\\Tools\\mingw530_32 to C:/msys64/mingw64, it needs to be pre-pended to some more paths in the project file and TLuaInterpreter class C++ code that loads both the Mudlet provided lua modules and system ones needs improvement to handle Qt Shadow builds (that place the built executable a further sub-directory down when the qmake CONFIG variable contains both debug_and_release and debug_and_release_target as it does on Windows)...}

Setting up IDEs

CLion

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.
    
    Could not find a package configuration file provided by "Qt5Core" with any
    of the following names:
    
    Qt5CoreConfig.cmake
    qt5core-config.cmake
    
    Add the installation prefix of "Qt5Core" to CMAKE_PREFIX_PATH or set
    "Qt5Core_DIR" to a directory containing one of the above files.  If
    "Qt5Core" provides a separate development package or SDK, be sure it has
    been installed.

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

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).