Compilation
aMule uses CMake (minimum version 3.10) as its build system. This page covers the complete build, install, and uninstall workflow. Platform-specific dependency installation commands are in the sub-pages for Windows, macOS, Linux, and BSD.
Dependencies
Required
| Package | Minimum version | Notes |
|---|---|---|
| CMake | 3.10 | Build system |
| zlib | 1.2.3 | Compression |
| wxWidgets | 3.2.0 | GUI toolkit (3.2 branch or newer) |
| Crypto++ | 8.1 | Hashing (MD4, MD5, SHA-1), RSA and EC encryption — classic or cryptopp-modern |
| Boost | 1.70 | Headers only; only asio is used |
The Crypto++ row accepts either the classic weidai11/cryptopp library (minimum 8.1, the first release with the ChaCha20-Poly1305 cipher used by EC encryption) or the cryptopp-modern fork (any release). The cmake check disambiguates the two by CRYPTOPP_VERSION: cryptopp-modern uses a calendar-style version number and is accepted without a minimum check. Since aMule 3.1.0, Crypto++ also provides SHA-1 and MD5 — aMule no longer ships its own implementations.
wxWidgets must be built with Unicode support (the default since wx 3.0). aMule is Unicode-only.
Optional
| Package | What it enables |
|---|---|
libgd ≥ 2.0.0 | Statistics images in cas |
libupnp ≥ 1.6.6 | UPnP port forwarding |
libmaxminddb ≥ 1.0 | Country flags and IP→country mapping |
gettext ≥ 0.11.5 | Native-language support (NLS) |
po4a | Translated man pages, rendered at build time; see Translated Man Pages |
libayatana-appindicator3 | Linux only. StatusNotifierItem (SNI) tray-icon backend; see Building on Linux. |
glib-2.0 dev headers | wxGTK builds (Linux / BSD). Required for the g_set_prgname() desktop-entry binding when building amule, amuled, or amulegui. No-op on macOS. |
readline | Line editing in amulecmd and amuleweb |
binutils-dev / libbfd | BFD-based crash handler |
libpng | PNG support in amuleweb |
Quick Start
# Clone the repository
git clone https://github.com/amule-org/amule.git
cd amule
# Install platform-specific dependencies first (see sub-pages)
# Configure — build the all-in-one GUI + daemon
cmake -B build \
-DBUILD_MONOLITHIC=YES \
-DBUILD_DAEMON=YES
# Build
cmake --build build -j"$(nproc)"
# Install (default prefix: /usr/local)
sudo cmake --install build
Build Options
All options are passed as -DOPTION=YES or -DOPTION=NO to the initial cmake -B build command.
| Option | Default | Builds |
|---|---|---|
BUILD_MONOLITHIC | YES | amule — all-in-one GUI client |
BUILD_DAEMON | NO | amuled — headless daemon |
BUILD_REMOTEGUI | NO | amulegui — remote control GUI |
BUILD_WEBSERVER | NO | amuleweb — legacy WebUI (HTTP web interface) |
BUILD_AMULEAPI | NO | amuleapi — REST API daemon and Web UI |
BUILD_AMULECMD | NO | amulecmd — CLI client for the daemon |
BUILD_ED2K | YES | ed2k — eD2k link handler helper |
BUILD_ALC | NO | alc — aMuleLinkCreator GUI |
BUILD_ALCC | NO | alcc — aMuleLinkCreator console |
BUILD_CAS | NO | cas — C statistics tool (Unix only) |
BUILD_WXCAS | NO | wxcas — GUI statistics tool |
BUILD_FILEVIEW | NO | fileview — console file viewer (experimental) |
BUILD_TESTING | NO | Unit test suite |
ENABLE_NLS | YES | Native-language support (gettext) |
TRANSLATED_MANPAGES | YES | Translated man pages rendered via po4a (requires ENABLE_NLS; skipped with a notice if po4a is not found) |
ENABLE_UPNP | YES | UPnP port forwarding |
ENABLE_IP2COUNTRY | YES | IP→country mapping (libmaxminddb), see IP2Country |
ENABLE_MMAP | YES | Compile the memory-mapped file I/O path where the platform supports it. Whether it is used is the runtime preference MMapEnabled (off by default); set this option NO only to leave the mmap code out entirely (e.g. sanitizer builds) |
ENABLE_BFD | YES | Use libbfd for in-process backtrace symbol resolution in crash reports; NO falls back to backtrace_symbols() plus an external addr2line |
USE_SYSTEM_PICOJSON | NO | Build amuleapi against a system-installed picojson instead of the bundled copy |
DOWNLOAD_AND_BUILD_DEPS | NO | When an optional dependency is missing, let CMake download and build it from source instead of failing (requires Git) |
ENABLE_CCACHE | AUTO | Use ccache as compiler launcher when found (AUTO/ON/OFF). Set OFF for distro builds that wrap the compiler themselves; set ON to hard-fail when ccache is missing |
ENABLE_VERSION_CHECK | ON | Compile in the in-app new-version check: the startup and daily check with its notification, the Periodically check for a new version preference and the About window's Check for updates button. Set OFF for OS-package builds: the whole feature is compiled out, nothing contacts GitHub, and the distro's package manager owns updates |
To list all available options with descriptions:
cmake -LAH -B build | less
Building Everything
cmake -B build \
-DBUILD_MONOLITHIC=YES \
-DBUILD_DAEMON=YES \
-DBUILD_REMOTEGUI=YES \
-DBUILD_WEBSERVER=YES \
-DBUILD_AMULEAPI=YES \
-DBUILD_AMULECMD=YES \
-DBUILD_ED2K=YES \
-DBUILD_ALC=YES \
-DBUILD_ALCC=YES \
-DBUILD_CAS=YES \
-DBUILD_WXCAS=YES \
-DBUILD_FILEVIEW=YES \
-DBUILD_TESTING=YES \
-DENABLE_NLS=YES \
-DENABLE_UPNP=YES \
-DENABLE_IP2COUNTRY=YES
Or, using the BUILD_EVERYTHING shorthand:
cmake -B build -DBUILD_EVERYTHING=YES
BUILD_EVERYTHING turns on every program target (BUILD_*; cas on Unix only), except BUILD_TESTING, which must still be enabled separately. It does not touch the ENABLE_* toggles, but ENABLE_NLS, ENABLE_UPNP, and ENABLE_IP2COUNTRY are all YES by default, so a default BUILD_EVERYTHING invocation produces a full-feature build provided their respective libraries (gettext, libupnp, libmaxminddb) are installed.
Experimental Options
These switches compile in unfinished features. They are all NO by default, a build without them behaves exactly like the upstream release, and nothing they enable is exposed as a user preference. See Experimental Groundwork.
| Option | Default | Enables |
|---|---|---|
ENABLE_UTP | NO | Experimental IPv4 uTP transport in amule/amuled: datagram framing, inbound streams and dialing peers that advertise it (vendored libutp; requires CMake ≥ 3.12). aMule does not advertise uTP itself |
ENABLE_IPV6 | NO | Experimental native IPv6 TCP admission (the IPv6 identity migration is still incomplete) |
ENABLE_KAD_PROTOCOL_10 | NO | Advertise Kademlia protocol version 0x0a (instead of 0x08) and the AICH hashes on keyword storage introduced by Kad 0x09 |
ENABLE_KAD_NODE_PROTECTION | NO | Local Kad node-protection heuristics: adaptive request timeouts and Kad identity protections (no wire-protocol change) |
ENABLE_ALL_EXPERIMENTAL | NO | Turn on every switch above at once. It overrides the individual switches, so -DENABLE_X=NO cannot exclude one while it is on — to build all but one, name the others individually |
Experimental options are for development and testing only. Do not enable them in release or distribution packages.
Debug Build
cmake -B build -DCMAKE_BUILD_TYPE=Debug -DBUILD_MONOLITHIC=YES
cmake --build build -j"$(nproc)"
The Debug type enables compiler optimisation flags for debugging and retains full symbol information. See Debugging for how to use it with GDB and Valgrind.
Installing
sudo cmake --install build
Default installation layout under /usr/local:
| What | Where |
|---|---|
| Binaries | /usr/local/bin/ |
| Translation catalogs | /usr/local/share/locale/<lang>/LC_MESSAGES/amule.mo |
| Man pages (English) | /usr/local/share/man/man1/ |
| Man pages (translated) | /usr/local/share/man/<lang>/man1/ |
| Data files (skins, webserver) | /usr/local/share/amule/ |
| Documentation | /usr/local/share/doc/amule/ |
| License | /usr/local/share/LICENSE.md |
| Desktop entries | /usr/local/share/applications/ |
| Icon | /usr/local/share/icons/hicolor/128x128/apps/ |
| AppStream metadata | /usr/local/share/metainfo/ |
Custom Install Prefix
Override the prefix with -DCMAKE_INSTALL_PREFIX:
cmake -B build -DCMAKE_INSTALL_PREFIX=/opt/amule -DBUILD_MONOLITHIC=YES
cmake --build build -j"$(nproc)"
sudo cmake --install build
Developer Install (No sudo)
Install to $HOME/.local during development. No root required, and easy to undo:
cmake --install build --prefix=$HOME/.local
Binaries land in ~/.local/bin/ (make sure it is in your $PATH).
On Linux, after a raw cmake --install you may need to refresh the icon cache and ensure the SNI tray-icon backend is present — see Desktop Integration.
Uninstalling
CMake records every installed file in build/install_manifest.txt. Use it to remove them:
# System install
sudo xargs rm -f < build/install_manifest.txt
# Local install (no sudo needed)
xargs rm -f < build/install_manifest.txt
Translated Man Pages
The translated man pages are not tracked in git — they are rendered at build time by po4a from the English masters (docs/man/*.1.in, src/utils/*/docs/*.1.in) and the translation catalogs (docs/man/po/manpages-<lang>.po), then installed under <prefix>/share/man/<lang>/man1/. Rendering is controlled by the TRANSLATED_MANPAGES option (default YES when ENABLE_NLS=YES): if po4a is found, the pages are rendered as part of the normal build; if it is missing, the build prints a notice and installs only the English pages — pass -DTRANSLATED_MANPAGES=NO to silence it.
After editing an English master, refresh the translation catalogs with ./scripts/update-manpages-po.sh and commit the diff (CI checks this). See Man Page Translations for the full translation workflow.
To build without po4a and still ship translated man pages, use the source bundle attached to each GitHub Release (aMule-<VERSION>-src.tar.gz) instead of the GitHub-generated "Source code" archive. It includes the pre-rendered *.<lang>.1.in files alongside the English masters, so po4a is not needed at build time.
Running Without Installing
All built binaries are placed in build/ and can be run directly:
./build/amule
./build/amuled
./build/amulecmd
This is the recommended workflow during development — no need to install after every build.
Speeding Up Builds with ccache
If ccache is installed, CMake detects it automatically and uses it as a compiler launcher. Incremental rebuilds are significantly faster when switching between branches or performing git bisect sessions:
# Debian / Ubuntu
sudo apt install ccache
# Fedora / RHEL
sudo dnf install ccache
Running the Unit Tests
cmake -B build -DBUILD_TESTING=YES -DBUILD_MONOLITHIC=YES
cmake --build build -j"$(nproc)"
ctest --test-dir build --output-on-failure
See Testing for the full test suite documentation.