README: add binary-install path + bandwidth-limit setup note by got3nks · Pull Request #527 · amule-project/amule

got3nks · 2026-05-05T18:28:09Z

Summary

aMule 3.0.0 ships pre-built binaries for every desktop, but the README still routes new users straight to the source-build instructions. Most users want a download, not a CMake invocation.

This PR restructures the README's installation flow into two clearly-marked options and adds a binary-install deep-dive doc, plus links the User Guide at docs/README.md to the matching binary-install sections so the headless-tools setup commands are accessible no matter which package format the reader installed.

What's in the README

The old ## Compiling section becomes ## Installation with two sub-sections:

Pre-built binaries (recommended) — minimal "download, run" hints per platform, link to the new deep-dive doc.
Building from source — existing CMake quick-start, retained verbatim, links to the existing docs/INSTALL.md.

The ## Setting Up section gains a second numbered step covering bandwidth limits — aMule ships with MaxUpload=0 and MaxDownload=0 (both interpreted as literal unlimited since #461 / #491), which is the right default for benchmarking but hostile on a residential line. Recommend ~80 % of line speed with a concrete 100/20 Mbps fibre example. The same advice already exists in docs/README.md; this just surfaces it on the front page where new users actually look.

What's in `docs/INSTALL_BINARIES.md` (new)

A ## Contents TOC at the top with anchored links into every section so the doc is navigable as a reference.

Per-platform install walkthroughs with the common pitfalls:

Platform	Pitfall covered
Linux AppImage	FUSE not installed (`libfuse2t64` / `libfuse2` / `fuse` / `fuse2` per distro)
Linux Flatpak	sandbox vs filesystem grants — `--filesystem=home` is in the manifest, so state lives in `~/.aMule/` exactly like a native install (existing config picked up automatically)
Linux distro packages	still 2.3.3 in most distro repos vs 3.0.0+ on Releases
macOS .dmg	unsigned binary; macOS 15 (Sequoia) removed the Control-click → Open bypass, supported path is now System Settings → Privacy & Security → Open Anyway. macOS 14 and earlier still support the Control-click flow. `xattr -d com.apple.quarantine` works on every version.
Windows .zip	SmartScreen "Windows protected your PC" → More info → Run anyway
Any	SHA-256 verification recipe (`sha256sum` / `shasum -a 256` / `certutil`)

A new ## Running the headless tools section covers how to invoke amuled / amulecmd / amulegui / amuleweb from each binary package — the wiki / User-Guide setup commands assume $PATH (true for make install, false for any binary package), and the path / dispatch pattern differs between formats:

Format	How a non-default binary is reached
Windows portable .zip	`.\amuled.exe`, `.\amulecmd.exe`, … all sit alongside in the unzipped folder
macOS .dmg	`/Applications/aMule.app/Contents/MacOS/amuled` (and friends); `amulegui` is the separate `aMuleGUI.app` bundle. Optional `/usr/local/bin` symlinks for short names.
Linux AppImage	argv[0]-dispatch: `ln -s aMule-*.AppImage amuled && ./amuled …` (already implemented in `packaging/linux/appimage/AppRun`)
Linux Flatpak	`flatpak run --command=amuled org.amule.aMule …`

What's in `docs/README.md` (User Guide)

Intro now links both INSTALL_BINARIES.md (binaries) and INSTALL.md (source); previously only the source-build doc was referenced.
"Running aMule headless" gains a short paragraph noting the $PATH assumption and four bullet links to the per-format anchors in INSTALL_BINARIES.md. The package-format detail lives only in INSTALL_BINARIES.md so the User Guide stays a thin pointer.

Verification

MaxUpload / MaxDownload defaults of 0 verified at src/Preferences.cpp:1020-1021
Flatpak --filesystem=home grant verified at packaging/linux/flatpak/org.amule.aMule.yaml.in
AppImage argv[0] dispatch verified at packaging/linux/appimage/AppRun:38-45
macOS .app layout (CLI binaries copied into Contents/MacOS/, aMuleGUI.app shipped separately) verified at packaging/macos/build.sh:103-119,146
macOS 15 Gatekeeper change verified against Apple's current support article
Release-asset filename patterns previewed against Packaging run 26888630567 on master tip ed15edb43; placeholder names in INSTALL_BINARIES.md aligned in 60aafb09e to match the actual artifact names produced by the workflow. The final spot-check against the real 3.0.0 release draft is still pending (see Test plan).

Test plan

Three README changes for users coming to aMule for the first time: 1. Top-level README: restructure "Compiling" -> "Installation" with two options — pre-built binaries (recommended for most users) and building from source (existing flow). Each lists minimum commands and links to its own deep-dive doc. 2. Top-level README: surface the unlimited-bandwidth defaults in the "Setting Up" section. aMule ships with MaxUpload=0 / MaxDownload=0, both interpreted as literal unlimited since the throttler rewrites in 3.0.0. On a residential line that means saturating the link and starving every other application; recommend setting limits to ~80% of line speed with a concrete 100/20 Mbps fibre example. 3. INSTALL_BINARIES.md: new "Running the headless tools" section covering how to invoke amuled / amulecmd / amulegui / amuleweb from a Windows .zip, macOS .dmg, Linux AppImage, or Linux Flatpak — paths and dispatch patterns differ between formats, and the wiki/setup commands previously assumed PATH (i.e. `make install`). Added a Contents TOC for navigation; linked the four per-format sub-headings from docs/README.md so the User Guide stays a thin pointer rather than duplicating the package-format detail.

