Skip to content

Refine compiling and agent docs #3944

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
ann0see wants to merge 1 commit into
base: main
Choose a base branch
from
+12 −10
Open

Refine compiling and agent docs #3944

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
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
10 changes: 4 additions & 6 deletions AGENTS.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,20 +1,18 @@
# Jamulus — Agent Instructions

Real-time networked music jamming app. Qt/C++ qmake project. Client and server share one codebase; entry point: `src/main.cpp`. Configure `CONFIG` flags in `Jamulus.pro`.
Real-time networked music jamming app. Qt/C++ qmake project. Client and server share one codebase; entry point: `src/main.cpp`. Qt project configuration in `Jamulus.pro`.

**Make the smallest possible change. One logical change per PR. Never mix refactoring with fixes/features.**

Priority order: Stability > Low latency / real-time safety > Backwards compatibility > Maintainability > New features. This order resolves conflicts only — new features are welcome.

---

## Build
## Build and Test

Linux: `qmake && make` (use `qmake-qt5` on Fedora). Headless server: `qmake "CONFIG+=headless serveronly" && make`. First run: `git submodule update --init` (oboe for Android). Run `make distclean` before re-running `qmake` with different `CONFIG` flags. Full per-platform table: `COMPILING.md`.
**Before running a build**, read `COMPILING.md` for your compile target. It includes build commands, platform-specific dependencies and `CONFIG` flags. `.github/autobuild` contains the build scripts for the GitHub Actions workflow. Read these files if you are stuck and need an example.

@mcfnord mcfnord Sep 10, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🤖 AI: The sentence dropped here is the one COMPILING.md does not carry: it calls make distclean optional. Measured on this head (aarch64, Qt 5.15.15): full default build, then qmake "CONFIG+=headless serveronly" and make — 0 objects recompiled, no relink, and the client binary stays in place (-n -c localhost tries to connect). After make distclean the same flags compile 33 objects and the binary rejects -c. Second edit: .github/autobuild/README.md says the scripts modify global system settings and belong in throw-away environments.

Suggested change
**Before running a build**, read `COMPILING.md` for your compile target. It includes build commands, platform-specific dependencies and `CONFIG` flags. `.github/autobuild` contains the build scripts for the GitHub Actions workflow. Read these files if you are stuck and need an example.
**Before running a build**, read `COMPILING.md` for your compile target. It includes build commands, platform-specific dependencies and `CONFIG` flags. Run `make distclean` before re-running `qmake` with different `CONFIG` flags; otherwise `make` rebuilds nothing and the previous configuration's binary stays in place. `.github/autobuild` contains the build scripts for the GitHub Actions workflow. Read these files if you are stuck and need an example, but run them only in a throw-away environment: they modify global system settings (see `.github/autobuild/README.md`).


macOS: `qmake QMAKE_APPLE_DEVICE_ARCHS=arm64 QT_ARCH=arm64 -spec macx-xcode Jamulus.pro` (Use `x86_64` on Intel Macs; `macx-clang` if using `make`). Then `xcodebuild build`, and `macdeployqt ./{Debug,Release}/Jamulus.app`.

**Testing:** run headless server (args `-s -n`), connect a client (e.g. via: `-n -c localhost`; may need jackd running on Linux. Run dummy Jack via: `jackd -d dummy`), exercise the change; use the JSON-RPC API (`docs/JSON-RPC.md`) where possible. Connecting a client needs a non-`serveronly` build (Build section above); `serveronly` rejects `-c`. State what you tested in the PR with evidence. GitHub Actions builds multiple platforms — on failure read the failing step's log.
**Testing:** run headless server (args `-s -n`), connect a client (e.g. via: `-n -c localhost`; may need jackd running on Linux. Run dummy Jack via: `jackd -d dummy`), exercise the change; use the JSON-RPC API (`docs/JSON-RPC.md`) where possible. Connecting a client needs a non-`serveronly` build (Build paragraph above); `serveronly` rejects `-c`. State what you tested in the PR with evidence. GitHub Actions builds multiple platforms — on failure read the failing step's log.

@mcfnord mcfnord Sep 10, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🤖 AI: The paragraph above no longer mentions serveronly; the flag is defined in the "Compile time arguments" table of COMPILING.md.

