Skip to content

Repository Structure

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

Repository Structure

This page documents the organization of the foo_mac_scrobble repository, explaining the purpose of each directory and key files.

Top-Level Structure

foo_mac_scrobble/
├── .github/                # GitHub-specific files
├── docs/                   # Documentation assets
├── foobar2000/            # Main component source
├── libPPUI/               # foobar2000 UI library
├── pfc/                   # Core utility library
├── .gitignore             # Git ignore rules
├── LICENSE                # MIT License
├── README.md              # Main documentation
├── sdk-license.txt        # foobar2000 SDK license
└── sdk-readme.html        # foobar2000 SDK readme

.github/ Directory

GitHub Actions workflows and issue templates.

.github/
├── workflows/
│   └── build_foobar.yml   # CI/CD build workflow
└── ISSUE_TEMPLATE/
    ├── bug_report.md       # Bug report template
    └── feature_request.md  # Feature request template

workflows/build_foobar.yml

Continuous integration workflow that:

  1. Checks out repository
  2. Builds component with Xcode
  3. Downloads and installs foobar2000
  4. Installs the built component
  5. Runs automated tests
  6. Uploads build artifacts

Triggers:

  • Push to main branch
  • Pull requests
  • Manual workflow dispatch

Build Matrix:

  • macOS: macos-latest (currently macOS 13+)
  • Xcode: Latest stable version

Issue Templates

  • Bug Report: Structured template for reporting bugs
  • Feature Request: Template for suggesting new features

Both templates include:

  • Problem description
  • Expected vs actual behavior
  • System information
  • Steps to reproduce

docs/ Directory

Documentation assets (images, diagrams, etc.).

docs/
└── images/
    ├── logo.png           # Project logo
    ├── preferences.jpg    # Preferences panel screenshot
    ├── auth_flow.jpg      # Authentication flow screenshot
    └── console_log.jpg    # Console debug output screenshot

Usage:

  • Referenced in README.md
  • Used in wiki pages
  • Displayed on GitHub

foobar2000/ Directory

Main component source code.

foobar2000/
├── SDK/                        # foobar2000 SDK headers
├── foo_mac_scrobble/          # Component source
└── foo_sample/                # Sample component (reference)

foobar2000/SDK/

Official foobar2000 SDK headers and libraries.

Key Files:

SDK/
├── foobar2000.h               # Main SDK header
├── play_callback.h            # Playback event interface
├── initquit.h                 # Component lifecycle
├── preferences_page.h         # Preferences UI
├── metadb.h                   # Track metadata
├── console.h                  # Console logging
├── cfg_var.h                  # Configuration variables
└── componentversion.h         # Version macros

Not Modified:

  • SDK files are included as-is from official distribution
  • No changes to SDK headers
  • Used via #include <SDK/...>

foobar2000/foo_mac_scrobble/

The component implementation.

foo_mac_scrobble/
├── Mac/                       # macOS-specific UI
│   ├── fooLastfmMacPreferences.h
│   ├── fooLastfmMacPreferences.mm
│   └── fooLastfmPreferences.xib
├── thirdparty/                # Third-party libraries
│   ├── json.hpp               # nlohmann JSON (single header)
│   ├── md5.h                  # MD5 hashing
│   └── md5.cpp
├── config.h                   # Configuration declarations
├── config.cpp                 # Configuration GUIDs
├── initquit.cpp               # Component lifecycle
├── lastfm_api.h               # Last.fm API client
├── lastfm_api.cpp
├── play_callback.cpp          # Playback event handler
├── scrobble_queue.h           # Offline queue manager
├── scrobble_queue.cpp
├── session_manager.h          # Session persistence
├── session_manager.cpp
├── foo_mac_scrobble.xcodeproj # Xcode project
└── Info.plist                 # Bundle metadata

Core Modules

File Purpose Lines of Code
lastfm_api.* Last.fm Web Services API client ~500
session_manager.* Session key persistence ~150
scrobble_queue.* Offline queue management ~300
play_callback.cpp Playback event hooks ~200
initquit.cpp Lifecycle & worker thread ~250
config.* Configuration GUIDs ~50

macOS UI Layer

File Purpose
fooLastfmMacPreferences.h Preferences view controller header
fooLastfmMacPreferences.mm Objective-C++ implementation
fooLastfmPreferences.xib Interface Builder layout

Third-Party Libraries

Library Version License Purpose
json.hpp 3.11.x MIT JSON serialization

Xcode Project

foo_mac_scrobble.xcodeproj

  • Target: foo_mac_scrobble (Component Bundle)
  • Schemes: Release, Debug
  • Build Settings:
    • SDK: macOS 12.0+
    • Architectures: arm64, x86_64
    • Language: C++17, Objective-C++ with ARC
    • Frameworks: Cocoa, Security, SystemConfiguration
    • Libraries: libcurl (system)

Build Phases:

  1. Compile Sources (C++/Objective-C++)
  2. Link Frameworks
  3. Copy Bundle Resources (.xib)

libPPUI/ Directory

foobar2000's Portable UI library for macOS.

