Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
11 changes: 6 additions & 5 deletions docs/developer/compilation/bsd.md
Original file line number Diff line number Diff line change
Expand Up @@ -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 \
Expand All @@ -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
Expand Down
11 changes: 6 additions & 5 deletions docs/developer/compilation/index.md
Original file line number Diff line number Diff line change
Expand Up @@ -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)
Expand Down Expand Up @@ -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.
Expand Down
11 changes: 6 additions & 5 deletions docs/developer/compilation/linux.md
Original file line number Diff line number Diff line change
Expand Up @@ -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 \
Expand All @@ -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
Expand Down
13 changes: 7 additions & 6 deletions docs/developer/compilation/macos.md
Original file line number Diff line number Diff line change
Expand Up @@ -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 \
Expand Down Expand Up @@ -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).
Expand Down
115 changes: 53 additions & 62 deletions docs/developer/compilation/windows.md
Original file line number Diff line number Diff line change
Expand Up @@ -3,52 +3,56 @@ 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

### Install MSYS2

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 \
Expand All @@ -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`.

Expand All @@ -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 <dir>`), 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-<arch>/`, 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-<arch>/`, 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):
Expand All @@ -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

Expand All @@ -178,43 +179,33 @@ 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

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

Expand Down
Loading