Skip to content

Compiling

Jump to bottom Edit New page
Dalton Messmer edited this page Oct 13, 2024 · 73 revisions

Contents



Dependencies

The following packages are required for building. Since most desktops offer these libraries through package repositories, we recommend using the Dependency Quickstart for most purposes. In case you are using windows for building lmms, where package managers do not really exist, we recommend using vcpkg

If you get stuck, please ask in the #support channel on Discord.

If a package is not available for your platform, you may need to manually install.

Dependencies Quickstart

Recommended. Each platform requires a compiler and several libraries. We've selected the most common settings for you.

Qt 5.9+ is required on the master branch. If you're using Linux and your distribution only ships older Qt versions, install Qt using the official installer at https://www.qt.io/download-open-source.

A platform is missing? Add it like this.

Dependencies Detailed

Alternately, you may download and compile each dependency manually. This is recommended for advanced users only.

Build Toolchain

Supported Toolchain Version Branch
✔️ cmake 3.9.0 master
✔️ cmake 2.8.7 stable-1.2
✔️ cmake 2.4.5 stable-1.1

Compiler

Supported Compiler
✔️ gcc/g++
✔️ clang
✔️ mingw-w64
✔️ msvc++

Libraries

Required Library Version Description
✔️ Qt5 >=5.9 on master, >=5.0 on stable-1.2 Widget toolkit for creating cross-platform graphical user interfaces
✔️ libsndfile >=1.0.11 Reading and writing sound files, >=1.0.18 for lmms>=master(>=1.0.26 for FLAC compression level setting for lmms>=master and >=1.1.0 for MP3 audio import for lmms>=master)
✔️ fftw3 Fast fourier transform computing library
✔️ libsamplerate >=0.1.7 Audio sample rate converter
libvorbis Audio encoding library
libogg Multimedia container format
wine Windows-on-Unix (needed for VST support)
libstk Signal processing and algorithmic synthesis library
libfluidsynth SoundFont synthesis library
fltk Lightweight GUI library (needed by ZynAddSubFX)
jack Software and hardware audio routing
sdl2 Audio interface library*
alsa Audio interface library*
libportaudio Audio interface library*
libsoundio Audio interface library*
perl For compiling the swh LADSPA plugins
perl XML::Parser For compiling the swh LADSPA plugins

*One or more required for audio playback



Clone Source Code

Before preparing the build environment, you must have a branch copy of the source code*.

# clone the "master" branch (e.g. "stable-1.2", etc)
git clone --recurse-submodules -b master https://github.com/lmms/lmms

* Advanced users may prefer to download a tarball instead: zip | tarball

For most users, this will create a folder ~/lmms which can be used for building. If you're already using ~/lmms for samples you'll see path 'lmms' already exists, use an alternate location e.g. ~/Desktop and try again.

    ... want to switch branches or fast-forward? See Accessing git repository.



Build Environment

The cmake toolchain offers several built-in configuration options. In addition, LMMS adds several options useful for building. Below are a list of the most standard options. We recommend using the CMake Quickstart for most purposes.

CMake Quickstart

Assumes you've already installed dependencies and cloned the source code

  1. Prepare build and, optionally, the target directories

    cd lmms
mkdir build
cd build

  2. And then choose one of the following...

    Running CMake

    # from "lmms/build" directory
cmake .. -DCMAKE_INSTALL_PREFIX=../target/

    Notes:

    • In case you want to build LMMS <= stable-1.2 with Qt5, see Using Qt5.
    • On MacOS, adding -DCMAKE_PREFIX_PATH="$(brew --prefix qt5)" to the end of the cmake command will point CMake to Qt5.
    • If CMake complains about not being able to find wine, add -DCMAKE_PREFIX_PATH=/usr/lib/wine to the end of the cmake command.

Build Options

Option* Description Common Values
CMAKE_INSTALL_PREFIX Install to non-standard (non-root) location. This is generally preferred, especially for coding, testing and packaging. ../target
CMAKE_PREFIX_PATH Set your Qt5 (probably other library too) installation path if it does not reside in standard installation paths /path/to/qt5
CMAKE_BUILD_TYPE Force build to include debugging or optimization symbols Release, Debug, RelWithDebInfo
CMAKE_CXX_COMPILER_LAUNCHER A compiler launcher can be used to (significantly) speed up subsequent builds, e.g. ccache. ccache
FORCE_VERSION Force version within software, useful for distributing one-off packages internal, 1.2.3-myfix
PLUGIN_LIST Limit build only to the specified /plugins/, used to reduce compile time, such as when bisecting "audio_file_processor kicker triple_oscillator"
LMMS_MINIMAL Same effect as PLUGIN_LIST, but auto-selects the core plugins required for most basic testing. True
WANT_QT5, WANT_SDL, WANT_SWH, WANT_VST... Toggle on/off a library, dependency or feature ON, OFF