…DME (#94) The Connection Speed section's recommendation and math examples were outdated: - Recommended setting only the upload cap ("You don't need to set a maximum download speed") while aMule actually ships with MaxUpload=0 AND MaxDownload=0 (literal-unlimited since the throttler rewrites in 3.0.0). On a connection aMule can saturate, the unlimited-download default starves every other application on the link. - Math example used an old 1024 kb/s / 512 kb/s ADSL profile and the "divide by 8 to get kB/s from kb/s" formulation. Modern fibre is the more realistic baseline, and ISP marketing is almost always in Mbps (not kb/s) today. Align with the README's "Set bandwidth limits" subsection (PR amule-project/amule#527): - Surface the unlimited defaults explicitly, with the link-starvation rationale plus the TCP-ACK angle for uncapped uploads. - Recommend setting both upload and download to ~80% of line speed. - Replace the kb/s ÷ 8 math with Mbps × 125, and the example with a 100/20 Mbps fibre line.

…lease-asset names Audited the placeholder names in this doc against the artifact filenames produced by the Packaging workflow on a clean upstream master tip (run 26888630567). Three of five didn't match: - AppImage: `aMule-<version>-<arch>.AppImage` -> the actual file ships with a `Linux-` infix: `aMule-<version>-Linux-<arch>.AppImage`. Updated the download instruction + the `chmod +x` / `./` invocation glob + the symlink-tutorial example. - Flatpak: same `Linux-` infix missing -> updated to `aMule-<version>-Linux-<arch>.flatpak`. - Windows installer: `aMule-<version>-Setup-<arch>.exe` -> the actual filename has a `Windows-` infix before `Setup`: `aMule-<version>-Windows-Setup-<arch>.exe`. Updated the download instruction + the certutil checksum command. Also nudged the placeholder arch values from `x86_64` / `aarch64` (the uname spelling) to `x64` / `arm64` (the spelling used in the release-asset filenames). The AppRun symlink dispatcher tolerates both spellings -- documented that explicitly alongside the symlink examples so users who follow muscle memory from earlier docs aren't misled. macOS Universal2 `.dmg` and Windows portable `.zip` already matched.

got3nks · 2026-06-08T08:52:42Z

@mrjimenez after 3.0.0 is released, we'll have to verify the filenames match what's documented in INSTALL_BINARIES.md.

…ect#527) * fix(amuleweb): restart Asio service before worker startup The synchronous EC connection can leave the process-global io_context in the stopped state before amuleweb creates its HTTP server. Worker threads then return from run() immediately, leaving port 4711 listening but never accepting requests. Restart the io_context before launching the long-lived worker pool so queued HTTP accepts are processed. * docs(asio): correct synchronous EC restart comment --------- Co-authored-by: Gerald B Cox <[email protected]>

got3nks force-pushed the pr-readme-binary-install branch 5 times, most recently from bf00dc0 to dcc244f Compare May 6, 2026 07:53

got3nks mentioned this pull request May 6, 2026

packaging.yml: ship aMuleGUI.app in macOS Universal2 .dmg #529

Merged

3 tasks

got3nks force-pushed the pr-readme-binary-install branch 3 times, most recently from f3a62ba to dcc3c86 Compare May 7, 2026 09:21

got3nks mentioned this pull request May 27, 2026

Publish aMule 3.0.0 pre-release packages #734

Closed

got3nks force-pushed the pr-readme-binary-install branch 2 times, most recently from e34a3ec to 75ac254 Compare May 28, 2026 07:29

got3nks force-pushed the pr-readme-binary-install branch from 75ac254 to 3ebaa46 Compare June 3, 2026 14:03

got3nks mentioned this pull request Jun 3, 2026

docs(quickstart-guide): update bandwidth-limit rationale to match README amule-org/amule-org.github.io#94

Merged

got3nks marked this pull request as ready for review June 4, 2026 19:42

got3nks mentioned this pull request Jun 4, 2026

List of tasks before aMule 3.0.0 release amule-org/amule-org.github.io#4

Closed

13 tasks

mrjimenez merged commit 1791d2b into amule-project:master Jun 8, 2026
7 checks passed

got3nks deleted the pr-readme-binary-install branch June 8, 2026 10:33

Navigation Menu

Uh oh!

README: add binary-install path + bandwidth-limit setup note - #527

README: add binary-install path + bandwidth-limit setup note#527
mrjimenez merged 2 commits into
amule-project:masterfrom
got3nks:pr-readme-binary-install

got3nks commented May 5, 2026 •

edited

Loading

Uh oh!

Uh oh!

got3nks commented Jun 8, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Uh oh!

Conversation

got3nks commented May 5, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

What's in the README

What's in docs/INSTALL_BINARIES.md (new)

What's in docs/README.md (User Guide)

Verification

Test plan

Uh oh!

Uh oh!

got3nks commented Jun 8, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

got3nks commented May 5, 2026 •

edited

Loading

What's in `docs/INSTALL_BINARIES.md` (new)

What's in `docs/README.md` (User Guide)