From 1136c8ee96a64a7e7f576f0217bed179265ad713 Mon Sep 17 00:00:00 2001 From: ann0see <20726856+ann0see@users.noreply.github.com> Date: Thu, 10 Sep 2026 14:02:50 +0200 Subject: [PATCH] Refine compiling and agent docs --- AGENTS.md | 10 ++++------ COMPILING.md | 12 ++++++++---- 2 files changed, 12 insertions(+), 10 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 2f735bd3a2..5f0a1a01ea 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1,6 +1,6 @@ # 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.** @@ -8,13 +8,11 @@ Priority order: Stability > Low latency / real-time safety > Backwards compatibi --- -## 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. -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. ## Never Do diff --git a/COMPILING.md b/COMPILING.md index d4a10c3bb5..4363b0e976 100644 --- a/COMPILING.md +++ b/COMPILING.md @@ -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. + +You can install Qt5 via homebrew: ```shell brew install Qt@5 @@ -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 @@ -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. 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. @@ -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.