* When provided on command line, all options must be prefixed with -D, e.g
cmake -DCMAKE_BUILD_TYPE=Debug

Using Qt5 (Obsolete)

Note: These flags are ONLY required for stable-1.2 branch. Newer branches (e.g. master) use Qt5 by default and doesn't require this.

In order to build LMMS with Qt5, add the following flag when invoking cmake: 
-DWANT_QT5=ON

... or if you're using mingw and configuring via script, you will provide -qt5 as a parameter to the shell script.

../cmake/build_mingw64.sh -qt5

If your Qt5 installation does not reside in standard installation paths, additionally pass e.g.

-DCMAKE_PREFIX_PATH=/path/to/qt5
# e.g. on Mac, -DCMAKE_PREFIX_PATH="$(brew --prefix qt)"

    ... still need help? Ask on our Discord chat server



Compiling

Do note that this section is for Linux and Mac. For Windows, refer to this page

Assumes you've already installed dependencies and cloned the source code and configured the build environment.

# from "lmms/build" directory
make -j4

... and then run by calling:

./lmms

Compilation errors are usually attributed to missing packages, misconfigured system or specific compatibility problems. Please jump to the appropriate troubleshooting guide:

Troubleshooting: Ubuntu, Debian, Fedora, openSUSE, Arch, macOS



Debugging

Debugging LMMS requires a re-run of the cmake command, but with the debug symbols turned on. For a comprehensive tutorial, see also Debugging LMMS

Adding Debug Symbols

# from "lmms/build" directory
cmake .. -DCMAKE_BUILD_TYPE=Debug -DCMAKE_INSTALL_PREFIX=../target/
# -- OR for better performance --
cmake .. -DCMAKE_BUILD_TYPE=RelWithDebInfo -DCMAKE_INSTALL_PREFIX=../target/
# re-run the build
make -j4

Debugging with gdb

Assuming you have gcc (most common), you'll need gdb installed via apt-get, dnf, pacman, etc.

gdb lmms
# or alternately gdb ../target/bin/lmms
(gdb) run
# once you hit the crash, CTRL + C
backtrace full

Debugging with lldb

Assuming you have clang (macOS, FreeBSD), you'll need lldb installed via brew, pkg_add, etc.

lldb lmms
# or alternately lldb ../target/bin/lmms
# macOS, use `make -j4 install` then `lldb LMMS.app/Contents/MacOS/lmms`
(lldb) run
# once you hit the crash, CTRL + C
thread backtrace all



Packaging

Supported Format Platform Notes
✔️ .exe Windows lmms>=0.4.0
✔️ .dmg macOS lmms>=1.0.0
✔️ .AppImage Linux Universal Work in progress, see #3688
✖️ .run Linux Universal Work in progress, see #2932
❌ .deb Debian, Ubuntu See #1620. Please contact package maintainers.
❌ .rpm Fedora, openSUSE Related to #1620. Please contact package maintainers.

Windows Packaging

This is the most common type for getting features and fixes out to a large number of testers. Assumes you've already installed dependencies and cloned the source code and configured the build environment. Once completed, the release should be published for others to download.

# from "lmms/build" directory
make package     # package using nsis

Try explorer . to see it in Explorer. Produces lmms-1.2.0.123-win64.exe, where 123 is the number of commits since stable release.

MacOS Packaging

Assumes you've already installed dependencies and cloned the source code and configured the build environment. Once completed, the release should be published for others to download.

Warning: Must set CMAKE_INSTALL_PREFIX or it will attempt to bundle all of /usr/local/.

# from "lmms/build" directory
make install     # builds the app bundle
make dmg         # creates the disk image using appdmg
open .           # optional: view in Finder

Produces lmms-1.2.0.123-mac10.11.dmg, where 123 is the number of commits since stable release and mac10.11 is the macOS version which the package was built on.

Linux Packaging

Assumes you've already installed dependencies and configured the build environment. Once completed, the release should be published for others to download. This command will fail if CMAKE_INSTALL_PREFIX was not provided.

Due to restrictions and best practice you can't build AppImages on systems newer than the oldest still-supported Ubuntu release (not counting Extended Security Maintenance).

# from "lmms/build" directory
make install     # installs to target
make appimage    # creates a Linux AppImage

Produces lmms-1.2.0-123-linux-x86_64.AppImage, where 123 is the number of commits since stable release.

Publishing a Release

Using GitHub releases, Project administrators may wish to package a release to their personal github account or to the entire project.

  • Personal Release: Used for distributing early feature or test packages.
    • URL: https://github.com/tresf/lmms/releases (replace tresf with your @github id)
  • Project Release: Used for distributing official stable and release candidate packages.
    • URL: https://github.com/lmms/lmms/releases

Download statistics are available here

Example release notes available here.

Clone this wiki locally