Suggested change
**Testing:** run headless server (args `-s -n`), connect a client (e.g. via: `-n -c localhost`; may need jackd running on Linux. Run dummy Jack via: `jackd -d dummy`), exercise the change; use the JSON-RPC API (`docs/JSON-RPC.md`) where possible. Connecting a client needs a non-`serveronly` build (Build paragraph above); `serveronly` rejects `-c`. State what you tested in the PR with evidence. GitHub Actions builds multiple platforms — on failure read the failing step's log.
**Testing:** run headless server (args `-s -n`), connect a client (e.g. via: `-n -c localhost`; may need jackd running on Linux. Run dummy Jack via: `jackd -d dummy`), exercise the change; use the JSON-RPC API (`docs/JSON-RPC.md`) where possible. Connecting a client needs a build without `serveronly` (`COMPILING.md`, "Compile time arguments"); `serveronly` rejects `-c`. State what you tested in the PR with evidence. GitHub Actions builds multiple platforms — on failure read the failing step's log.


## Never Do

Expand Down
12 changes: 8 additions & 4 deletions COMPILING.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -110,7 +110,9 @@ You will need Xcode and Qt.

First, install [Xcode from the Mac AppStore](https://apps.apple.com/us/app/xcode/id497799835?mt=12). Then [install homebrew](https://brew.sh/).

After that you can install Qt via homebrew:
**Note** the official Jamulus build uses Qt6. Download and install Qt6, e.g, via the [official open source installer](https://www.qt.io/download-qt-installer). We use Qt5 here as it is easier to set up.

@mcfnord mcfnord Sep 10, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🤖 AI: Reads as: install Qt6, then use Qt5. And autobuild.yml builds macOS with Qt 6.10.2 and, for the legacy Intel artifact, Qt 5.15.2, so "the official build uses Qt6" covers one job of two. Versions are left to the workflow so the doc cannot drift.

Suggested change
**Note** the official Jamulus build uses Qt6. Download and install Qt6, e.g, via the [official open source installer](https://www.qt.io/download-qt-installer). We use Qt5 here as it is easier to set up.
**Note:** the official macOS builds use Qt6, plus Qt5 for the legacy Intel build; the exact versions are in `.github/workflows/autobuild.yml`. The steps below use Qt5 from Homebrew because it is easier to set up. To match the official build instead, install Qt6 via the [official open-source installer](https://www.qt.io/download-qt-installer).


You can install Qt5 via homebrew:

```shell
brew install Qt@5
Expand All @@ -120,6 +122,7 @@ brew link Qt@5 --force
### Generate Xcode Project file

`qmake QMAKE_APPLE_DEVICE_ARCHS=arm64 QT_ARCH=arm64 -spec macx-xcode Jamulus.pro`

**Note:** if you still build on x86_64, not Apple Silicon, you must replace `arm64` with `x86_64`.

### Print build targets and configuration in console
Expand Down Expand Up @@ -149,8 +152,9 @@ Schemes:

`xcodebuild build`

Will build the file and make it available in `./Release/Jamulus.app`
In order to run the application, you need to run `macdeployqt ./Release/Jamulus.app` once to set up all required libraries and frameworks.
Will build the file and make it available in `./Release/Jamulus.app`.

**Note**: To run the application, you need to run `macdeployqt ./Release/Jamulus.app` once to set up all required libraries and frameworks.

@mcfnord mcfnord Sep 10, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🤖 AI: **Note:** on lines 28, 79, 126 and 171; only this one has the colon outside.

Suggested change
**Note**: To run the application, you need to run `macdeployqt ./Release/Jamulus.app` once to set up all required libraries and frameworks.
**Note:** To run the application, you need to run `macdeployqt ./Release/Jamulus.app` once to set up all required libraries and frameworks.


If you want to build the installer, please run the `deploy_mac.sh` script: `./mac/deploy_mac.sh`. You'll find the installer in the deploy/ folder.

Expand Down Expand Up @@ -184,7 +188,7 @@ If you want to build the installer, please run the `deploy_mac.sh` script: `./ma

- Install Qt, including the Android support from the Qt installer
- Follow Qt's [Getting Started with Qt for Android](https://doc.qt.io/qt-5/android-getting-started.html) instructions
- Make sure Jamulus submodules are present, notably oboe:
- **Important**: Make sure Jamulus submodules are present, notably oboe:
`git submodule update --init`
- Open Jamulus.pro in Qt Creator
- Now you should be able to Build & Run for Android.
Expand Down
Loading