Building from Source

How to get a debug build of Bòcan on your Mac. The full reference is DEVELOPMENT.md in the main repository.

Prerequisites

Tool	Version	Where to get it
Mac	Apple Silicon (arm64)	Intel is not supported
Xcode	27	App Store or developer.apple.com
Swift	6.2 or later	Comes with Xcode
Homebrew	Any	brew.sh

All other tools (SwiftLint, SwiftFormat, XcodeGen, xcbeautify, FFmpeg, Chromaprint) are installed by make bootstrap from the Brewfile.

First setup

git clone https://github.com/bocan/bocan-music.git
cd bocan-music

# project.yml refers to Secrets.xcconfig, so the project cannot be
# generated without it. The empty defaults in the template are sufficient.
cp Secrets.xcconfig.template Secrets.xcconfig

# Install the tools and git hooks, bundle fpcalc and the FFmpeg
# libraries, and generate Bocan.xcodeproj.
make bootstrap

# Print the tool versions and check the version pins.
make doctor

Build and run

make build      # Debug build
make open       # Open the project in Xcode

Run make generate when you change project.yml, or when you add files to Tests/AppTests, UITests, or Resources. Do not edit the .pbxproj file by hand.

Common commands

Command	What it does
make help	Show all targets
make build	Debug build
make format	Format all Swift files
make lint	SwiftLint (strict) and the source audits
make format-check	SwiftFormat lint, with no file changes
make test	Xcode unit tests
make test-coverage	Tests with the 80% coverage gate
make tests	Format, lint, and the full test matrix
make clean	Remove build artefacts

More about the test targets is in Testing.

Optional API keys

The app builds and runs with an empty Secrets.xcconfig. Add keys only for the functions you want to work on:

Key	Function	Without it
ACOUSTID_API_KEY	Identify Track (AcoustID lookup)	Fingerprint lookup does not work
BOCAN_LASTFM_API_KEY and BOCAN_LASTFM_SHARED_SECRET	Last.fm scrobbling	Last.fm does not connect
PODCAST_INDEX_API_KEY and PODCAST_INDEX_API_SECRET	Podcast search through Podcast Index	Search uses the iTunes catalogue only

Never commit Secrets.xcconfig.

Things to know

• Your debug build has its own library. The debug build is sandboxed and keeps its data in ~/Library/Containers/io.cloudcauldron.bocan/. The installed release app uses ~/Library/Application Support/Bocan/. The two can run at the same time, so make sure you know which one you look at.
• FFmpeg is pinned to a major version. The pin is in .ffmpeg-major, and make doctor checks it. After an FFmpeg or Chromaprint upgrade in Homebrew, run make bundle-fpcalc again.
• Logs. In Console.app, filter by the subsystem io.cloudcauldron.bocan. In the app, use Help → Log Console (⌘⇧L).
• The pre-commit hook does not catch lint errors. It runs gitleaks and SwiftFormat, but its SwiftLint step checks nothing. make lint does. Run it before you push.

Contributing

Read CONTRIBUTING.md before you open a pull request. In short:

1. Open or find an issue first, to discuss the idea.
2. Work on a short-lived branch named <type>/<slug>. Never commit to main.
3. Use Conventional Commits. The scope is the module, for example fix(subsonic): retry failed logins.
4. One logical change for each pull request.
5. A feat, fix, or perf pull request adds a user-facing note under ## [Unreleased] in CHANGELOG.md.
6. make lint && make test-coverage must pass locally.

The full branch and release flow is in The Bòcan Release Process. Security problems go through SECURITY.md, not the public issue tracker.