From ffa3959bfe8254cf7826fd9f54cf170b4ae01095 Mon Sep 17 00:00:00 2001 From: ngosang Date: Tue, 3 Nov 2026 09:43:56 +0100 Subject: [PATCH] Update developer build guides for aMule 3.2.0 - Windows: build in MSYS2 CLANG64 (x64) or CLANGARM64 (ARM64); MINGW64 is no longer supported (amule-org/amule#2316). Update package names, DLL paths, packaging notes and troubleshooting. - Fix build output paths: binaries are under build/src/ (amuleapi in build/src/webapi/, app bundles on macOS). - Clone the 3.2.0 tag in the compilation guides. - Drop the too-short ctest timeout on Windows. --- docs/developer/compilation/bsd.md | 11 +-- docs/developer/compilation/index.md | 11 +-- docs/developer/compilation/linux.md | 11 +-- docs/developer/compilation/macos.md | 13 +-- docs/developer/compilation/windows.md | 115 +++++++++++------------- docs/developer/debugging.md | 24 ++--- docs/developer/file-formats/fileview.md | 2 +- docs/developer/index.md | 6 +- 8 files changed, 94 insertions(+), 99 deletions(-) diff --git a/docs/developer/compilation/bsd.md b/docs/developer/compilation/bsd.md index 8868f36..3470c19 100644 --- a/docs/developer/compilation/bsd.md +++ b/docs/developer/compilation/bsd.md @@ -76,7 +76,7 @@ On NetBSD, `gettext-tools` pulls in `gettext-lib` (which provides `libintl`) aut ## Build ```sh -git clone https://github.com/amule-org/amule.git +git clone --branch 3.2.0 https://github.com/amule-org/amule.git cd amule cmake -B build \ @@ -99,12 +99,13 @@ This enables a common set of components. See [Build Options](index.md#build-opti ## Running from the Build Directory -All binaries are placed in `build/` and can be run directly without installing: +The main binaries are placed in `build/src/` (`amuleapi` in `build/src/webapi/`; see [Running Without Installing](index.md#running-without-installing) for the others) and can be run directly without installing: ```sh -./build/amule -./build/amuled -./build/amulecmd +./build/src/amule +./build/src/amuled +./build/src/webapi/amuleapi +./build/src/amulecmd ``` ## BSD-Specific Notes diff --git a/docs/developer/compilation/index.md b/docs/developer/compilation/index.md index f98af8b..74c750f 100644 --- a/docs/developer/compilation/index.md +++ b/docs/developer/compilation/index.md @@ -40,7 +40,7 @@ wxWidgets must be built with Unicode support (the default since wx 3.0). aMule i ```sh # Clone the repository -git clone https://github.com/amule-org/amule.git +git clone --branch 3.2.0 https://github.com/amule-org/amule.git cd amule # Install platform-specific dependencies first (see sub-pages) @@ -216,12 +216,13 @@ To build without `po4a` and still ship translated man pages, use the **source bu ## Running Without Installing -All built binaries are placed in `build/` and can be run directly: +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`). ```sh -./build/amule -./build/amuled -./build/amulecmd +./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. diff --git a/docs/developer/compilation/linux.md b/docs/developer/compilation/linux.md index f5443e3..5a14c2f 100644 --- a/docs/developer/compilation/linux.md +++ b/docs/developer/compilation/linux.md @@ -129,7 +129,7 @@ For debugging on Gentoo with split-debug symbols, see [Debugging](../debugging.m ## Build ```sh -git clone https://github.com/amule-org/amule.git +git clone --branch 3.2.0 https://github.com/amule-org/amule.git cd amule cmake -B build \ @@ -154,12 +154,13 @@ This enables a common set of components. See [Build Options](index.md#build-opti ## Running from the Build Directory -All binaries are placed in `build/` and can be run directly without installing: +The main binaries are placed in `build/src/` (`amuleapi` in `build/src/webapi/`; see [Running Without Installing](index.md#running-without-installing) for the others) and can be run directly without installing: ```sh -./build/amule -./build/amuled -./build/amulecmd +./build/src/amule +./build/src/amuled +./build/src/webapi/amuleapi +./build/src/amulecmd ``` ## Desktop Integration diff --git a/docs/developer/compilation/macos.md b/docs/developer/compilation/macos.md index 25008d9..75ddc6f 100644 --- a/docs/developer/compilation/macos.md +++ b/docs/developer/compilation/macos.md @@ -65,7 +65,7 @@ On Intel Macs, Homebrew installs to `/usr/local`, which is already on the defaul ## Build ```sh -git clone https://github.com/amule-org/amule.git +git clone --branch 3.2.0 https://github.com/amule-org/amule.git cd amule cmake -B build \ @@ -95,13 +95,14 @@ If `ENABLE_NLS=YES` but `msgfmt`/`msgmerge` or `libintl` cannot be found, the co ## Running from the Build Directory -All binaries are placed in `build/` and can be run directly without installing: +The main binaries are placed in `build/src/` (`amuleapi` in `build/src/webapi/`; see [Running Without Installing](index.md#running-without-installing) for the others) and can be run directly without installing. `amule` and `amulegui` are built as the `aMule.app` and `aMuleGUI.app` bundles: ```sh -./build/amule -./build/amuled -./build/amuleapi -./build/amulecmd +./build/src/aMule.app/Contents/MacOS/aMule +./build/src/aMuleGUI.app/Contents/MacOS/aMuleGUI +./build/src/amuled +./build/src/webapi/amuleapi +./build/src/amulecmd ``` For how to use each binary, see the User Manual: [amuled](../../manual/interfaces/amuled.md) (daemon), [amuleapi](../../manual/interfaces/amuleapi/index.md) (REST API & Web UI), [amulecmd](../../manual/interfaces/amulecmd.md) (command-line client), and [amuleweb](../../manual/interfaces/amuleweb.md) (legacy WebUI). diff --git a/docs/developer/compilation/windows.md b/docs/developer/compilation/windows.md index 94310c4..5020705 100644 --- a/docs/developer/compilation/windows.md +++ b/docs/developer/compilation/windows.md @@ -3,7 +3,7 @@ id: windows title: Building on Windows --- -This page is a self-contained guide to building aMule from source on Windows using **MSYS2** with the **MINGW64** toolchain and **Ninja** as the build generator. The general [Compilation](index.md) page documents the full CMake workflow and the complete list of [build options](index.md#build-options). For other platforms, see [macOS](macos.md), [Linux](linux.md), and [BSD](bsd.md). +This page is a self-contained guide to building aMule from source on Windows using **MSYS2** with the **CLANG64** toolchain (x64) and **Ninja** as the build generator. The general [Compilation](index.md) page documents the full CMake workflow and the complete list of [build options](index.md#build-options). For other platforms, see [macOS](macos.md), [Linux](linux.md), and [BSD](bsd.md). ## Prerequisites @@ -11,44 +11,48 @@ This page is a self-contained guide to building aMule from source on Windows usi Download and install MSYS2 from [https://www.msys2.org/](https://www.msys2.org/). Follow the first-run update instructions on the website. -After the base installation, open the **MSYS2 MINGW64** terminal (not MSYS2 MSYS or UCRT64) for all subsequent steps. +After the base installation, open the **MSYS2 CLANG64** terminal for all subsequent steps. On Windows on ARM, use **MSYS2 CLANGARM64** instead (see [Building for ARM64](#building-for-arm64)). The Windows build requires CMake ≥ 3.12, wxWidgets ≥ 3.2.0, Boost ≥ 1.70, and crypto++ ≥ 8.1 — the MSYS2 packages below already satisfy these. :::note -MSYS2 packages only wxWidgets 3.2 for MINGW64, so a MINGW64 build lacks the **Appearance** setting (light/dark mode), which needs wxWidgets 3.3. The release packages and CI build x64 in **CLANG64** instead (see [Packaging](#packaging-portable-zip-and-installer)). +**MINGW64** is no longer supported: MSYS2 deprecated it and no longer packages wxWidgets for it. An existing MINGW64 setup cannot build aMule; switch to the CLANG64 shell and install the packages below. ::: ## Install Dependencies -In the MSYS2 MINGW64 terminal: +In the MSYS2 CLANG64 terminal: ```sh pacman -Syu pacman -S \ - mingw-w64-x86_64-boost \ - mingw-w64-x86_64-cmake \ - mingw-w64-x86_64-crypto++ \ - mingw-w64-x86_64-gettext \ - mingw-w64-x86_64-libgd \ - mingw-w64-x86_64-libmaxminddb \ - mingw-w64-x86_64-ninja \ - mingw-w64-x86_64-pkgconf \ - mingw-w64-x86_64-pupnp \ - mingw-w64-x86_64-readline \ - mingw-w64-x86_64-toolchain \ - mingw-w64-x86_64-wxwidgets3.2-msw \ - mingw-w64-x86_64-zlib + mingw-w64-clang-x86_64-boost \ + mingw-w64-clang-x86_64-cmake \ + mingw-w64-clang-x86_64-crypto++ \ + mingw-w64-clang-x86_64-gettext \ + mingw-w64-clang-x86_64-libgd \ + mingw-w64-clang-x86_64-libmaxminddb \ + mingw-w64-clang-x86_64-ninja \ + mingw-w64-clang-x86_64-pkgconf \ + mingw-w64-clang-x86_64-pupnp \ + mingw-w64-clang-x86_64-readline \ + mingw-w64-clang-x86_64-toolchain \ + mingw-w64-clang-x86_64-wxwidgets3.3-msw \ + mingw-w64-clang-x86_64-zlib ``` -The `mingw-w64-x86_64-toolchain` group includes GCC, binutils, and all associated tools. +The `mingw-w64-clang-x86_64-toolchain` group includes Clang, LLD, and all associated tools. CI installs its own list (`cmake_mingw_w64_deps` in `.github/workflows/ccpp.yml`): it builds libupnp from source instead of installing `pupnp`, and adds packages for optional features such as QUIC. + +### Building for ARM64 + +On Windows on ARM, work in the **MSYS2 CLANGARM64** terminal and replace the `mingw-w64-clang-x86_64-` prefix with `mingw-w64-clang-aarch64-` in every package name on this page. The rest of the guide is the same, except that the DLLs live in `C:\msys64\clangarm64\bin`. ## Build -In the MSYS2 MINGW64 terminal, clone the repository and configure with CMake using the **Ninja** generator: +In the MSYS2 CLANG64 terminal, clone the repository and configure with CMake using the **Ninja** generator: ```sh -git clone https://github.com/amule-org/amule.git +git clone --branch 3.2.0 https://github.com/amule-org/amule.git cd amule cmake -B build \ @@ -66,11 +70,7 @@ cmake -B build \ cmake --build build ``` -The `-G Ninja` flag selects the Ninja build generator, which is faster than the default `make`-based generator for incremental builds. To use all available CPU cores: - -```sh -cmake --build build -- -j$(nproc) -``` +The `-G Ninja` flag selects the Ninja build generator, which is faster than the default `make`-based generator for incremental builds and uses all CPU cores by default. This enables a common set of components. See [Build Options](index.md#build-options) for the full list. To build every component, add the remaining `BUILD_*`/`ENABLE_*` flags (e.g. `-DBUILD_REMOTEGUI=YES -DBUILD_ALC=YES -DBUILD_ALCC=YES -DBUILD_WXCAS=YES -DENABLE_NLS=YES`) or use `-DBUILD_EVERYTHING=YES`. @@ -93,47 +93,48 @@ The `Debug` build type retains full symbol information. See [Debugging](../debug Build with `-DBUILD_TESTING=YES` (as in the [Debug Build](#debug-build) above), then run: ```sh -ctest --test-dir build --output-on-failure --timeout 10 +ctest --test-dir build --output-on-failure ``` See [Testing](../testing.md) for the full test suite documentation. ## Running the Built Binaries -The compiled `.exe` files are placed in `build/`. Run them directly from the MSYS2 MINGW64 terminal: +The main `.exe` files are placed in `build/src/` (`amuleapi` in `build/src/webapi/`; see [Running Without Installing](index.md#running-without-installing) for the others). Run them directly from the MSYS2 CLANG64 terminal: ```sh -./build/amule.exe -./build/amuled.exe -./build/amuleapi.exe -./build/amulecmd.exe +./build/src/amule.exe +./build/src/amuled.exe +./build/src/webapi/amuleapi.exe +./build/src/amulecmd.exe ``` Which executables are produced depends on the `BUILD_*` options you enabled: [`amule`](../../manual/interfaces/gui/amule.md) (GUI), [`amuled`](../../manual/interfaces/amuled.md) (daemon), [`amulegui`](../../manual/interfaces/gui/amulegui.md) (remote GUI), [`amuleapi`](../../manual/interfaces/amuleapi/index.md) (REST API & Web UI), [`amulecmd`](../../manual/interfaces/amulecmd.md) (CLI), [`amuleweb`](../../manual/interfaces/amuleweb.md) (legacy WebUI), and the [`ed2k`](../../manual/utilities/ed2k.md) link handler. -To run binaries outside the MSYS2 terminal (e.g. by double-clicking in Windows Explorer), the MINGW64 DLLs must be available. Either: +To run binaries outside the MSYS2 terminal (e.g. by double-clicking in Windows Explorer), the CLANG64 DLLs must be available. Either: -1. Add `C:\msys64\mingw64\bin` to the Windows system `PATH`. -2. Or copy the required DLLs next to the executable. The packaging scripts in `packaging/windows/build.sh` handle this automatically for release builds. +1. Add `C:\msys64\clang64\bin` to the Windows system `PATH`. +2. Or install into a folder (`cmake --install build --prefix `), which copies the required DLLs and `ca-bundle.crt` (needed for HTTPS downloads) next to the executables, as `packaging/windows/build.sh` does. -## Notes on the MSYS2 MINGW64 Environment +## Notes on the MSYS2 Environment -All commands must be run inside the **MSYS2 MINGW64** shell. Do not use: +All commands must be run inside the **MSYS2 CLANG64** shell (**CLANGARM64** on ARM64). Do not use: -- **MSYS2 MSYS** — uses a different runtime and does not find MINGW64 packages. -- **MSYS2 UCRT64** — uses the Windows Universal CRT instead of MSVCRT; package names differ (`mingw-w64-ucrt-x86_64-*`). +- **MSYS2 MSYS** — uses a different runtime and does not find CLANG64 packages. +- **MSYS2 MINGW64** — not supported (see the note above). - **Command Prompt** or **PowerShell** — these do not have access to the MSYS2 build tools. +CI does not test **MSYS2 UCRT64**, and its package names differ (`mingw-w64-ucrt-x86_64-*`). + ## Packaging (Portable .zip and Installer) -If you want a redistributable build rather than running the binaries from the build tree, the `packaging/windows/` directory contains helper scripts that produce a portable `.zip` and an NSIS installer. Unlike the manual build above, these scripts use the **MinGW Makefiles** generator (not Ninja — Ninja crashes with `0xc0000142` inside CMake's `try_compile` inner project on this toolchain), build into `build-windows-/`, and disable the test build (`BUILD_TESTING=NO`). +If you want a redistributable build rather than running the binaries from the build tree, the `packaging/windows/` directory contains helper scripts that produce a portable `.zip` and an NSIS installer. Unlike the manual build above, these scripts use the **MinGW Makefiles** generator (not Ninja — Ninja crashes with `0xc0000142` inside CMake's `try_compile` inner project when run from these scripts), build into `build-windows-/`, and disable the test build (`BUILD_TESTING=NO`). -The scripts support two architectures, selected by the `WINDOWS_MSYSTEM` value in `packaging/windows/versions.env` (default `CLANGARM64`): +The scripts support two architectures, selected by `WINDOWS_MSYSTEM` in `packaging/windows/versions.env` (default `CLANGARM64`). `build.sh` stops if it does not match the MSYS2 shell it runs in: | MSYS2 environment | Architecture | |---|---| -| `CLANG64` | x64 (used for the x64 release) | -| `MINGW64` | x64 (limited to wxWidgets 3.2) | +| `CLANG64` | x64 | | `CLANGARM64` | ARM64 (Windows on ARM) | `build.sh` takes a subcommand (`build` is the default): @@ -153,15 +154,15 @@ packaging/windows/build.sh installer packaging/windows/build.sh sign ``` -The `build` step configures CMake, compiles, installs a portable tree (`bin/{amule,amuled,amulegui,amulecmd,ed2k}.exe` plus the MSYS2 DLLs resolved automatically via `file(GET_RUNTIME_DEPENDENCIES)` and a `ca-bundle.crt` for libcurl HTTPS), and zips it. - -To build the x64 release from a CLANG64 shell, either set `WINDOWS_MSYSTEM=CLANG64` in `versions.env` or override it inline: +To build for x64 from a CLANG64 shell, override the default: ```sh WINDOWS_MSYSTEM=CLANG64 packaging/windows/build.sh ``` -The `installer` subcommand requires `makensis` (NSIS 3.x) on `PATH`. See `packaging/windows/README.md` for installer details and remote (SSH) build instructions. +The `build` step configures CMake, compiles, installs a portable tree (the executables under `bin/`, plus the MSYS2 DLLs resolved automatically via `file(GET_RUNTIME_DEPENDENCIES)` and a `ca-bundle.crt` for libcurl HTTPS), and zips it. + +The scripts also need `zip` (`pacman -S zip`). The `installer` subcommand needs NSIS 3.x (`makensis`) and `python`, and `sign` needs `signtool` from the Windows SDK. See `packaging/windows/README.md` for installer details and remote (SSH) build instructions. ### Signing @@ -178,22 +179,12 @@ See `packaging/windows/versions.env` for the full list of signing variables. ## Troubleshooting -### `winsock2.h` Warnings During Build - -You may see warnings like: - -``` -winsock2.h:15: #warning Please include winsock2.h before windows.h -``` - -This is a known interaction between the MSYS2 MINGW64 `winsock2.h` header and wxWidgets 3.2's `wrapwin.h`. CMake defines `WIN32_LEAN_AND_MEAN` to suppress it (done automatically in `CMakeLists.txt`). The warning is harmless and does not indicate a build problem. - ### `crypto++` not found -The MSYS2 package is `mingw-w64-x86_64-crypto++`. Verify it is installed: +The MSYS2 package is `mingw-w64-clang-x86_64-crypto++`. Verify it is installed: ```sh -pacman -Q mingw-w64-x86_64-crypto++ +pacman -Q mingw-w64-clang-x86_64-crypto++ ``` ### CMake Cannot Find Ninja @@ -201,20 +192,20 @@ pacman -Q mingw-w64-x86_64-crypto++ Install the Ninja package and verify: ```sh -pacman -S mingw-w64-x86_64-ninja +pacman -S mingw-w64-clang-x86_64-ninja which ninja ninja --version ``` ### `pkg-config` not found -Install the MINGW64 version: +Install the CLANG64 version: ```sh -pacman -S mingw-w64-x86_64-pkgconf +pacman -S mingw-w64-clang-x86_64-pkgconf ``` -Do not use the generic MSYS2 `pkg-config` — it does not know about the MINGW64 package paths. +Do not use the generic MSYS2 `pkg-config` — it does not know about the CLANG64 package paths. ### Build Directory Must Be Deleted After a Failed Configure diff --git a/docs/developer/debugging.md b/docs/developer/debugging.md index f8a535d..e839c00 100644 --- a/docs/developer/debugging.md +++ b/docs/developer/debugging.md @@ -45,13 +45,13 @@ cmake -B build \ cmake --build build -j"$(nproc)" ``` -The resulting binaries in `build/` contain full symbol information (function names, line numbers, local variable names). They are significantly larger than release builds — this is expected. A Debug build also defines the `__DEBUG__` preprocessor macro, which enables aMule's per-category runtime debug logging (see [Runtime Debug Logging](#runtime-debug-logging) below). +The resulting binaries under `build/src/` contain full symbol information (function names, line numbers, local variable names). They are significantly larger than release builds — this is expected. A Debug build also defines the `__DEBUG__` preprocessor macro, which enables aMule's per-category runtime debug logging (see [Runtime Debug Logging](#runtime-debug-logging) below). :::tip Running Without Installing -All built binaries can be run directly from `build/` during development: +The binaries under `build/src/` can be run directly during development (see [Running Without Installing](compilation/index.md#running-without-installing)): ```sh -./build/amule -./build/amuled +./build/src/amule +./build/src/amuled ``` ::: @@ -93,7 +93,7 @@ These settings are loaded automatically every time GDB starts. ### Running aMule Under GDB ```sh -gdb --args build/amule --disable-fatal +gdb --args build/src/amule --disable-fatal (gdb) run ``` @@ -180,7 +180,7 @@ On macOS the supported debugger is **LLDB**, which ships with the Xcode Command LLDB takes the same role as GDB in this guide — run aMule under it with: ```sh -lldb -- build/amule --disable-fatal +lldb -- build/src/aMule.app/Contents/MacOS/aMule --disable-fatal (lldb) run ``` @@ -240,7 +240,7 @@ valgrind \ --leak-check=full \ --num-callers=20 \ --error-exitcode=1 \ - build/amule + build/src/amule ``` - `--leak-check=full` — show a detailed report for each leak. Note this respects the default `--show-leak-kinds=definite,possible`, so it reports *definitely* and *possibly* lost blocks only. Add `--show-leak-kinds=all` to also include *reachable* and *indirectly lost* blocks. @@ -258,7 +258,7 @@ valgrind \ --tool=memcheck \ --vgdb=yes \ --vgdb-error=1 \ - build/amule + build/src/amule ``` When Valgrind detects the first error, it prints a message with a connection command: @@ -271,7 +271,7 @@ When Valgrind detects the first error, it prints a message with a connection com In a second terminal, run: ```sh -gdb build/amule +gdb build/src/amule (gdb) target remote | vgdb --pid=12345 ``` @@ -287,7 +287,7 @@ Some Valgrind errors originate in third-party libraries (wxWidgets, OpenSSL, X11 valgrind \ --tool=memcheck \ --gen-suppressions=yes \ - build/amule --enable-stdin + build/src/amule --enable-stdin ``` :::caution stdin must stay open @@ -319,7 +319,7 @@ valgrind \ --tool=memcheck \ --leak-check=full \ --suppressions=amule.supp \ - build/amule + build/src/amule ``` ### Recommended Full Invocation @@ -332,7 +332,7 @@ valgrind \ --num-callers=20 \ --suppressions=amule.supp \ --gen-suppressions=yes \ - build/amule --enable-stdin + build/src/amule --enable-stdin ``` On first runs, use `--gen-suppressions=yes` (together with aMule's `--enable-stdin`) to build up the suppression file. Once the file is stable, remove `--gen-suppressions=yes` and use `--error-exitcode=1` to detect regressions. diff --git a/docs/developer/file-formats/fileview.md b/docs/developer/file-formats/fileview.md index 40dc8b4..6ede5bf 100644 --- a/docs/developer/file-formats/fileview.md +++ b/docs/developer/file-formats/fileview.md @@ -17,7 +17,7 @@ cmake -B build -DBUILD_FILEVIEW=ON cmake --build build -j"$(nproc)" ``` -The resulting `fileview` binary is placed in `build/` and installed to `bin/` on `cmake --install`. See the [Compilation](../compilation/index.md) guides for the full build setup. +The resulting `fileview` binary is placed in `build/src/utils/fileview/` and installed to `bin/` on `cmake --install`. See the [Compilation](../compilation/index.md) guides for the full build setup. ## Usage diff --git a/docs/developer/index.md b/docs/developer/index.md index 4491a21..b5ed69a 100644 --- a/docs/developer/index.md +++ b/docs/developer/index.md @@ -158,11 +158,11 @@ cmake --build build -j"$(nproc)" ### Running from the Build Directory -All built binaries are placed in `build/` and can be run directly without installing: +The binaries are placed under `build/src/` and can be run directly without installing: ```sh -./build/amule -./build/amuled --full-daemon +./build/src/amule +./build/src/amuled --full-daemon ``` This is convenient during development — no need to `sudo cmake --install` for every change.