Compilation
aMule uses CMake (minimum version 3.12) 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.12 | Build system (3.14 for DOWNLOAD_AND_BUILD_DEPS) |
| 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 --branch 3.2.0 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 and CMake ≥ 3.14) |
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 apart from the IPv6 Connection preferences of an ENABLE_IPV6 build, 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). aMule does not advertise uTP itself. Also the transport for ENABLE_NATT_SERVER_COORDINATION |
ENABLE_IPV6 | NO | Experimental native IPv6 for eD2k TCP: dual-stack listener, dialing IPv6 peers and sources, advertising an IPv6 address (identity migration still incomplete) |
ENABLE_NATT_SERVER_COORDINATION | NO | Experimental server-coordinated NAT traversal (Lugdunum callbacks, ed2k-server LowID hole punching). Each mechanism also needs its amule.conf runtime setting, off by default |
ENABLE_KAD_NODE_PROTECTION | NO | Local Kad node-protection heuristics: adaptive request timeouts and Kad identity protections (no wire-protocol change) |
ENABLE_QUIC | NO | Experimental QUIC transport for NAT-traversed connections in amule/amuled. Requires the system ngtcp2 (≥ 1.0.0) with its GnuTLS crypto library, and BUILD_MONOLITHIC or BUILD_DAEMON (configure fails otherwise) |
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. In a build without amule and amuled, ENABLE_QUIC stays off |
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/ |
| Icons | /usr/local/share/icons/hicolor/{128x128,256x256,scalable}/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. po4a skips a page that is less than 70% translated; that page is not installed, and man shows the English page instead.
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
The binaries can be run directly from the build tree. amule, amuled, amulegui, amulecmd and ed2k are placed in build/src/, amuleapi in build/src/webapi/, amuleweb in build/src/webserver/src/, and the utilities under build/src/utils/. On macOS, amule and amulegui are app bundles (build/src/aMule.app, build/src/aMuleGUI.app).
./build/src/amule # macOS: ./build/src/aMule.app/Contents/MacOS/aMule
./build/src/amuled
./build/src/webapi/amuleapi
./build/src/amulecmd
This is the recommended workflow during development — no need to install after every build.
Development Build Script
scripts/compile.sh configures, builds and tests every program (BUILD_* targets and BUILD_TESTING) in build/, with ENABLE_NLS, ENABLE_UPNP and ENABLE_IP2COUNTRY on. Run it from the top of the source tree:
./scripts/compile.sh -j"$(nproc)"
| Option | Effect |
|---|---|
--clean | Remove the build folder first, for a full rebuild. Without it, the build is incremental |
-d, --debug | Debug build instead of Release |
-e, --experimental | Also compile every experimental feature (ENABLE_ALL_EXPERIMENTAL). Without it the script passes NO, so an existing build folder switches back |
-j<n>, --jobs <n> | Run <n> build jobs in parallel |
-s, --strip | Show the sizes the executables would have once stripped; the build folder is left untouched |
-c, --measure-cache | Build with an empty, isolated ccache directory and print its size. Skips the tests; implies --clean |
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.