libPPUI/
├── CDialogResizing.h          # Dialog resizing utilities
├── Controls.h                 # Common controls
├── PaintUtils.h               # Drawing utilities
└── ...                        # Additional UI helpers

Purpose:

  • Provides cross-platform UI abstractions
  • Used by foobar2000 SDK for macOS
  • Simplifies Cocoa integration

Usage in Component:

  • Primarily used internally by SDK
  • Component uses native Cocoa for UI

pfc/ Directory

"Portability & Foundation Classes" — Core utility library.

pfc/
├── string_base.h              # String handling
├── pathUtils.h                # File path utilities
├── int_types.h                # Integer type definitions
├── primitives.h               # Basic types
├── bit_array.h                # Bit manipulation
└── ...                        # Additional utilities

Purpose:

  • Cross-platform utility functions
  • String manipulation
  • File I/O helpers
  • Type definitions

Usage in Component:

#include "pfc/string_base.h"
#include "pfc/pathUtils.h"

pfc::string8 session_path = pfc::io::path::combine(
    core_api::get_profile_path(),
    "lastfm_session.json"
);

Configuration Files

.gitignore

Excludes build artifacts and system files:

# Xcode
*.xcworkspace
xcuserdata/
DerivedData/

# Build outputs
build/
*.component/

# macOS
.DS_Store

LICENSE

MIT License:

  • Permits commercial and private use
  • Requires attribution
  • No warranty provided

README.md

Main project documentation:

  • Installation instructions
  • Configuration guide
  • Quick troubleshooting
  • Links to wiki

sdk-license.txt & sdk-readme.html

foobar2000 SDK documentation and license terms.

Build Outputs

Not in repository (generated at build time):

build/                          # CLI build output
├── Build/
│   └── Products/
│       └── Release/
│           └── foo_mac_scrobble.component/

~/Library/Developer/Xcode/DerivedData/  # Xcode build output
└── foo_mac_scrobble-<HASH>/
    └── Build/
        └── Products/
            └── Release/
                └── foo_mac_scrobble.component/

User Data Files

Not in repository (created at runtime):

~/Library/foobar2000-v2/
├── configuration/              # foobar2000 config
│   └── [component settings]
├── user-components/            # Installed components
│   └── foo_mac_scrobble/
│       └── foo_mac_scrobble.component/
├── lastfm_session.json         # Session key
└── lastfm_scrobble_queue.json  # Offline queue

Dependencies Map

foo_mac_scrobble.component
    │
    ├── foobar2000 SDK
    │   ├── Core API (foobar2000.h)
    │   ├── Play Callback (play_callback.h)
    │   ├── Init/Quit (initquit.h)
    │   └── Preferences (preferences_page.h)
    │
    ├── pfc Library
    │   ├── String utilities
    │   └── Path utilities
    │
    ├── libPPUI (via SDK)
    │   └── UI abstractions
    │
    ├── System Frameworks
    │   ├── Cocoa.framework
    │   ├── Security.framework
    │   └── SystemConfiguration.framework
    │
    ├── System Libraries
    │   └── libcurl (HTTP client)
    │
    └── Third-Party
        ├── nlohmann/json (JSON)
        └── md5 (hashing)

Code Organization Principles

Module Boundaries

  • API Client (lastfm_api.*) — Independent, testable
  • Queue (scrobble_queue.*) — Self-contained persistence
  • Session (session_manager.*) — Isolated credential handling
  • Callbacks (play_callback.cpp) — Thin wrapper around SDK
  • Lifecycle (initquit.cpp) — Orchestration layer

Header Organization

// 1. System headers
#include <Foundation/Foundation.h>
#include <string>

// 2. foobar2000 SDK
#include "SDK/foobar2000.h"
#include "SDK/play_callback.h"

// 3. Utility libraries
#include "pfc/string_base.h"

// 4. Third-party
#include "thirdparty/json.hpp"

// 5. Project headers
#include "lastfm_api.h"
#include "scrobble_queue.h"

File Naming Conventions

  • C++ headers: .h (e.g., lastfm_api.h)
  • C++ source: .cpp (e.g., lastfm_api.cpp)
  • Objective-C++ headers: .h (e.g., fooLastfmMacPreferences.h)
  • Objective-C++ source: .mm (e.g., fooLastfmMacPreferences.mm)
  • Interface Builder: .xib (e.g., fooLastfmPreferences.xib)

Source Line Counts

Approximate line counts (excluding comments and blank lines):

Category Lines
Core C++ Logic ~1,500
macOS UI (Objective-C++) ~400
Third-party (included) ~1,000
Total Component ~2,900
foobar2000 SDK (used) ~50,000+
pfc Library (used) ~20,000+

Version Control

Branching Strategy

  • main — Stable releases
  • develop — Active development (if used)
  • feature/* — Feature branches
  • testing/* — Testing branches

Commit Guidelines

  • Clear, descriptive commit messages
  • Reference issues when applicable
  • Atomic commits (one logical change per commit)

Release Process

  1. Update version in main.cpp and project.pbxproj
  2. Update CHANGELOG.md
  3. Create release tag: v0.x.x
  4. Build and upload release assets
  5. Update documentation

Related Documentation

Questions about the structure? Open an issue on GitHub.

Clone this wiki locally