Skip to content

Building from Source

Jump to bottom
avelytchko edited this page Nov 17, 2025 · 1 revision

Building from Source

This guide covers building the foo_mac_scrobble component from source code. Whether you want to contribute, customize the plugin, or understand the build process, this page has you covered.

Prerequisites

System Requirements

  • macOS 12 (Monterey) or later
  • Xcode 15 or later
  • Command Line Tools (installed via Xcode)
  • foobar2000 for macOS (for testing)

Included Dependencies

The repository includes all necessary dependencies:

  • foobar2000 SDK
  • libPPUI (foobar2000 UI library)
  • pfc (core support library)
  • Third-party libraries (in thirdparty/)

No additional package managers or dependencies are required.

Building via Xcode (GUI)

1. Clone the Repository

git clone https://github.com/avelytchko/foo_mac_scrobble.git
cd foo_mac_scrobble

2. Open the Project

open foobar2000/foo_mac_scrobble/foo_mac_scrobble.xcodeproj

3. Configure Build Settings

The project is pre-configured with all necessary settings:

  • SDK: foobar2000 SDK paths are relative to the project
  • Build Configuration: Use Release for production builds
  • Architecture: Universal binary (arm64 + x86_64)
  • Deployment Target: macOS 12.0

4. Select Scheme

In Xcode, ensure the foo_mac_scrobble scheme is selected in the toolbar.

5. Build

Press ⌘B or choose Product → Build from the menu.

6. Locate the Output

After a successful build, the component is located at:

~/Library/Developer/Xcode/DerivedData/foo_mac_scrobble-<HASH>/Build/Products/Release/foo_mac_scrobble.component/

You can reveal it in Finder via Product → Show Build Folder in Finder.

Building via Command Line

The CLI build process mirrors the GitHub Actions workflow.

Basic Build

cd foobar2000/foo_mac_scrobble

xcodebuild -project foo_mac_scrobble.xcodeproj \
  -scheme foo_mac_scrobble \
  -configuration Release \
  -derivedDataPath build

Build with Debug Logging Enabled

xcodebuild -project foo_mac_scrobble.xcodeproj \
  -scheme foo_mac_scrobble \
  -configuration Release \
  -derivedDataPath build \
  OTHER_CPLUSPLUSFLAGS="-DFOO_LASTFM_DEBUG_DEFAULT=1"

Build with Pre-configured API Credentials (CI Build)

xcodebuild -project foo_mac_scrobble.xcodeproj \
  -scheme foo_mac_scrobble \
  -configuration Release \
  -derivedDataPath build \
  OTHER_CPLUSPLUSFLAGS="-DFOO_LASTFM_DEBUG_DEFAULT=1 \
  -DFOO_LASTFM_CI_API_KEY='\"YOUR_API_KEY\"' \
  -DFOO_LASTFM_CI_API_SECRET='\"YOUR_API_SECRET\"'"

Note: Pre-configured credentials are only needed for automated testing. Normal builds don't require this — users enter their own credentials in the preferences UI.

Install to foobar2000

After building, copy the component to your foobar2000 directory:

cp -r build/Build/Products/Release/foo_mac_scrobble.component \
  ~/Library/foobar2000-v2/user-components/foo_mac_scrobble/

Restart foobar2000 to load the component.

Build Configurations

Release (Default)

  • Optimized for performance
  • Debug symbols stripped
  • Suitable for distribution

Debug

  • No optimizations
  • Full debug symbols included
  • Verbose logging enabled

To build Debug configuration:

xcodebuild -project foo_mac_scrobble.xcodeproj \
  -scheme foo_mac_scrobble \
  -configuration Debug \
  -derivedDataPath build

Compiler Flags

The project supports several compile-time flags:

Flag Purpose Default
FOO_LASTFM_DEBUG_DEFAULT Enable debug logging by default 0 (off)
FOO_LASTFM_CI_API_KEY Embed API key (CI only) Not set
FOO_LASTFM_CI_API_SECRET Embed API secret (CI only) Not set

These can be passed via OTHER_CPLUSPLUSFLAGS as shown in the CLI examples above.

Continuous Integration

The project includes a GitHub Actions workflow that:

  1. Checks out the repository
  2. Builds the component with Xcode
  3. Downloads and installs foobar2000
  4. Installs the built component
  5. Runs automated tests (API initialization, queue processing)
  6. Uploads build artifacts

Workflow File

See .github/workflows/build_foobar.yml for the complete workflow configuration.

Automated Testing

The CI workflow includes self-tests that verify:

  • Plugin loads successfully
  • Last.fm API initializes correctly
  • Session management works
  • Queue system processes tracks
  • Network requests are handled properly

Troubleshooting Build Issues

"SDK not found" Error

Ensure Xcode Command Line Tools are installed:

xcode-select --install

Build Fails with Linking Errors

Clean the build folder and try again:

# In Xcode: Product → Clean Build Folder (⌘⇧K)

# Or via CLI:
rm -rf build/
xcodebuild clean -project foo_mac_scrobble.xcodeproj -scheme foo_mac_scrobble

"No such file or directory" for SDK Headers

The foobar2000 SDK paths are relative to the project. Ensure you've cloned the complete repository including all subfolders:

git clone https://github.com/avelytchko/foo_mac_scrobble.git
cd foo_mac_scrobble
ls -la foobar2000/  # Should show the SDK structure

Xcode Won't Open Project

Ensure you're opening the .xcodeproj file, not individual source files:

open foobar2000/foo_mac_scrobble/foo_mac_scrobble.xcodeproj

Next Steps

Questions? Open an issue on GitHub.

Clone this wiki locally