Difference between revisions of "Compiling Mudlet"

From Mudlet
Jump to navigation Jump to search
(→‎Lua & Luarocks: added bundled rocks)
(294 intermediate revisions by 23 users not shown)
Line 1: Line 1:
 
{{TOC right}}
 
{{TOC right}}
  
= Key contributing information =
+
If you just want to use Mudlet, you can skip these steps, and use one of the already ready (pre-compiled) installers [https://www.mudlet.org/download ready for download].
 +
 
 +
Otherwise, hop in for new adventure!
 +
 
 +
[[File:Easy Mudlet code understanding.png|400px|none]]
 +
 
 +
= Compiling =
 +
 
 +
== Compiling on Ubuntu ==
 +
 
 +
These instructions will get you setup compiling on Ubuntu. Need a hand? Join us on Mudlet's [https://discord.gg/BwgJpMj Discord] or [http://forums.mudlet.org/viewforum.php?f=7 forums].
 +
 
 +
===Ubuntu 22.04===
 +
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 \
 +
  libpcre3-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 \
 +
  libglu1-mesa-dev mesa-common-dev libglib2.0-dev libgstreamer1.0-dev libqt5opengl5-dev \
 +
  qtmultimedia5-dev qttools5-dev qt5keychain-dev libsecret-1-dev \
 +
  libqt5texttospeech5-dev qtspeech5-flite-plugin qtspeech5-speechd-plugin \
 +
  qtbase5-dev qtchooser qt5-qmake qtbase5-dev-tools qtmultimedia5-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-pcre
 +
 
 +
'''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 qmake, the first is for general use, the second is for developers:
 +
  qmake ../src/mudlet.pro
 +
'''*OR*'''
 +
  qmake CONFIG+=debug ../src/mudlet.pro
  
Clang format is used to automatically format code submissions using the [https://github.com/Mudlet/Mudlet/blob/development/src/.clang-format src/.clang-format] style. [http://doc.qt.io/qtcreator/creator-beautifier.html See here] how to enable clang-format with Qt Creator - and make sure to specify the 'File' option for the configuration style.
+
'''Now finish compiling:'''
 +
  make -j `nproc`
  
Branches:
+
4. '''installing compiled code'''
  
'''development''' is the development branch where new features can go.
+
After successful code compilation, next few commands will install resulting binaries, desktop file for menus and appropriate icon.
 +
  sudo make install
 +
  sudo cp ../mudlet.png /usr/share/pixmaps
 +
  sudo cp ../mudlet.desktop /usr/share/applications
  
Workflow:
+
5. '''optional additional software'''
  
Fork and submit a PR with your changes ([https://guides.github.com/activities/forking/ Github tutorial]).
+
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.
  
== Travis Integration ==
+
Many of Qt widget styles and color schemes are available in official repositories, and will make Mudlet better.
  
Mudlet is hosted on [https://github.com/Mudlet/Mudlet Github] and uses [https://travis-ci.org/Mudlet/Mudlet Travis] for continuous integration by building on a Ubuntu 14.04 LTS Linux and a macOS 10.11 platforms. This means that every push to the Git repository is test compiled on both Ubuntu and Mac OSX but '''not''' Microsoft Windows (yet).
+
6. '''Mudlet on Wayland'''
  
Travis integration is defined in a [https://github.com/Mudlet/Mudlet/blob/development/.travis.yml .travis.yml] file and in our case, it references shell scripts in the [https://github.com/Mudlet/Mudlet/tree/development/CI CI] directory, which handle things like installing dependencies and building mudlet.
+
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)
  
{{note}} Travis builds do not currently package mudlet, so not everything is automated.
+
7. '''uninstallation'''
  
= Compiling =
+
You can reverse the process described in this guide with following command:
  
== Compiling on Ubuntu ==
+
  sudo rm -fr /usr/bin/mudlet /usr/share/mudlet /usr/share/applications/mudlet.desktop /usr/share/pixmaps/mudlet.png
  
These instructions will get you setup compiling on Ubuntu. Need a hand? [https://discord.gg/BwgJpMj Discord], [https://gitter.im/Mudlet/Mudlet Join us on Gitter] (need a Github account), or [http://forums.mudlet.org/viewforum.php?f=7 forums].
+
===Other Ubuntu Versions===
  
'''1. Ubuntu 16.04 setup'''
+
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 [https://launchpad.net/~beineri 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.
  
If you're on Ubuntu 16.04 (Xenial Xerus), install the following. If you're on a newer Ubuntu, skip this step and go to ''2. Install dependencies''.
+
== Compiling on Chrome OS ==
  
  sudo add-apt-repository ppa:beineri/opt-qt58-xenial
+
These instructions will get you setup compiling on Chrome OS. Need a hand? Join us on Mudlet's [https://discord.gg/BwgJpMj Discord] or [http://forums.mudlet.org/viewforum.php?f=7 forums].
  sudo apt update
 
  sudo apt install qt58-meta-full qt58creator
 
  
'''2. Install dependencies'''
+
'''1. Install dependencies'''
  
  sudo apt install git build-essential qt5-default qtmultimedia5-dev qttools5-dev \
+
  sudo apt install git build-essential \
   libhunspell-dev lua5.1 liblua5.1-0-dev libpcre3-dev libboost-dev zlib1g-dev cmake \
+
   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 \
+
   libhunspell-dev lua-rex-pcre2 lua-sql-sqlite3 lua-filesystem lua-zip libyajl-dev \
   libzip-dev gstreamer0.10-fluendo-mp3 libgstreamer0.10-0 libglu1-mesa-dev \
+
   libzip-dev libglu1-mesa-dev ccache libpugixml-dev mesa-common-dev qtcreator \
   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
 +
sudo luarocks install luautf8
 +
sudo luarocks install lua-yajl
  
 
'''3. Get Mudlet source'''
 
'''3. Get Mudlet source'''
Line 49: Line 110:
 
'''4. Create a build directory'''
 
'''4. Create a build directory'''
  
  cd mudlet
+
cd mudlet
  mkdir build
+
mkdir build && cd build
  cd build
 
 
 
'''5. Run the following commands, depending on which build system you want to use '''
 
  
'''EITHER:'''
+
'''5. Run the following command '''
  
  cmake ..
+
  cmake .. -G Ninja
  
'''OR:'''
+
'''then:'''
  
  qmake CONFIG+=debug ../src/src.pro
+
  ninja -j 2
 
 
'''THEN:'''
 
 
 
make -j `nproc`
 
  
 
'''5. Start the application you have just compiled - enjoy'''
 
'''5. Start the application you have just compiled - enjoy'''
  
  ./mudlet
+
  src/mudlet
 
 
Optionally - install [https://apps.ubuntu.com/cat/applications/ccache/ ccache] and [http://manpages.ubuntu.com/manpages/trusty/man1/ccache.1.html#contenttoc3 enable it] for quicker compilation - it especially helps when you're switching between Git branches.
 
  
 
== Compiling on macOS ==
 
== Compiling on macOS ==
  
These instructions will get you setup compiling on macOS. Need a hand? [https://gitter.im/Mudlet/Mudlet Join us on Gitter] (need a Github account), [https://discord.gg/BwgJpMj Discord server] or [http://forums.mudlet.org/viewforum.php?f=7 forums] otherwise.
+
These instructions will get you setup compiling on macOS. Need a hand? Join us on Mudlet's [https://discord.gg/BwgJpMj Discord server] or [http://forums.mudlet.org/viewforum.php?f=7 forums] otherwise.
  
  
Line 82: Line 134:
 
Install [https://itunes.apple.com/us/app/xcode/id497799835?ls=1&mt=12 XCode], command line tools for XCode, and [http://brew.sh HomeBrew].
 
Install [https://itunes.apple.com/us/app/xcode/id497799835?ls=1&mt=12 XCode], command line tools for XCode, and [http://brew.sh HomeBrew].
  
Once homebrew is installed, do:
+
Once everything is installed, do:
  
 
   brew doctor
 
   brew doctor
Line 89: Line 141:
  
 
'''2. Get Mudlet source'''
 
'''2. Get Mudlet source'''
   git clone --recursive https://github.com/Mudlet/Mudlet.git mudlet
+
   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}'''
+
'''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
+
   cd Mudlet && 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''
+
'''3. Setup your environment'''
   export PATH="/usr/local/opt/qt5/bin:$PATH"
+
   ./CI/travis.osx.before_install.sh
  export LDFLAGS=" -L/usr/local/opt/qt5/lib ${LDFLAGS}"
+
   ./CI/travis.osx.install.sh
  export CPPFLAGS=" -I/usr/local/opt/qt5/include ${CPPFLAGS}"
 
  CI/travis.osx.before_install.sh
 
   CI/travis.osx.install.sh
 
  
'''4. Go to the mudlet build folder'''
+
  luarocks config lua_version 5.1
   cd build
+
  eval `luarocks path --lua-version=5.1`
 +
For the following, one may have to add <code>''_DIR="/opt/homebrew/"''</code> such as <code>PCRE_DIR="/opt/homebrew/"</code> or <code>ZIP_DIR="/opt/homebrew/"</code> if the installation could not find header files.
 +
  luarocks --lua-version=5.1 --lua-dir=`brew --prefix [email protected]` install lrexlib-pcre PCRE_DIR=`brew --prefix pcre`
 +
   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`
  
'''5. Run the following commands, depending on which build system you want to use (qmake IS recommended for Linux and Mac platforms)
+
  brew install boost
 +
OK to answer yes to delete files if prompted for the <code>rm</code> command above.
  
'''EITHER:'''
+
'''4. Run the following commands'''
  
   qmake ../src/src.pro
+
   cd build
 +
  cmake ../../Mudlet -DCMAKE_PREFIX_PATH=`brew --prefix qt5`
 +
  make -j `sysctl -n hw.ncpu`
  
'''OR:'''
 
  
   cmake ..
+
'''5. Enjoy'''
 +
    
 +
The mudlet.app is now available in <code>src/</code> for launching:
  
'''THEN:'''
+
  open src/Mudlet.app
  
  make -j `sysctl -n hw.ncpu`
+
'''6. Qt Creator setup'''
 +
 
 +
No Lua installation is found, despite it existing on your system? Launch Qt Creator by doing <code>open /Applications/Qt Creator.app</code> (location depends on how you installed it).
  
 +
Receiving a <code>No rule to make target ... libQt5UiTools_debug.a</code> error? A workaround is to [https://bugreports.qt.io/browse/QTBUG-81251?focusedCommentId=538705&page=com.atlassian.jira.plugin.system.issuetabpanels%3Acomment-tabpanel#comment-538705 symlink a file].
  
'''6. Enjoy'''
+
Mudlet in Qt Creator is not launching due to <code>dyld: Symbol not found: __cg_jpeg_resync_to_restart</code>? See [https://stackoverflow.com/a/44851430/72944 here] for a workaround.
  
The Mudlet.app is now available in Finder for launching.
+
====== 7. Troubleshooting ======
 +
If you exhaust all efforts to get YAJL to compile on your local system with homebrew, [https://github.com/lloyd/yajl/ clone from the YAJL repository] then  <code>./configure && sudo make install</code>.
  
== Compiling on Debian 'Sid' ==
+
== Compiling on Debian ==
  
 
'''1. Install required packages from main repo.'''
 
'''1. Install required packages from main repo.'''
 
 
  $ sudo apt-get install build-essential liblua5.1-dev zlib1g-dev libhunspell-dev libpcre3-dev \
+
  sudo apt-get install build-essential git liblua5.1-0-dev zlib1g-dev libhunspell-dev libpcre3-dev \
  libzip-dev libboost-dev libyajl-dev libpulse-dev lua-rex-pcre lua-filesystem lua-zip \
+
libzip-dev libboost-dev libyajl-dev libpulse-dev libsecret-1-dev lua-rex-pcre2 lua-filesystem lua-zip \
  lua-sql-sqlite3 qt5-default qtmultimedia5-dev qttools5-dev
+
lua-sql-sqlite3 qt5-qmake qtmultimedia5-dev qttools5-dev luarocks ccache libpugixml-dev
  
 +
sudo luarocks install luautf8
 +
sudo luarocks install lua-yajl
 +
sudo luarocks install lrexlib-pcre
  
 
'''2. Grab latest Mudlet source.'''
 
'''2. Grab latest Mudlet source.'''
 
 
  $ cd ~ && mkdir projects && cd projects && git clone --recursive https://github.com/Mudlet/Mudlet.git mudlet
+
  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
 +
 
 +
'''4. (Optional) Discord library'''
 +
 
 +
If you get the following error;
 +
 
 +
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:/home/user/mudlet-dev/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 [https://discord.gg/BwgJpMj Discord] or [http://forums.mudlet.org/viewforum.php?f=7 forums].
  
 +
''' 1.a Install apt dependencies '''
  
'''3. Build Mudlet.'''
+
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-pcre2 lua-filesystem lua-zip \
 +
  lua-sql-sqlite3 qt5-assistant qtmultimedia5-dev qttools5-dev luarocks ccache libpugixml-dev cmake
 +
 
 +
 
 +
[[File:Apt-get-install-y-n.png|center|thumb|installing apt dependencies]]
 +
 
 +
''' 1.b Install luarocks dependencies '''
 +
 
 +
sudo luarocks install luautf8
 +
sudo luarocks install lrexlib-pcre
 +
sudo luarocks install lua-yajl YAJL_LIBDIR=`find /usr -name "libyajl.so" -printf '%h\n'` YAJL_INCDIR=/usr/include
 +
 
 +
 
 +
[[File:After-luarocks-dependencies.png|center|thumb|after luarocks dependencies]]
 +
 
 +
''' 2. Get Mudlet source '''
 +
 
 +
mkdir ~/source && cd ~/source
 +
git clone --recursive -b development https://github.com/Mudlet/Mudlet.git
 +
 
 +
[[File:After-get-mudlet-source.png|center|thumb|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
 +
 
 +
[[File:After-qmake.png|center|thumb|After qmake]]
 +
 
 +
''' THEN: '''
 +
:For the fastest compile time while still being able to use the system at all (~35min on a RPi4 with 4GB of ram)
 +
make -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 some of those tasks'':
 +
make
 +
 
 +
[[File:Success.png|center|thumb|Success!]]
 +
 
 +
''' 4. Install the application you have just compiled '''
 +
 
 +
sudo make install
 +
 
 +
[[File:Installed.png|center|thumb|Installed now]]
 +
 
 +
''' 5. Enjoy! '''
 +
 
 +
# mudlet is in the path, can just run it
 +
mudlet
 +
 
 +
== Compiling on Arch Linux ==
 +
 
 +
===AUR Install and Compile===
 +
Mudlet is available in the [https://aur.archlinux.org Arch User Repository].
 +
(If the AUR has become unmaintained/orphaned, then skip below to [https://wiki.mudlet.org/w/Compiling_Mudlet#Manual_Install_and_Compile 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 [https://wiki.archlinux.org/index.php/Arch_User_Repository 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 [https://discord.gg/BwgJpMj Discord] or [http://forums.mudlet.org/viewforum.php?f=7 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 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
 +
 
 +
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-pcre
 +
  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 qmake, the first is for general use, the second is for developers:
 +
  qmake ../src/mudlet.pro
 +
'''*OR*'''
 +
  qmake CONFIG+=debug ../src/mudlet.pro
 +
 
 +
'''Now finish compiling:'''
 +
  make -j `nproc`
 +
 
 +
'''4. installing compiled code'''
 +
 
 +
After successful code compilation, next few commands will install resulting binaries, desktop file for menus and appropriate icon.
 +
  sudo make 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 groupinstall "Development Tools" "Development Libraries"
 +
 
 +
sudo dnf install compat-lua compat-lua-devel compat-lua-libs hunspell-devel lua5.1-filesystem luarocks pugixml-devel qtkeychain-qt5-devel bitstream-vera-fonts-all ccache qt-creator qt5-qtmultimedia-devel qt5-qtgamepad-devel yajl-devel qtchooser qt5-qttools-devel qt5-qttools-static zziplib-devel pcre-devel libzip-devel sqlite-devel
 +
 
 +
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-pcre
 +
In your user's home directory:
  
  $ cd ~/projects/mudlet/src
+
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.
  
  $ qmake
+
'''2. Obtain the source code'''
 +
  git clone --recursive --branch=development <nowiki>https://github.com/Mudlet/Mudlet.git</nowiki>
 +
mkdir Mudlet/build
 +
cd Mudlet/src
  
$ make
+
'''3. Make necessary compiling instruction adjustments'''
  
$ sudo make install
+
Edit mudlet.pro - find these lines in mudlet.pro and make the following changes:
 +
     linux {
 +
         LIBS += \
 +
             -llua5.1 \
 +
             -lhunspell
 +
         INCLUDEPATH += /usr/include/lua5.1
 +
     }
 +
We're adding a - between lua and 5.1 and adding -1.7 to hunspell under LIBS so that it becomes this:
 +
     linux {
 +
         LIBS += \
 +
             -llua-5.1 \
 +
             -lhunspell-1.7
 +
         INCLUDEPATH += /usr/include/lua5.1
 +
     }
 +
Save and exit.
  
== Compiling on ArchLinux ==
+
'''4. Compile'''
 +
cd ../build
 +
Run this in the build directory:
 +
WITH_FONTS=NO WITH_OWN_QTKEYCHAIN=NO WITH_UPDATER=NO WITH_VARIABLE_SPLASH_SCREEN=NO XDG_DATA_DIRS=/usr/share qmake-qt5 PREFIX=/usr INCLUDEPATH+=/usr/include/lua-5.1 LUA_SEARCH_OUT=lua-5.1 ../src/mudlet.pro
 +
An explanation of the qmake arguments -- we're passing these environment variables to mudlet.pro:
 +
WITH_FONTS=NO WITH_OWN_KEYCHAIN=NO WITH_UPDATER=NO WITH_VARIABLE_SPLASH_SCREEN=NO XDG_DATA_DIRS=/usr/share
 +
Adding build variables to mudlet.pro so that it finds the correct libraries:
 +
PREFIX=/usr INCLUDEPATH+=/usr/include/lua-5.1
 +
And finally adding a build variable to translations/translated/updateqm.pri so that it uses the correct version of the Lua compiler (Fedora also comes with 5.4) to generate translation statistics.
 +
LUA_SEARCH_OUT=lua-5.1
 +
Once complete, run the following:
  
The best way to do this would be to use the PKGBUILD found [https://aur.archlinux.org/cgit/aur.git/plain/PKGBUILD?h=mudlet-dev here]. You'll just download the PKGBUILD into a directory, run
+
If you have time to kill (About 10 minutes on an Apple M1 Max in Fedora):
 +
make
 +
If you want it done as fast as possible(Less than a minute on an Apple M1 Max in Fedora):
 +
make -j `nproc`
 +
Or if you want something in between, make -j `nproc` tells it to use all available processor cores.  If you want to use a specific number instead (ie 2), you can use:
 +
make -j 2
  
  makepkg
+
'''5. Install'''
  sudo pacman -U [name of the generated pkg file]
+
  sudo make install
 +
sudo cp ../mudlet.png /usr/share/pixmaps
 +
  sudo cp ../mudlet.desktop /usr/share/applications
  
and you'll be done. For more info on what this does, visit [https://wiki.archlinux.org/index.php/Arch_User_Repository this site].
+
'''6. Hang onto the cloned git repo '''
 +
If you need to uninstall, you can go back into the /build directory and 'sudo make uninstall'.
  
 
== Compiling on Gentoo ==
 
== Compiling on Gentoo ==
 
An [https://github.com/toaster/gentoo-overlay overlay containing Mudlet is available] for compiling Mudlet on Gentoo.
 
An [https://github.com/toaster/gentoo-overlay overlay containing Mudlet is available] for compiling Mudlet on Gentoo.
  
== Compiling on Windows 10 ==
+
== Compiling on Windows ==
 +
 
 +
These instructions will get you setup compiling on Windows.
  
These instructions will get you setup compiling on Windows. Need a hand? [https://gitter.im/Mudlet/Mudlet Join us on Gitter] (need a Github account), [https://discord.gg/BwgJpMj Discord server] or [http://forums.mudlet.org/viewforum.php?f=7 forums] otherwise.
+
Need a hand? Join us on the Mudlet [https://discord.gg/BwgJpMj Discord server] or [http://forums.mudlet.org/viewforum.php?f=7 forums].
  
'''1.Download & Install the Prerequisites'''
+
'''1. Download Mudlet source code'''
  
Qt:  
+
# Install [https://desktop.github.com/ Github Desktop].
  http://download.qt.io/official_releases/online_installers/qt-unified-windows-x86-online.exe
+
# Clone ([https://help.github.com/desktop/guides/contributing-to-projects/cloning-a-repository-from-github-to-github-desktop/#platform-windows instructions]) Mudlet's [https://github.com/mudlet/mudlet repository] to your local drive.
Run the installer and de-select everything and just select:
+
{{note}} You must use a location on <code>C:\</code> without any spaces in folder names!
  Qt->Qt 5.6->MinGW 4.9.2 (32 bit)
 
  Qt->Qt 5.6->Source components
 
In this tutorial, it is installed in C:\Qt\ (so you will have C:\Qt\5.x)
 
  
7Zip:
+
'''2. Perform a one-time setup'''
  http://www.7-zip.org/a/7z1602-x64.msi
 
  
Notepad++:
+
* Open powershell in the newly cloned folder by typing in <code>powershell</code> in the address bar:
  https://notepad-plus-plus.org/download (at the last check it was at version 7.3)
 
Recommended if you don't have a good source editor installed already (it is release under a GPL License).
 
  
Mingw-builds:
+
[[File:Open powershell in a folder.png|none|thumb|418x418px]]
  https://sourceforge.net/projects/mingwbuilds/files/host-windows/releases/4.8.1/32-bit/threads-posix/dwarf/x32-4.8.1-release-posix-dwarf-rev5.7z/download
 
extract this to C:\mingw32
 
  
Latest msys from:
+
* Run <code>Set-ExecutionPolicy -Scope Process -ExecutionPolicy Unrestricted</code> to enable the setup script to run and press <code>A</code>.
  http://sourceforge.net/projects/mingwbuilds/files/external-binary-packages/
+
* Run <code>./setup-windows-sdk.ps1</code>
put the msys folder in C:\mingw32, so you get C:\mingw32\msys
 
  
CMake:
+
This will automatically download all of the requires tools (including Python 2) and libraries, set them up for you, build Mudlet, and launch it!
  http://www.cmake.org/files/v3.0/cmake-3.0.0-win32-x86.exe
 
  
Python:
+
{{note}} If this script exits immediately, please [https://docs.microsoft.com/en-us/powershell/scripting/windows-powershell/install/installing-windows-powershell?view=powershell-7.1#upgrading-existing-windows-powershell upgrade your PowerShell version] first. You may also need to [https://learn.microsoft.com/de-de/powershell/module/microsoft.powershell.core/about/about_execution_policies?view=powershell-7.4 allow to run scripts from the internet]
  https://www.python.org/ftp/python/2.7.11/python-2.7.11.msi
 
  
 +
{{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.
  
'''2.Download libraries in MSYS'''
+
'''3. Watch the magic happen'''
  
Open MSYS (click msys.bat in the C:\mingw32\msys folder), where you'll be in a home directory. Copy the lines below and right-click on the terminal to paste them:
+
Here is a video recording of the setup unfolding, compiling, etc. for your comparsion:
  
mkdir src
+
[[File:Start-of-installation.gif|frame|none|Sometimes the output will get stuck and not progress - just press Enter to make it continue. This is a well-known [https://serverfault.com/questions/204150/sometimes-powershell-stops-sending-output-until-i-press-enter-why Powershell bug.]]]
cd src
 
wget --no-check-certificate --output-document hunspell-1.4.1.tar.gz https://github.com/hunspell/hunspell/archive/v1.4.1.tar.gz
 
wget http://www.lua.org/ftp/lua-5.1.5.tar.gz
 
wget --no-check-certificate https://sourceforge.net/projects/pcre/files/pcre/8.38/pcre-8.38.tar.gz/download
 
wget http://zlib.net/zlib-1.2.11.tar.gz
 
wget http://www.sqlite.org/2013/sqlite-autoconf-3071700.tar.gz
 
wget --no-check-certificate https://launchpad.net/ubuntu/+archive/primary/+files/libzip_0.11.2.orig.tar.gz
 
wget --no-check-certificate --output-document yajl-2.0.1.tar.gz https://github.com/lloyd/yajl/tarball/2.0.1
 
wget --no-check-certificate https://sourceforge.net/projects/zziplib/files/zziplib13/0.13.62/zziplib-0.13.62.tar.bz2/download
 
wget --no-check-certificate https://indy.fulgan.com/SSL/openssl-1.0.2k-i386-win32.zip
 
  
A folder will get created in C:\mingw32\msys\home\your_name\src with all the files.
+
During the installation, you'll see the Qt installer window pop-up - this is normal:
  
Extract all libraries with:
+
[[File:Qt-installer.gif|thumb|none]]
  
for a in `ls -1 *.tar.gz`; do tar -zxvf $a; done
+
The Qt installer might ask you about your data collection preferences - answer as you wish and the automated install will continue:
for a in `ls -1 *.tar.bz2`; do tar xvfj $a; done
 
  /c/Program\ Files/7-Zip/7z -oopenssl-1.0.2k e openssl-1.0.2k-i386-win32.zip
 
  
Boost:
+
[[File:Qt-installer-data-collection.png|thumb|none]]
wget --no-check-certificate https://sourceforge.net/projects/boost/files/boost/1.60.0/boost_1_60_0.tar.gz/download
 
/c/Program\ Files/7-Zip/7z e boost_1_60_0.tar.gz && /c/Program\ Files/7-Zip/7z x boost_1_60_0.tar
 
cp -r boost_1_60_0/boost /c/mingw32/include
 
  
'''3.Compiling libraries'''
+
The installer's final step will be compiling all of the source code, which looks like this:
  
'''Environment Settings'''
+
[[File:Compiling-step.gif|thumb|none]]
  
You want control over what compilers are being using so prefix your Path with (in [http://superuser.com/questions/949560/how-do-i-set-system-environment-variables-in-windows-10 system environment variables]):
+
After it's all done, a Mudlet version ending in "-dev" will launch automatically:
  
 +
[[File:Mudlet-launching.gif|frame|none]]
 +
 +
If something didn't work right, you can check out the verbose log that is available at <code>C:\src\verbose_output.log</code>.
 +
 +
=== Coding on Mudlet ===
 +
 +
Open <code>C:\<path to repository>\src\mudlet.pro</code> in Qt Creator, which resides here: <code>C:\Qt\Tools\QtCreator\bin\qtcreator.exe</code>. Then enable Debug and Release builds and hit ''Configure Project'':
 +
 +
[[File:Selection_173.png|frame|none]]
 +
 +
Press <code>Ctrl+5</code> and update project settings. Check how many logical processors are available in your system with the Task Manager:
 +
 +
[[File:Task-manager.png|thumb|none|2 processors are available in this example]]
 +
 +
And set this amount in Qt Creator:
 +
 +
[[File:Change Qt Creator to use many cores.gif|frame|none]]
 +
 +
Hit run:
 +
 +
[[File:Selection 176.png|frame|none]]
 +
 +
Click on '''Compile Output''' to see progress on compiling:
 +
 +
[[File:Selection 177.png|frame|none]]
 +
 +
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 [https://help.github.com/desktop/guides/contributing-to-projects/creating-a-pull-request/#platform-windows pull request]. Thanks for improving open-source!
 +
 +
=== Uninstalling ===
 +
To get rid of everything, remove the following folders:
 +
 +
C:\Libraries
 +
C:\LuaRocks
 +
C:\MinGW
 
  C:\Python27
 
  C:\Python27
  C:\mingw32\bin
+
  C:\Qt
  C:\Program Files (x86)\CMake\bin
+
  C:\src
C:\Qt\5.6\mingw49_32\bin
+
 
 +
== Compiling on Github Codespaces ==
 +
 
 +
[https://github.com/features/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".
 +
 
 +
[[File:New codespace.png|alt=New codespace screenshot|frameless]]
 +
 
 +
'''2. Wait for it to load'''
 +
 
 +
This will take a while (~5min) so grab a tea:
 +
 
 +
[[File:Building Visual Studio Codespace.png|frameless]]
 +
 
 +
'''3. Connect to the environment'''
 +
 
 +
Go to the <code>Ports</code> section at the bottom and change the Port Privacy of the Open Mudlet port to Public:
 +
 
 +
[[File:Port privacy in Github Codespaces.png|900x900px]]
 +
 
 +
 
 +
Then connect to your online Linux desktop with <code>mudlet</code> as the password by clicking on the web icon.
 +
 
 +
[[File:Connect to remote machine.png|frameless]]
 +
 
 +
 
 +
In case it can't connect, make sure the port privacy is set to <code>Public</code>. 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 😉
 +
 
 +
[[File:Github_codespaces_desktop.png|alt=|frameless|400x400px]]
 +
 
 +
'''4. Build Mudlet'''
 +
 
 +
In Codespaces, hit <code>F7</code> and select <code>Let CMake guess...</code>
 +
 
 +
[[File:CMake configuration.png|none]]
 +
 
 +
It will then start building Mudlet automatically. Using the [https://docs.github.com/en/free-pro-team@latest/github/developing-online-with-codespaces/about-billing-for-codespaces 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.
 +
 
 +
[[File:Building Mudlet in codespaces.png|none]]
 +
 
 +
'''5. Run Mudlet'''
 +
 
 +
[[File:Launch Mudlet.png|none]]
 +
 
 +
Hit the little play button at the bottom of the screen, and Mudlet will now launch in the remote connection tab. Not working? [https://discord.gg/kuYvMQ9 We can help]. Otherwise, enjoy!
 +
 
 +
[[File:Mudlet running remotely.png ‎|500px]]
 +
 
 +
Note: When the codespace is unused for a while, it will disconnect. It'll never disconnect while you're actively using it. See [https://github.com/microsoft/vscode-dev-containers/issues/588 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 [https://docs.docker.com/get-docker/ docker] and [https://docs.docker.com/compose/install/ docker-compose].
 +
 
 +
Clone the development branch
 +
 
 +
  git clone --recursive -b development https://github.com/Mudlet/Mudlet.git
 +
  cd Mudlet/docker
  
Be sure to restart msys.bat after setting the above to pick up the new values.
+
Make a local copy of the .env.template file:
  
'''MSYS Compilations'''
+
  cp .env.template .env
  
All of the following will be completed inside the msys command prompt.
+
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.
  
cd into each respective directory:
+
To run Qt-Creator and develop Mudlet, run <code>docker-compose up dev</code>.
  
'''Hunspell''':
+
To run Mudlet, run <code>docker-compose up mudlet</code>. Note: At the moment, the mudlet build will not persist settings past container rebuilds.
  ./configure --prefix=/c/mingw32 && make -j 2 && make install
 
  
'''YAJL''':
+
== Compiling on Windows 7+ (MSYS2 Alternative)==
First, remove all the windows specific compiler settings with:
 
powershell -Command "(Get-Content CMakeLists.txt -Raw) -replace '\/W4' -replace '(?<=SET\(linkFlags)[^\)]+' -replace '\/wd4996 \/wd4255 \/wd4130 \/wd4100 \/wd4711' -replace '(?<=SET\(CMAKE_C_FLAGS_DEBUG .)\/D \DEBUG \/Od \/Z7', '-g' -replace '(?<=SET\(CMAKE_C_FLAGS_RELEASE .)\/D NDEBUG \/O2', '-O2' | Out-File -encoding ASCII CMakeLists.txt"
 
  
Then compile:
+
''INCOMPLETE, IN PROGRESS''
 +
 
 +
Go to http://www.msys2.org/ to download the 64 bit MSYS2 installer (as of 2020/05/24 32 bit hosts - for '''compiling''' software, but ''not'' for using code built with it have been deprecated, the last installer for that 32-bit systems is held at: http://repo.msys2.org/distrib/i686/msys2-i686-20200517.exe) 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 the ones for 64-bit targets - it is possible to install both for building Mudlet for target PCs of both bitnesses on a 64-bit host, it is not clear whether the reverse is true with a 32-bit host. These will pull in a number of other required packages as well (the ''--needed'' option prevents the re-installation of packages that have already been installed by MSYS2/Mingw-w64's own setup/installation process) - as some of the packages, e.g. ''base-devel'' are actually ''groups'' you will be requested to select which members of that group are actually required, it is easiest to just go with the default which is to install ALL of the packages in that group!
 +
 
 +
: For 32-Bit Mudlet builds:
 +
:<syntaxhighlight lang="shell">
 +
MSYS user@computer ~
 +
$ pacman -S --needed base-devel git mercurial cvs wget ruby zip p7zip python mingw-w64-i686-toolchain mingw-w64-i686-qt-creator mingw-w64-i686-qt5-multimedia mingw-w64-i686-libzip mingw-w64-i686-pugixml mingw-w64-i686-lua51 mingw-w64-i686-lua51-lpeg mingw-w64-i686-lua51-lsqlite3 mingw-w64-i686-hunspell mingw-w64-i686-boost mingw-w64-i686-yajl mingw-w64-i686-clang mingw-w64-i686-cmake mingw-w64-i686-SDL unzip
 +
</syntaxhighlight>
 +
 
 +
: For 64-Bit Mudlet builds:
 +
:<syntaxhighlight lang="shell">
 +
MSYS user@computer ~
 +
$ pacman -S --needed base-devel git mercurial cvs wget ruby zip p7zip python mingw-w64-x86_64-toolchain mingw-w64-x86_64-qt-creator mingw-w64-x86_64-qt5-multimedia mingw-w64-x86_64-libzip mingw-w64-x86_64-pugixml mingw-w64-x86_64-lua51 mingw-w64-x86_64-lua51-lpeg mingw-w64-x86_64-lua51-lsqlite3 mingw-w64-x86_64-hunspell mingw-w64-x86_64-boost mingw-w64-x86_64-yajl mingw-w64-x86_64-clang mingw-w64-x86_64-cmake mingw-w64-x86_64-SDL unzip
 +
</syntaxhighlight>
 +
 
 +
::The ''*-zziplib'' libraries are used by the ''luazip'' luarock {from the Kepler project} but Mudlet will work perfectly well with the alternative ''lua-zip'' {from the brimworks GitHub repository - which also provides the ''lua-yajl'' rock} which does not require this library - although it is possible that it might still be pulled into the system as a dependency of another MSYS2 package.
 +
 
 +
: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!''
 +
 
 +
:{| class="wikitable"
 +
|-
 +
|'''Attention - Luarocks packages problem'''
 +
|-
 +
| Recently the Luarocks project attempted to adopt the MSYS2/Mingw-w64 platform as one it would supported natively and the MSYS2/Mingw-w64 project went and upgraded its luarocks packages to make use of the changes and also on-board other improvements (and the version number increased from ''2.4.4-2'' to ''3.5.0-1'') unfortunately this completely broke them and although the issue has been reported ([https://github.com/msys2/MINGW-packages/issues/9037 MSYS2 Issue 9037]) a fix has not yet materialised. The only way to work around this in the meantime is to download the older package (with '''wget''') and install it manually (with '''pacman -U):
 +
|-
 +
|For 32-Bit Mudlet builds:
 +
:<syntaxhighlight lang="shell">
 +
MSYS user@computer ~
 +
$ wget https://repo.msys2.org/mingw/mingw32/mingw-w64-i686-lua51-luarocks-2.4.4-2-any.pkg.tar.zst
 +
--2021-07-07 22:19:09--  https://repo.msys2.org/mingw/mingw32/mingw-w64-i686-lua51-luarocks-2.4.4-2-any.pkg.tar.zst
 +
Resolving repo.msys2.org (repo.msys2.org)... 178.63.98.68
 +
Connecting to repo.msys2.org (repo.msys2.org)|178.63.98.68|:443... connected.
 +
HTTP request sent, awaiting response... 200 OK
 +
Length: 97905 (96K) [application/octet-stream]
 +
Saving to: ‘mingw-w64-i686-lua51-luarocks-2.4.4-2-any.pkg.tar.zst’
 +
 
 +
mingw-w64-i686-lua51-luarocks-2.4.4-2- 100%[===========================================================================>]  95.61K  --.-KB/s    in 0.07s
 +
 
 +
2021-07-07 22:19:10 (1.43 MB/s) - ‘mingw-w64-i686-lua51-luarocks-2.4.4-2-any.pkg.tar.zst’ saved [97905/97905]
  
mkdir build
 
cd build
 
cmake -G "MSYS Makefiles" ..
 
make
 
cp yajl-2.0.1/lib/* /c/mingw32/lib/
 
cp -R yajl-2.0.1/include/* /c/mingw32/include/
 
  
'''Lua''':
+
MSYS user@computer ~
edit the Makefile, change <tt>INSTALL_TOP= /usr/local</tt> to <tt>INSTALL_TOP= /c/mingw32</tt>
+
$ pacman -U mingw-w64-i686-lua51-luarocks-2.4.4-2-any.pkg.tar.zst
 +
loading packages...
 +
resolving dependencies...
 +
looking for conflicting packages...
  
change <tt>TO_LIB= liblua.a</tt> to <tt>TO_LIB= liblua.a lua51.dll</tt>
+
Packages (1) mingw-w64-i686-lua51-luarocks-2.4.4-2
  
  make mingw
+
Total Installed Size: 0.46 MiB
make install
 
  
'''PCRE''':
+
:: Proceed with installation? [Y/n] y
./configure --prefix=/c/mingw32 && make -j 2 && make install
+
(1/1) checking keys in keyring                                                                [#####################################################] 100%
 +
(1/1) checking package integrity                                                              [#####################################################] 100%
 +
(1/1) loading package files                                                                  [#####################################################] 100%
 +
(1/1) checking for file conflicts                                                            [#####################################################] 100%
 +
(1/1) checking available disk space                                                          [#####################################################] 100%
 +
:: Processing package changes...
 +
(1/1) installing mingw-w64-i686-lua51-luarocks                                                [#####################################################] 100%
  
'''Sqlite''':
+
MSYS user@computer ~
  ./configure --prefix=/c/mingw32 && make -j 2 && make install
+
</syntaxhighlight>
 +
|-
 +
|For 64-Bit Mudlet builds:
 +
:<syntaxhighlight lang="shell">
 +
MSYS user@computer ~
 +
$ wget https://repo.msys2.org/mingw/mingw64/mingw-w64-x86_64-lua51-luarocks-2.4.4-2-any.pkg.tar.zst
 +
--2021-07-07 22:17:32-- https://repo.msys2.org/mingw/mingw64/mingw-w64-x86_64-lua51-luarocks-2.4.4-2-any.pkg.tar.zst
 +
Resolving repo.msys2.org (repo.msys2.org)... 178.63.98.68
 +
Connecting to repo.msys2.org (repo.msys2.org)|178.63.98.68|:443... connected.
 +
HTTP request sent, awaiting response... 200 OK
 +
Length: 97935 (96K) [application/octet-stream]
 +
Saving to: ‘mingw-w64-x86_64-lua51-luarocks-2.4.4-2-any.pkg.tar.zst’
  
'''ZLib''':
+
mingw-w64-x86_64-lua51-luarocks-2.4.4- 100%[===========================================================================>] 95.64K --.-KB/s    in 0.07s
make -f win32/Makefile.gcc
 
export INCLUDE_PATH=/c/mingw32/include/
 
export LIBRARY_PATH=/c/mingw32/lib/
 
export BINARY_PATH=/c/mingw32/bin/
 
  make -f win32/Makefile.gcc install
 
  cp zlib1.dll /c/mingw32/bin
 
cp libz.dll.a /c/mingw32/lib
 
  
'''LibZip''':
+
2021-07-07 22:17:32 (1.28 MB/s) - ‘mingw-w64-x86_64-lua51-luarocks-2.4.4-2-any.pkg.tar.zst’ saved [97935/97935]
./configure --prefix=/c/mingw32 && make -j 2 && make install
 
cp lib/zipconf.h /c/mingw32/include
 
  
'''ZZIPlib''':
 
powershell -Command "(gc configure) -replace 'uname -msr', 'uname -ms' | Out-File -encoding ASCII configure"
 
configure --disable-mmap --prefix=c:/mingw32/ && make -j 2 && make install
 
  
'''3.Downloading Mudlet Sources'''
+
MSYS user@computer ~
 +
$ pacman -U mingw-w64-x86_64-lua51-luarocks-2.4.4-2-any.pkg.tar.zst
 +
loading packages...
 +
resolving dependencies...
 +
looking for conflicting packages...
  
'''Getting Mudlet'''
+
Packages (1) mingw-w64-x86_64-lua51-luarocks-2.4.4-2
  
From within msys:
+
Total Installed Size: 0.46 MiB
  
cd ~/src
+
:: Proceed with installation? [Y/n] y
git clone --recursive https://github.com/Mudlet/Mudlet.git
+
(1/1) checking keys in keyring                                                                [#####################################################] 100%
cd Mudlet/src
+
(1/1) checking package integrity                                                              [#####################################################] 100%
 +
(1/1) loading package files                                                                  [#####################################################] 100%
 +
(1/1) checking for file conflicts                                                            [#####################################################] 100%
 +
(1/1) checking available disk space                                                          [#####################################################] 100%
 +
:: Processing package changes...
 +
(1/1) installing mingw-w64-x86_64-lua51-luarocks                                              [#####################################################] 100%
  
'''Building Mudlet from terminal'''
+
MSYS user@computer ~
 +
</syntaxhighlight>
 +
|}
  
cd ~/src/Mudlet/src
+
::{| class="wikitable"
qmake CONFIG+=debug
+
|-
make -j 2
+
|'''Warning for those planning to build ''both'' 32 and 64 bit versions'''
 +
|-
 +
|If one is planning to build ''both'' bitness binaries an additional step is necessary as, by default, the MSYS2/Mingw-w64 ''luarocks'' setup seems to place any ''.lua'' or ''.dll'' modules it builds/installs on a per user (the so-called ''local'' basis) into the same directories with the same names. This is no good for two reasons:
 +
* It is difficult to work out which bitness a particular module is for and whilst 32-bit modules ''might'' work in a 64-bit environment the reverse is definitely not the case
 +
* It confuses the Luarocks package management systems (as effectively there will be two different luarocks systems operated side-by-side)
  
''NOTE:'' If you install any of the above in a directory other than /c/mingw32, it is necessary to override some of the default include/lib paths that qmake sets up. To do so, you'll need to append a number of INCLUDEPATH and LIBPATH parameters to the qmake call.
+
This can be worked around by:
 +
* Editing the '''.\etc\luarocks\config-5.1.lua''' for each bitness so that the ''rocks_trees'' table entry for the ''user'' key is changed from this in '''both''' files:
 +
:<syntaxhighlight lang="lua">    { name = [[user]], root = home..[[/.luarocks]] },</syntaxhighlight>
 +
to something different for each of them, say, for example, for the the 64-bit one:
 +
:<syntaxhighlight lang="lua">    { name = [[user]], root = home..[[/.luarocks-x64]] },</syntaxhighlight>
 +
* Then by specifying the ''rocktree'' name ('''user''') on the command line when '''installing''' or '''building''' a luarock with the ''--tree user'' argument - note that for some inexplicable reason the ''--local'' argument that '''''should''''' do the same thing does not seem to work for these two actions, it is not clear whether this is a MSYS2/Mingw-w64 specific issue or it goes further upstream to Luarocks in general. Thus, in the next step it will be necessary to change from using:
 +
:<syntaxhighlight lang="shell">
 +
MINGW64 user@computer ~
 +
$ luarocks install --local rockname
 +
</syntaxhighlight>
 +
to, for the example given:
 +
:<syntaxhighlight lang="shell">
 +
MINGW64 user@computer ~
 +
$ luarocks install --tree user rockname
 +
</syntaxhighlight>
 +
where ''user'' is the literal string "user" to match the Lua table key in the rock_trees and not, in this case, a representation of the user-name/account of the person performing the action.
 +
|}
  
Example (installed in an F: drive):
+
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:/msys64/home/user''' or '''c:/msys32/home/user''' (if both bitnessess are to be built it will be necessary to repeat the following step twice, one for each and also observe the steps in the above warning) install the following luarocks:
qmake CONFIG+=debug INCLUDEPATH+=/f/mingw32/include INCLUDEPATH+=/f/mingw32/lib/include LIBPATH+=/f/mingw32/lib LIBPATH+=/f/mingw32/lib/lib LIBPATH+=/f/mingw32/bin
 
  
'''Building Mudlet from QtCreator'''
+
:{| class="wikitable sortable"
 +
|-
 +
! rockname
 +
|-
 +
| lrexlib-pcre
 +
|-
 +
| lua-yajl
 +
|-
 +
| luafilesystem
 +
|-
 +
| luasql-sqlite3
 +
|-
 +
| luautf8
 +
|-
 +
| luazip or lua-zip
 +
|}
 +
by using:
 +
:<syntaxhighlight lang="shell">
 +
MINGW64 user@computer ~
 +
$ luarocks install [--local] rockname
 +
</syntaxhighlight>
 +
The ''--local'' argument is an optional one that causes the luarock and the lua module to be installed on a per-user basis rather than on a system wide one, this may be important if the PC is used by multiple users and more than one of them uses Lua in any form.
  
Open src.pro (within Mudlet2/src) in Qt Creator, disable shadow builds for both release and debug. Change build type to debug (bottom-left) and compile.
+
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:
 +
:<syntaxhighlight lang="shell">
 +
MINGW64 user@computer ~
 +
$ mkdir ./src
  
'''4.Copy Needed DLLs'''
+
MINGW64 user@computer ~
 +
$ mkdir ./src/mudlet
 +
</syntaxhighlight>
  
Copy the following dll's needed to run Mudlet:
+
Change to that directory and get the source code:
''See above note about alternative install paths before copying.''
+
:<syntaxhighlight lang="shell">
 +
MINGW64 user@computer ~
 +
$ cd ./src/mudlet
  
cd debug/
+
MINGW64 user@computer ~/src/mudlet
cp /c/Qt/5.6/mingw49_32/bin/icudt54.dll .
+
$ git clone git://github.com/Mudlet/Mudlet.git .
cp /c/Qt/5.6/mingw49_32/bin/icuin54.dll .
+
</syntaxhighlight>
cp /c/Qt/5.6/mingw49_32/bin/icuuc54.dll .
 
cp /c/Qt/5.6/mingw49_32/bin/Qt5Cored.dll .
 
cp /c/Qt/5.6/mingw49_32/bin/Qt5Guid.dll .
 
cp /c/Qt/5.6/mingw49_32/bin/libEGLd.dll .
 
cp /c/Qt/5.6/mingw49_32/bin/libGLESv2d.dll .
 
cp /c/Qt/5.6/mingw49_32/bin/Qt5Networkd.dll .
 
cp /c/Qt/5.6/mingw49_32/bin/Qt5OpenGLd.dll .
 
cp /c/Qt/5.6/mingw49_32/bin/Qt5Widgetsd.dll .
 
cp /c/Qt/5.6/mingw49_32/bin/Qt5Multimediad.dll .
 
cp /c/Qt/5.6/mingw49_32/bin/libgcc_s_dw2-1.dll .
 
cp /c/Qt/5.6/mingw49_32/bin/libstdc++-6.dll .
 
cp /c/Qt/5.6/mingw49_32/bin/libwinpthread-1.dll .
 
cp /c/mingw32/lib/libyajl.dll .
 
cp $HOME/src/lua-5.1.5/src/lua51.dll .
 
cp $HOME/src/lua-5.1.5/src/lua51.dll /c/mingw32/bin
 
cp $HOME/src/openssl-1.0.2k/libeay32.dll .
 
cp $HOME/src/openssl-1.0.2k/ssleay32.dll .
 
cp /c/mingw32/bin/libzip-2.dll .
 
cp /c/mingw32/bin/libhunspell-1.4-0.dll .
 
cp /c/mingw32/bin/libpcre-1.dll .
 
cp /c/mingw32/bin/libsqlite3-0.dll .
 
cp /c/mingw32/bin/zlib1.dll .
 
cp -r ../mudlet-lua/ .
 
cp ../*.dic .
 
cp -r /c/Qt/5.6/mingw49_32/plugins/audio .
 
cp -r /c/Qt/5.6/mingw49_32/plugins/mediaservice .
 
cp -r /c/Qt/5.6/mingw49_32/plugins/platforms .
 
cp -r /c/Qt/5.6/mingw49_32/plugins/imageformats .
 
  
cd ../release/
+
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 mergedTherefore 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 namesSo to add "myName", and those of the leading active contributors to the Mudlet codebase you will use:
cp /c/Qt/5.6/mingw49_32/bin/icudt54.dll .
+
:<syntaxhighlight lang="shell">
cp /c/Qt/5.6/mingw49_32/bin/icuin54.dll .
+
MINGW64 user@computer ~/src/mudlet
cp /c/Qt/5.6/mingw49_32/bin/icuuc54.dll .
+
$ git remote add Mine https://github.com/myName/Mudlet.git
cp /c/Qt/5.6/mingw49_32/bin/Qt5Core.dll .
 
  cp /c/Qt/5.6/mingw49_32/bin/Qt5Gui.dll .
 
  cp /c/Qt/5.6/mingw49_32/bin/libEGL.dll .
 
cp /c/Qt/5.6/mingw49_32/bin/libGLESv2.dll .
 
cp /c/Qt/5.6/mingw49_32/bin/Qt5Network.dll .
 
cp /c/Qt/5.6/mingw49_32/bin/Qt5OpenGL.dll .
 
cp /c/Qt/5.6/mingw49_32/bin/Qt5Widgets.dll .
 
cp /c/Qt/5.6/mingw49_32/bin/Qt5Multimedia.dll .
 
cp /c/Qt/5.6/mingw49_32/bin/libgcc_s_dw2-1.dll .
 
cp /c/Qt/5.6/mingw49_32/bin/libstdc++-6.dll .
 
cp /c/Qt/5.6/mingw49_32/bin/libwinpthread-1.dll .
 
cp /c/mingw32/lib/libyajl.dll .
 
cp $HOME/src/lua-5.1.5/src/lua51.dll .
 
cp $HOME/src/lua-5.1.5/src/lua51.dll /c/mingw32/bin
 
cp $HOME/src/openssl-1.0.2k/libeay32.dll .
 
cp $HOME/src/openssl-1.0.2k/ssleay32.dll .
 
cp /c/mingw32/bin/libzip-2.dll .
 
cp /c/mingw32/bin/libhunspell-1.4-0.dll .
 
cp /c/mingw32/bin/libpcre-1.dll .
 
cp /c/mingw32/bin/libsqlite3-0.dll .
 
cp /c/mingw32/bin/zlib1.dll .
 
cp -r ../mudlet-lua/ .
 
cp ../*.dic .
 
cp -r /c/Qt/5.6/mingw49_32/plugins/audio .
 
cp -r /c/Qt/5.6/mingw49_32/plugins/mediaservice .
 
cp -r /c/Qt/5.6/mingw49_32/plugins/platforms .
 
cp -r /c/Qt/5.6/mingw49_32/plugins/imageformats .
 
  
 +
MINGW64 user@computer ~/src/mudlet
 +
$ git remote add Vadim https://github.com/vadi2/Mudlet.git
  
'''5.Setting up Lua libraries'''
+
MINGW64 user@computer ~/src/mudlet
 +
$ git remote add SlySven https://github.com/SlySven/Mudlet.git
  
At this point your Lua install will be bare-bones and lacking the Lua libraries Mudlet uses.
+
MINGW64 user@computer ~/src/mudlet
 +
$ git remote add Kebap https://github.com/Kebap/Mudlet.git
 +
</syntaxhighlight>
  
cd ~/src
+
Now obtain ''all'' the versions of the code with:
wget --no-check-certificate http://keplerproject.github.io/luarocks/releases/luarocks-2.4.0-win32.zip
+
:<syntaxhighlight lang="shell">
unzip luarocks-2.4.0-win32.zip
+
MINGW64 user@computer ~/src/mudlet
 +
$ git fetch --all
 +
</syntaxhighlight>
  
Switch to the Windows command line to install luarocks:
+
This will produce a lot of lines of output the first time and it might take a little while on a slow connection...
cd C:\mingw32\msys\home\%USERNAME%\src\luarocks-2.4.0-win32
 
install.bat /P C:\LuaRocks /MW
 
  
Wait for the installation to finish. Then:
+
{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 }
cd \LuaRocks\lua\luarocks
 
powershell -Command "(gc cfg.lua) -replace 'mingw32-gcc', 'gcc' | Out-File -encoding ASCII cfg.lua"
 
cd \LuaRocks
 
luarocks install LuaFileSystem
 
luarocks install LuaSQL-SQLite3 SQLITE_INCDIR="c:\mingw32\include" SQLITE_LIBDIR="c:\mingw32\lib"
 
luarocks install lrexlib-pcre PCRE_LIBDIR="c:\mingw32\lib" PCRE_INCDIR="c:\mingw32\include"
 
  
Back in the msys command line:
+
Some modifications to the qmake/cmake project files are needed and these are now supported in the main ''development'' branch in the upstream {the Mudlet organisation's own GitHub repository} which requires that there is an environmental variable '''WITH_MAIN_BUILD_SYSTEM''' and it is set to the (case-insensitive) value '''NO''':
cd ~/src
+
:<syntaxhighlight lang="shell">
wget --no-check-certificate https://github.com/rjpcomputing/luazip/archive/master.zip
+
MINGW64 user@computer ~/src/mudlet
unzip master
+
$ export WITH_MAIN_BUILD_SYSTEM=NO
cd luazip-master/
+
</syntaxhighlight>
gcc -O2 -c -o src/luazip.o -IC:/mingw32/include/ src/luazip.c
 
gcc -shared -o zip.dll src/luazip.o -Lc:\mingw32\lib -lzzip -lz c:/mingw32/bin/lua51.dll -lm
 
cp zip.dll ~/src/Mudlet/src/debug
 
cp zip.dll ~/src/Mudlet/src/release
 
cp -r /c/mingw32/lib/lua/5.1/* ~/src/Mudlet/src/debug
 
cp -r /c/mingw32/lib/lua/5.1/* ~/src/Mudlet/src/release
 
  
 +
Also the '''MINGW_BASE_DIR''' environmental variable will need to be set to the root directory for the MINGW-W64 installation for the appropriate bitness of the target to be made. For building on a 64-Bit Host {the PC that is ''compiling'' the code} to make a 64-Bit application this will likely be '''C:/msys64/mingw64''' and for a 32-Bit application it will probably be '''C:/msys64/ming32'''.
 +
: E.g. <syntaxhighlight lang="shell">
 +
MINGW64 user@computer ~/src/mudlet
 +
$ export MINGW_BASE_DIR=C:/msys64/mingw64 # To build a 64-Bit Application with a 64-Bit system
 +
</syntaxhighlight>
  
 +
: Or: <syntaxhighlight lang="shell">
 +
MINGW32 user@computer ~/src/mudlet
 +
$ export MINGW_BASE_DIR=C:/msys64/mingw32 # To build a 32-Bit Application with a 64-Bit system
 +
</syntaxhighlight>
  
You're done! You can now launch mudlet by running '''mudlet.exe''' in the debug/ folder, or from command line:
+
Now checkout a branch {ideally, if working on solving a new issue, or adding a feature or resolving a bug, one should create a new branch that is a copy of the current, upstream ''development'' branch} and then work on it with Qt Creator:
 +
:<syntaxhighlight lang="shell">
 +
MINGW64 user@computer ~/src/mudlet
 +
$ qtcreator &
 +
</syntaxhighlight>
  
cd ~/src/Mudlet/src/debug
+
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...
./mudlet.exe
 
  
 
= Setting up IDEs =
 
= Setting up IDEs =
 
== CLion ==
 
== CLion ==
 +
=== Qt not detected ===
 
If you'd like to use CLion and it is giving the following error:
 
If you'd like to use CLion and it is giving the following error:
  
 
  <nowiki>
 
  <nowiki>
By not providing "FindQt5Core.cmake" in CMAKE_MODULE_PATH this project has
+
    By not providing "FindQt5Core.cmake" in CMAKE_MODULE_PATH this project has
asked CMake to find a package configuration file provided by "Qt5Core", but
+
    asked CMake to find a package configuration file provided by "Qt5Core", but
CMake did not find one.
+
    CMake did not find one.
 +
 
 +
    ...
 +
  </nowiki>
 +
 
 +
You can fix this by setting <code>-DCMAKE_PREFIX_PATH=<your Qt + version + compiler location></code>. For example: <code>-DCMAKE_PREFIX_PATH=/media/vadi/SSDer/Programs/Qt/5.14.2/gcc_64/</code> [[File:CLion CMake settings - finidng Qt.png|700px|none]]
 +
 
 +
=== CLion setup on Windows ===
 +
After running <code>setup-windows-sdk.ps1</code> 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.''
 +
 
 +
[[File:Clion Settings - Cmake.png|frameless|700x700px]]
 +
 
 +
 
 +
 
 +
You will need 32 bit version of MinGW. Set it in the <code>Toolset</code> field to:
 +
C:\Qt\Tools\mingw730_32
 +
 
 +
''Directory may be slightly different if MinGW version used will change.''
 +
 
 +
[[File:Toolchain.png|frameless|700x700px]]
 +
 
 +
=== Clang Tidy ===
 +
Ensure that CLion is set to run the project's [https://www.jetbrains.com/help/clion/clang-tidy-checks-support.html#paticularcheck .clang-tidy checks] with the <code>Prefer .clang-tidy files over IDE settings</code> option:
 +
 
 +
[[File:Clang Tidy CLIon.png|700px|none]]
 +
 
 +
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:
 +
 
 +
* [https://clang.llvm.org/docs/LeakSanitizer.html LeakSanitizer] for detecting memory leaks
 +
* [https://clang.llvm.org/docs/AddressSanitizer.html AddressSanitizer] for detecting most issues dealing with memory, such as out of bounds accesses to heap, stack, global and more
 +
* [https://clang.llvm.org/docs/UndefinedBehaviorSanitizer.html 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)
 +
* [https://clang.llvm.org/docs/MemorySanitizer.html MemorySanitizer] for detecting reading uninitialised memory
 +
* [https://clang.llvm.org/docs/ThreadSanitizer.html ThreadSanitizer] for detecting threading issues
 +
 
 +
To use the sanitisers, set the <code>USE_SANITIZER</code> CMake variable to one or several variables (separate by comma): <code>Address</code>, <code>Memory</code>, <code>MemoryWithOrigins</code>, <code>Undefined</code>, <code>Thread</code>, or <code>Leak</code>
 +
 
 +
To use them in CLion, adjust the CMake settings:
 +
 
 +
[[File:Clion_cmake_settings.png|frameless|890x890px]]
 +
 
 +
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 [https://www.jetbrains.com/help/clion/clangformat-as-alternative-formatter.html#clion-support CLion is set to use] the <code>.clang-format</code> formatting style:
 +
 
 +
[[File:Clang-format CLion.png]]
 +
 
 +
This helps keep the look'n'feel of the source code in a consistent manner, even with many people contributing to Mudlet.
 +
 
 +
== Visual Studio Code ==
 +
 
 +
To set the path in Visual Studio Code, open settings, search for <code>cmake environment</code> and set the <code>CMAKE_PREFIX_PATH</code> to your path, such as <code>/media/vadi/SSDer/Programs/Qt/5.14.2/gcc_64/</code>:
 +
 
 +
[[File:CMake path in Visual Studio Code.png|none]]
 +
 
 +
===Clang Tidy===
 +
clang-tidy catches common programming issues, run it by selecting 'Analysis' from the command palette (Ctrl+Shift+P by default):
 +
 
 +
[[File:Clang-tidy in vscode.png|none]]
 +
 
 +
It is also possible [https://devblogs.microsoft.com/cppblog/visual-studio-code-c-december-2021-update-clang-tidy/ 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:
 +
 
 +
* [https://clang.llvm.org/docs/LeakSanitizer.html LeakSanitizer] for detecting memory leaks
 +
* [https://clang.llvm.org/docs/AddressSanitizer.html AddressSanitizer] for detecting most issues dealing with memory, such as out of bounds accesses to heap, stack, global and more
 +
* [https://clang.llvm.org/docs/UndefinedBehaviorSanitizer.html 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)
 +
* [https://clang.llvm.org/docs/MemorySanitizer.html MemorySanitizer] for detecting reading uninitialised memory
 +
* [https://clang.llvm.org/docs/ThreadSanitizer.html ThreadSanitizer] for detecting threading issues
 +
 
 +
To use the sanitisers, set the <code>USE_SANITIZER</code> CMake variable to one or several variables (separate by comma): <code>Address</code>, <code>Memory</code>, <code>MemoryWithOrigins</code>, <code>Undefined</code>, <code>Thread</code>, or <code>Leak</code>
 +
 
 +
To use them in VSCode, set the <code>cmake.configureSettings</code> variable:
 +
 
 +
[[File:Cmake.configureSettings option in vscode.png|frameless|890x890px]]
 +
 
 +
[[File:Choosing which sanitizers in vscode to use.png|frameless|891x891px]]
 +
 
 +
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 [https://clang.llvm.org/extra/clang-tidy/ clang-tidy] and [https://github.com/KDE/clazy clazy] tools help catch any issues early on. See  [https://doc.qt.io/qtcreator/creator-clang-tools.html Qt Creator's instructions] for setting this up - clang-tidy can use the <code>.clang-tidy</code> file that's available at the root of the repository, and for clazy enable <code>level0</code> and <code>level1</code> checks.
 +
 
 +
[[File:Clang tidy configuration.png|frame|none]]
 +
[[File:Clazy configuration.png|frame|none]]
 +
 
 +
===Checking memory leaks & other issues (sanitizers)===
 +
Besides clang-tidy, it's also possible to enable clang sanitizers to double-check for issues:
 +
 
 +
* [https://clang.llvm.org/docs/LeakSanitizer.html LeakSanitizer] for detecting memory leaks
 +
* [https://clang.llvm.org/docs/AddressSanitizer.html AddressSanitizer] for detecting most issues dealing with memory, such as out of bounds accesses to heap, stack, global and more
 +
* [https://clang.llvm.org/docs/UndefinedBehaviorSanitizer.html 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)
 +
* [https://clang.llvm.org/docs/MemorySanitizer.html MemorySanitizer] for detecting reading uninitialised memory
 +
* [https://clang.llvm.org/docs/ThreadSanitizer.html ThreadSanitizer] for detecting threading issues
 +
 
 +
To use the sanitisers, set the <code>USE_SANITIZER</code> CMake variable to one or several variables (separate by comma): <code>Address</code>, <code>Memory</code>, <code>MemoryWithOrigins</code>, <code>Undefined</code>, <code>Thread</code>, or <code>Leak</code>
 +
 
 +
To use them in Qt creator, head to <code>Projects</code> - <code>Build</code>:
 +
 
 +
[[File:Sanitisers in qt creator.png|frameless|890x890px]]
 +
 
 +
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 <code>.clang-format</code> formatting style in the C++ settings. Turn on <code>Format instead of indenting</code> for <code>Ctrl+I</code> to format code, and ensure <code>Override Clang Format configuration file</code> is disabled:
 +
 
 +
[[File:Qt Creator clang format.png]]
 +
 
 +
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: <code>‘LUA_GLOBALSINDEX’ was not declared in this scope</code>.
 +
 
 +
To fix this, pass the path to Lua headers explicitly. For CMake: <code>-DLUA_INCLUDE_DIR=/usr/include/lua5.1</code> (adjust as needed).
 +
 
 +
= Key contributing information =
 +
 
 +
Clang format is used to automatically format code submissions using the [https://github.com/Mudlet/Mudlet/blob/development/src/.clang-format src/.clang-format] style. [http://doc.qt.io/qtcreator/creator-beautifier.html 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 ([https://guides.github.com/activities/forking/ 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
 +
 
 +
= Lua & Luarocks =
 +
 
 +
Mudlet includes a [https://en.wikipedia.org/wiki/Lua_(programming_language) 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 [https://wiki.mudlet.org/w/Manual:Lua_Functions 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 [https://en.wikipedia.org/wiki/C_(programming_language) '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 [https://en.wikipedia.org/wiki/LuaRocks 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 ==
 +
 
 +
# [https://luarocks.org/modules/xavier-wang/luautf8 luautf8] (manual in README)
 +
# [https://luarocks.org/modules/martin-eden/lcf lcf] (customised version)
 +
# [https://luarocks.org/modules/hisham/luafilesystem luafilesystem] ([http://lunarmodules.github.io/luafilesystem/manual.html manual])
 +
# [https://luarocks.org/modules/rrt/lrexlib-pcre lrexlib-pcre] ([https://rrthomas.github.io/lrexlib/manual.html manual])
 +
# [http://lunarmodules.github.io/luasql/ luasql-sqlite3] (http://lunarmodules.github.io/luasql/manual.html manual)
 +
# [https://luarocks.org/modules/brimworks/lua-yajl lua-yajl] (manual in README)
 +
# [https://luarocks.org/modules/mpeterv/luazip luazip] ([http://mpeterv.github.io/luazip/ 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.
 +
 
 +
<nowiki>
 +
> luarocks show bit32
  
Could not find a package configuration file provided by "Qt5Core" with any
+
bit32 5.3.5.1-1 - Lua 5.2 bit manipulation library
of the following names:
 
  
Qt5CoreConfig.cmake
+
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.
qt5core-config.cmake
 
  
Add the installation prefix of "Qt5Core" to CMAKE_PREFIX_PATH or set
+
License:        MIT
"Qt5Core_DIR" to a directory containing one of the above files. If
+
Homepage:      http://www.lua.org/manual/5.2/manual.html#6.7
"Qt5Core" provides a separate development package or SDK, be sure it has
+
Installed in:  /usr/local
been installed.</nowiki>
 
  
You can fix this by setting <code>-DCMAKE_PREFIX_PATH=<your Qt + version + compiler location></code>. For example: <code>-DCMAKE_PREFIX_PATH=/home/vadi/Programs/Qt/5.8/gcc_64/</code> [[File:CLion CMake settings - finidng Qt.png|200px|thumb|right]]
+
Modules:
 +
        bit32 (/usr/local/lib/lua/5.1/bit32.so)
 +
 
 +
Depends on:
 +
        lua >= 5.1, < 5.5 (using 5.1-1)
 +
</nowiki>
 +
 
 +
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.
 +
 
 +
<nowiki>
 +
> 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
 +
</nowiki>
 +
 
 +
Or from within mudlet itself you can issue these commands to double check the correct paths are being used.
 +
 
 +
<nowiki>
 +
> 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
 +
</nowiki>
 +
 
 +
4. Recompile and run a test script using the [https://www.lua.org/pil/8.1.html require command] to load in the necessary library.
 +
 
 +
<nowiki>
 +
bit32 = require("bit32")
 +
 
 +
function bit32_test()
 +
  bit32.band(0,1)
 +
end
 +
</nowiki>
 +
 
 +
= Compile Time Flags =
 +
 
 +
<nowiki>
 +
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...
 +
</nowiki>

Revision as of 08:14, 4 May 2024

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.

Otherwise, hop in for new adventure!

Easy Mudlet code understanding.png

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 22.04

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 \
  libpcre3-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 \
  libglu1-mesa-dev mesa-common-dev libglib2.0-dev libgstreamer1.0-dev libqt5opengl5-dev \
  qtmultimedia5-dev qttools5-dev qt5keychain-dev libsecret-1-dev \
  libqt5texttospeech5-dev qtspeech5-flite-plugin qtspeech5-speechd-plugin \
  qtbase5-dev qtchooser qt5-qmake qtbase5-dev-tools qtmultimedia5-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-pcre

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 qmake, the first is for general use, the second is for developers:

 qmake ../src/mudlet.pro

*OR*

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

Now finish compiling:

 make -j `nproc`

4. installing compiled code

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

 sudo make 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 libpcre3-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
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 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

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/travis.osx.before_install.sh
 ./CI/travis.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 PCRE_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-pcre PCRE_DIR=`brew --prefix pcre`
 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`
 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 qt5`
 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. Troubleshooting

If you exhaust all efforts to get YAJL to compile on your local system with homebrew, 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 liblua5.1-0-dev zlib1g-dev libhunspell-dev libpcre3-dev \
libzip-dev libboost-dev libyajl-dev libpulse-dev libsecret-1-dev lua-rex-pcre2 lua-filesystem lua-zip \
lua-sql-sqlite3 qt5-qmake qtmultimedia5-dev qttools5-dev luarocks ccache libpugixml-dev
sudo luarocks install luautf8
sudo luarocks install lua-yajl
sudo luarocks install lrexlib-pcre

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

4. (Optional) Discord library

If you get the following error;

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:/home/user/mudlet-dev/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 libpcre3-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


installing apt dependencies

1.b Install luarocks dependencies

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


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

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 while still being able to use the system at all (~35min on a RPi4 with 4GB of ram)
make -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 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 Arch Linux

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

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-pcre
 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 qmake, the first is for general use, the second is for developers:

 qmake ../src/mudlet.pro

*OR*

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

Now finish compiling:

 make -j `nproc`

4. installing compiled code

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

 sudo make 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 groupinstall "Development Tools" "Development Libraries"
sudo dnf install compat-lua compat-lua-devel compat-lua-libs hunspell-devel lua5.1-filesystem luarocks pugixml-devel qtkeychain-qt5-devel bitstream-vera-fonts-all ccache qt-creator qt5-qtmultimedia-devel qt5-qtgamepad-devel yajl-devel qtchooser qt5-qttools-devel qt5-qttools-static zziplib-devel pcre-devel libzip-devel sqlite-devel
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-pcre

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
mkdir Mudlet/build
cd Mudlet/src

3. Make necessary compiling instruction adjustments

Edit mudlet.pro - find these lines in mudlet.pro and make the following changes:

    linux {
        LIBS += \
            -llua5.1 \
            -lhunspell
        INCLUDEPATH += /usr/include/lua5.1
    }

We're adding a - between lua and 5.1 and adding -1.7 to hunspell under LIBS so that it becomes this:

    linux {
        LIBS += \
            -llua-5.1 \
            -lhunspell-1.7
        INCLUDEPATH += /usr/include/lua5.1
    }

Save and exit.

4. Compile

cd ../build

Run this in the build directory:

WITH_FONTS=NO WITH_OWN_QTKEYCHAIN=NO WITH_UPDATER=NO WITH_VARIABLE_SPLASH_SCREEN=NO XDG_DATA_DIRS=/usr/share qmake-qt5 PREFIX=/usr INCLUDEPATH+=/usr/include/lua-5.1 LUA_SEARCH_OUT=lua-5.1 ../src/mudlet.pro

An explanation of the qmake arguments -- we're passing these environment variables to mudlet.pro:

WITH_FONTS=NO WITH_OWN_KEYCHAIN=NO WITH_UPDATER=NO WITH_VARIABLE_SPLASH_SCREEN=NO XDG_DATA_DIRS=/usr/share

Adding build variables to mudlet.pro so that it finds the correct libraries:

PREFIX=/usr INCLUDEPATH+=/usr/include/lua-5.1

And finally adding a build variable to translations/translated/updateqm.pri so that it uses the correct version of the Lua compiler (Fedora also comes with 5.4) to generate translation statistics.

LUA_SEARCH_OUT=lua-5.1

Once complete, run the following:

If you have time to kill (About 10 minutes on an Apple M1 Max in Fedora):

make

If you want it done as fast as possible(Less than a minute on an Apple M1 Max in Fedora):

make -j `nproc`

Or if you want something in between, make -j `nproc` tells it to use all available processor cores.  If you want to use a specific number instead (ie 2), you can use:

make -j 2

5. Install

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

6. Hang onto the cloned git repo If you need to uninstall, you can go back into the /build directory and 'sudo make uninstall'.

Compiling on Gentoo

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

Compiling on Windows

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 Note: You must use a location on C:\ without any spaces in folder names!

2. Perform a one-time setup

  • Open powershell in the newly cloned folder by typing in powershell in the address bar:
Open powershell in a folder.png
  • Run Set-ExecutionPolicy -Scope Process -ExecutionPolicy Unrestricted to enable the setup script to run and press A.
  • Run ./setup-windows-sdk.ps1

This will automatically download all of the requires tools (including Python 2) and libraries, set them up for you, build Mudlet, and launch it!

Note Note: If this script exits immediately, please upgrade your PowerShell version first. You may also need to allow to run scripts from the internet

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

3. Watch the magic happen

Here is a video recording of the setup unfolding, compiling, etc. for your comparsion:

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:

Qt-installer.gif

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

Qt-installer-data-collection.png

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

Compiling-step.gif

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

Mudlet-launching.gif

If something didn't work right, you can check out the verbose log that is available at C:\src\verbose_output.log.

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:

Selection 173.png

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:

Change Qt Creator to use many cores.gif

Hit run:

Selection 176.png

Click on Compile Output to see progress on compiling:

Selection 177.png

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, remove the following folders:

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

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

New codespace screenshot

2. Wait for it to load

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

Building Visual Studio Codespace.png

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:

Port privacy in Github Codespaces.png


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

Connect to remote machine.png


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

CMake configuration.png

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.

Building Mudlet in codespaces.png

5. Run Mudlet

Launch Mudlet.png

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!

Mudlet running remotely.png

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.

Compiling on Windows 7+ (MSYS2 Alternative)

INCOMPLETE, IN PROGRESS

Go to http://www.msys2.org/ to download the 64 bit MSYS2 installer (as of 2020/05/24 32 bit hosts - for compiling software, but not for using code built with it have been deprecated, the last installer for that 32-bit systems is held at: http://repo.msys2.org/distrib/i686/msys2-i686-20200517.exe) 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 the ones for 64-bit targets - it is possible to install both for building Mudlet for target PCs of both bitnesses on a 64-bit host, it is not clear whether the reverse is true with a 32-bit host. These will pull in a number of other required packages as well (the --needed option prevents the re-installation of packages that have already been installed by MSYS2/Mingw-w64's own setup/installation process) - as some of the packages, e.g. base-devel are actually groups you will be requested to select which members of that group are actually required, it is easiest to just go with the default which is to install ALL of the packages in that group!

For 32-Bit Mudlet builds:
MSYS user@computer ~
$ pacman -S --needed base-devel git mercurial cvs wget ruby zip p7zip python mingw-w64-i686-toolchain mingw-w64-i686-qt-creator mingw-w64-i686-qt5-multimedia mingw-w64-i686-libzip mingw-w64-i686-pugixml mingw-w64-i686-lua51 mingw-w64-i686-lua51-lpeg mingw-w64-i686-lua51-lsqlite3 mingw-w64-i686-hunspell mingw-w64-i686-boost mingw-w64-i686-yajl mingw-w64-i686-clang mingw-w64-i686-cmake mingw-w64-i686-SDL unzip
For 64-Bit Mudlet builds:
MSYS user@computer ~
$ pacman -S --needed base-devel git mercurial cvs wget ruby zip p7zip python mingw-w64-x86_64-toolchain mingw-w64-x86_64-qt-creator mingw-w64-x86_64-qt5-multimedia mingw-w64-x86_64-libzip mingw-w64-x86_64-pugixml mingw-w64-x86_64-lua51 mingw-w64-x86_64-lua51-lpeg mingw-w64-x86_64-lua51-lsqlite3 mingw-w64-x86_64-hunspell mingw-w64-x86_64-boost mingw-w64-x86_64-yajl mingw-w64-x86_64-clang mingw-w64-x86_64-cmake mingw-w64-x86_64-SDL unzip
The *-zziplib libraries are used by the luazip luarock {from the Kepler project} but Mudlet will work perfectly well with the alternative lua-zip {from the brimworks GitHub repository - which also provides the lua-yajl rock} which does not require this library - although it is possible that it might still be pulled into the system as a dependency of another MSYS2 package.
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!
Attention - Luarocks packages problem
Recently the Luarocks project attempted to adopt the MSYS2/Mingw-w64 platform as one it would supported natively and the MSYS2/Mingw-w64 project went and upgraded its luarocks packages to make use of the changes and also on-board other improvements (and the version number increased from 2.4.4-2 to 3.5.0-1) unfortunately this completely broke them and although the issue has been reported (MSYS2 Issue 9037) a fix has not yet materialised. The only way to work around this in the meantime is to download the older package (with wget) and install it manually (with pacman -U):
For 32-Bit Mudlet builds:
MSYS user@computer ~
$ wget https://repo.msys2.org/mingw/mingw32/mingw-w64-i686-lua51-luarocks-2.4.4-2-any.pkg.tar.zst
--2021-07-07 22:19:09--  https://repo.msys2.org/mingw/mingw32/mingw-w64-i686-lua51-luarocks-2.4.4-2-any.pkg.tar.zst
Resolving repo.msys2.org (repo.msys2.org)... 178.63.98.68
Connecting to repo.msys2.org (repo.msys2.org)|178.63.98.68|:443... connected.
HTTP request sent, awaiting response... 200 OK
Length: 97905 (96K) [application/octet-stream]
Saving to: ‘mingw-w64-i686-lua51-luarocks-2.4.4-2-any.pkg.tar.zst’

mingw-w64-i686-lua51-luarocks-2.4.4-2- 100%[===========================================================================>]  95.61K  --.-KB/s    in 0.07s

2021-07-07 22:19:10 (1.43 MB/s) - ‘mingw-w64-i686-lua51-luarocks-2.4.4-2-any.pkg.tar.zst’ saved [97905/97905]


MSYS user@computer ~
$ pacman -U mingw-w64-i686-lua51-luarocks-2.4.4-2-any.pkg.tar.zst
loading packages...
resolving dependencies...
looking for conflicting packages...

Packages (1) mingw-w64-i686-lua51-luarocks-2.4.4-2

Total Installed Size:  0.46 MiB

:: Proceed with installation? [Y/n] y
(1/1) checking keys in keyring                                                                [#####################################################] 100%
(1/1) checking package integrity                                                              [#####################################################] 100%
(1/1) loading package files                                                                   [#####################################################] 100%
(1/1) checking for file conflicts                                                             [#####################################################] 100%
(1/1) checking available disk space                                                           [#####################################################] 100%
:: Processing package changes...
(1/1) installing mingw-w64-i686-lua51-luarocks                                                [#####################################################] 100%

MSYS user@computer ~
For 64-Bit Mudlet builds:
MSYS user@computer ~
$ wget https://repo.msys2.org/mingw/mingw64/mingw-w64-x86_64-lua51-luarocks-2.4.4-2-any.pkg.tar.zst
--2021-07-07 22:17:32--  https://repo.msys2.org/mingw/mingw64/mingw-w64-x86_64-lua51-luarocks-2.4.4-2-any.pkg.tar.zst
Resolving repo.msys2.org (repo.msys2.org)... 178.63.98.68
Connecting to repo.msys2.org (repo.msys2.org)|178.63.98.68|:443... connected.
HTTP request sent, awaiting response... 200 OK
Length: 97935 (96K) [application/octet-stream]
Saving to: ‘mingw-w64-x86_64-lua51-luarocks-2.4.4-2-any.pkg.tar.zst’

mingw-w64-x86_64-lua51-luarocks-2.4.4- 100%[===========================================================================>]  95.64K  --.-KB/s    in 0.07s

2021-07-07 22:17:32 (1.28 MB/s) - ‘mingw-w64-x86_64-lua51-luarocks-2.4.4-2-any.pkg.tar.zst’ saved [97935/97935]


MSYS user@computer ~
$ pacman -U mingw-w64-x86_64-lua51-luarocks-2.4.4-2-any.pkg.tar.zst
loading packages...
resolving dependencies...
looking for conflicting packages...

Packages (1) mingw-w64-x86_64-lua51-luarocks-2.4.4-2

Total Installed Size:  0.46 MiB

:: Proceed with installation? [Y/n] y
(1/1) checking keys in keyring                                                                [#####################################################] 100%
(1/1) checking package integrity                                                              [#####################################################] 100%
(1/1) loading package files                                                                   [#####################################################] 100%
(1/1) checking for file conflicts                                                             [#####################################################] 100%
(1/1) checking available disk space                                                           [#####################################################] 100%
:: Processing package changes...
(1/1) installing mingw-w64-x86_64-lua51-luarocks                                              [#####################################################] 100%

MSYS user@computer ~
Warning for those planning to build both 32 and 64 bit versions
If one is planning to build both bitness binaries an additional step is necessary as, by default, the MSYS2/Mingw-w64 luarocks setup seems to place any .lua or .dll modules it builds/installs on a per user (the so-called local basis) into the same directories with the same names. This is no good for two reasons:
  • It is difficult to work out which bitness a particular module is for and whilst 32-bit modules might work in a 64-bit environment the reverse is definitely not the case
  • It confuses the Luarocks package management systems (as effectively there will be two different luarocks systems operated side-by-side)

This can be worked around by:

  • Editing the .\etc\luarocks\config-5.1.lua for each bitness so that the rocks_trees table entry for the user key is changed from this in both files:
    { name = [[user]], root = home..[[/.luarocks]] },

to something different for each of them, say, for example, for the the 64-bit one:

    { name = [[user]], root = home..[[/.luarocks-x64]] },
  • Then by specifying the rocktree name (user) on the command line when installing or building a luarock with the --tree user argument - note that for some inexplicable reason the --local argument that should do the same thing does not seem to work for these two actions, it is not clear whether this is a MSYS2/Mingw-w64 specific issue or it goes further upstream to Luarocks in general. Thus, in the next step it will be necessary to change from using:
MINGW64 user@computer ~
$ luarocks install --local rockname

to, for the example given:

MINGW64 user@computer ~
$ luarocks install --tree user rockname

where user is the literal string "user" to match the Lua table key in the rock_trees and not, in this case, a representation of the user-name/account of the person performing the action.

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:/msys64/home/user or c:/msys32/home/user (if both bitnessess are to be built it will be necessary to repeat the following step twice, one for each and also observe the steps in the above warning) install the following luarocks:

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

by using:

MINGW64 user@computer ~
$ luarocks install [--local] rockname

The --local argument is an optional one that causes the luarock and the lua module to be installed on a per-user basis rather than on a system wide one, this may be important if the PC is used by multiple users and more than one of them uses Lua in any form.

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 }

Some modifications to the qmake/cmake project files are needed and these are now supported in the main development branch in the upstream {the Mudlet organisation's own GitHub repository} which requires that there is an environmental variable WITH_MAIN_BUILD_SYSTEM and it is set to the (case-insensitive) value NO:

MINGW64 user@computer ~/src/mudlet
$ export WITH_MAIN_BUILD_SYSTEM=NO

Also the MINGW_BASE_DIR environmental variable will need to be set to the root directory for the MINGW-W64 installation for the appropriate bitness of the target to be made. For building on a 64-Bit Host {the PC that is compiling the code} to make a 64-Bit application this will likely be C:/msys64/mingw64 and for a 32-Bit application it will probably be C:/msys64/ming32.

E.g.
MINGW64 user@computer ~/src/mudlet
$ export MINGW_BASE_DIR=C:/msys64/mingw64 # To build a 64-Bit Application with a 64-Bit system
Or:
MINGW32 user@computer ~/src/mudlet
$ export MINGW_BASE_DIR=C:/msys64/mingw32 # To build a 32-Bit Application with a 64-Bit system

Now checkout a branch {ideally, if working on solving a new issue, or adding a feature or resolving a bug, one should create a new branch that is a copy of the current, upstream development 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...

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=/media/vadi/SSDer/Programs/Qt/5.14.2/gcc_64/

CLion CMake settings - finidng Qt.png

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.

Clion Settings - Cmake.png


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.

Toolchain.png

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:

Clang Tidy CLIon.png

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:

Clion cmake settings.png

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:

Clang-format CLion.png

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

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 /media/vadi/SSDer/Programs/Qt/5.14.2/gcc_64/:

CMake path in Visual Studio Code.png

Clang Tidy

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

Clang-tidy in vscode.png

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:

Cmake.configureSettings option in vscode.png

Choosing which sanitizers in vscode to use.png

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.

Clang tidy configuration.png
Clazy configuration.png

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:

Sanitisers in qt creator.png

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:

Qt Creator clang format.png

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

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

  1. luautf8 (manual in README)
  2. lcf (customised version)
  3. luafilesystem (manual)
  4. lrexlib-pcre (manual)
  5. luasql-sqlite3 (http://lunarmodules.github.io/luasql/manual.html manual)
  6. lua-yajl (manual in README)
  7. luazip (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

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