Skip to content

Version Locations in AudioLab

Overview

The AudioLab version number must be synchronized across multiple files and artifacts. This document identifies all locations where the version appears.

Critical Rule: All locations MUST display the same version. Inconsistency causes confusion and debugging nightmares.

Version Format Standard

MAJOR.MINOR.PATCH[-PRERELEASE][+BUILD]

Example: 2.1.3-beta.2

Primary Version Source (Single Source of Truth)

CMakeLists.txt (Root)

Location: c:\AudioDev\audio-lab\CMakeLists.txt

Format: 

project(audio_lab VERSION 2.1.3 LANGUAGES CXX)

Extraction Pattern: 

# Extract version using regex
$content = Get-Content CMakeLists.txt
$content -match 'project\(audio_lab VERSION (\d+)\.(\d+)\.(\d+)'
$major = $matches[1]
$minor = $matches[2]
$patch = $matches[3]

Access in CMake: 

${PROJECT_VERSION}        # "2.1.3"
${PROJECT_VERSION_MAJOR}  # "2"
${PROJECT_VERSION_MINOR}  # "1"
${PROJECT_VERSION_PATCH}  # "3"

Secondary Locations (Must Be Synchronized)

1. Version Header File

Location: 2 - FOUNDATION/04_CORE/04_11_state_serialization/04_11_01_versioning/version.hpp

Format: 

#pragma once

namespace audiolab {

constexpr int VERSION_MAJOR = 2;
constexpr int VERSION_MINOR = 1;
constexpr int VERSION_PATCH = 3;
constexpr const char* VERSION_PRERELEASE = "beta.2"; // Empty for stable
constexpr const char* VERSION_BUILD = "";            // Build metadata

// Full version string
constexpr const char* VERSION_STRING = "2.1.3-beta.2";

// Numeric version for comparisons (MMmmpp format)
// Example: 2.1.3 → 020103
constexpr int VERSION_NUMERIC = (VERSION_MAJOR * 10000) +
                                 (VERSION_MINOR * 100) +
                                  VERSION_PATCH;

} // namespace audiolab

Usage in Code: 

#include "version.hpp"

void printVersion() {
    std::cout << "AudioLab v" << audiolab::VERSION_STRING << std::endl;
}

bool isCompatible(int fileVersion) {
    return fileVersion <= audiolab::VERSION_NUMERIC;
}

2. Plugin Metadata (JUCE)

Location: 2 - FOUNDATION/05_PLUGINS/[PluginName]/JucePlugin_Config.h

Format: 

#define JucePlugin_VersionString        "2.1.3"
#define JucePlugin_VersionCode          0x20103  // Hex: MAJOR.MINOR.PATCH

Calculation: 

// Version code in hex: 0xMMmmpp
// 2.1.3 → 0x020103 → 131331 (decimal)

DAW Visibility: - Shows in plugin manager - Used for plugin identification - Critical for preset compatibility

3. Package Metadata

vcpkg.json

Location: c:\AudioDev\audio-lab\vcpkg.json

Format: 

{
  "name": "audiolab",
  "version-string": "2.1.3-beta.2",
  "description": "AudioLab DSP Framework"
}

4. Documentation

Main README.md

Location: c:\AudioDev\audio-lab\README.md

Format: 

# AudioLab v2.1.3

Audio DSP framework and plugin suite.

**Current Version:** 2.1.3-beta.2

Doxygen Configuration

Location: docs/Doxyfile

Format: 

PROJECT_NUMBER = "2.1.3-beta.2"

5. Installer Configuration

Windows (InnoSetup)

Location: 03_13_02_build_packaging/installer_configs/windows_inno_setup.iss

Format: 

#define MyAppVersion "2.1.3"
#define MyAppPublisher "AudioLab Team"

macOS (Packages)

Location: 03_13_02_build_packaging/installer_configs/macos_packages.json

Format: 

{
  "version": "2.1.3",
  "build": "20231015.a3f8b92"
}

Linux (AppImage)

Location: 03_13_02_build_packaging/installer_configs/linux_appimage.yml

Format: 

version: 2.1.3
release: beta.2

6. About Dialog (UI)

Location: 2 - FOUNDATION/05_PLUGINS/[PluginName]/UI/AboutDialog.cpp

Format: 

#include "version.hpp"

AboutDialog::AboutDialog() {
    versionLabel.setText(
        "AudioLab v" + String(audiolab::VERSION_STRING),
        dontSendNotification
    );
}

7. Git Tags

Format: 

v2.1.3       # Stable release
v2.1.3-beta.2 # Pre-release

Creation: 

git tag -a v2.1.3 -m "Release version 2.1.3"
git push origin v2.1.3

Verification: 

git describe --tags
# Output: v2.1.3-5-ga3f8b92
# Meaning: 5 commits after tag v2.1.3, commit a3f8b92

8. Changelog

Location: c:\AudioDev\audio-lab\CHANGELOG.md

Format: 

# Changelog

## [2.1.3] - 2023-10-15

### Added
- New reverb algorithm

### Fixed
- Audio clicks on bypass (#123)

9. Build Artifacts (Filenames)

Installer Files: 

AudioLab-2.1.3-Setup-Windows-x64.exe
AudioLab-2.1.3-Setup-macOS-arm64.dmg
AudioLab-2.1.3-VST3-Linux-x64.tar.gz

Archive Files: 

audiolab-2.1.3-src.zip
audiolab-2.1.3-docs.zip

Update Checklist

When bumping version from 2.1.3 to 2.2.0:

Pre-Update

  • Determine version bump (MAJOR/MINOR/PATCH)
  • Update CHANGELOG.md with changes
  • Commit all pending changes

Update Process

  • Run version_bump.ps1 minor (automated)
  • OR manually update:
  • CMakeLists.txt: project(audio_lab VERSION 2.2.0)
  • version.hpp: Update all constants
  • JucePlugin_Config.h: Update version string and code
  • vcpkg.json: Update version-string
  • README.md: Update version badge/header
  • Doxyfile: Update PROJECT_NUMBER
  • Installer configs (InnoSetup, Packages, AppImage)
  • About dialog (if hardcoded)
  • CHANGELOG.md: Add [2.2.0] section header

Verification

  • Run version_verify.ps1 to check consistency
  • Build project: cmake --build build
  • Check About dialog shows new version
  • Check installer filename contains new version

Finalize

  • Commit: git commit -m "chore: bump version to 2.2.0"
  • Tag: git tag -a v2.2.0 -m "Release version 2.2.0"
  • Push: git push && git push --tags

Verification Script

Script: version_verify.ps1

# Extract version from each location and compare

$cmake = (Get-Content CMakeLists.txt | Select-String 'VERSION (\d+\.\d+\.\d+)').Matches.Groups[1].Value
$hpp = (Get-Content version.hpp | Select-String 'VERSION_STRING = "([^"]+)"').Matches.Groups[1].Value
$vcpkg = (Get-Content vcpkg.json | ConvertFrom-Json).'version-string'

Write-Host "CMakeLists.txt: $cmake"
Write-Host "version.hpp:    $hpp"
Write-Host "vcpkg.json:     $vcpkg"

if ($cmake -eq $hpp -and $hpp -eq $vcpkg) {
    Write-Host "✓ All versions consistent" -ForegroundColor Green
} else {
    Write-Host "✗ Version mismatch detected!" -ForegroundColor Red
    exit 1
}

Common Mistakes

❌ Updating Only CMakeLists.txt

Problem: About dialog shows old version Solution: Update version.hpp

❌ Forgetting Git Tag

Problem: Can't identify release commit later Solution: Always tag releases

❌ Inconsistent Pre-release Labels

Problem: CMake says "2.1.3", installer says "2.1.3-beta.2" Solution: Decide: either all include pre-release or none

❌ Hardcoding Version in UI

Problem: Must remember to update UI code Solution: Always read from version.hpp

Automation

The version_bump.ps1 script automates updating all these locations. See version_bump.ps1 for implementation.

Usage: 

# Increment PATCH: 2.1.3 → 2.1.4
.\version_bump.ps1 patch

# Increment MINOR: 2.1.4 → 2.2.0
.\version_bump.ps1 minor

# Increment MAJOR: 2.2.0 → 3.0.0
.\version_bump.ps1 major

# Set pre-release: 2.2.0 → 2.2.0-beta.1
.\version_bump.ps1 pre-release beta.1

# Remove pre-release: 2.2.0-beta.1 → 2.2.0
.\version_bump.ps1 release

Best Practices

  1. Single Source of Truth: CMakeLists.txt is authoritative
  2. Generate, Don't Duplicate: Generate version.hpp from CMake when possible
  3. Automate: Use version_bump.ps1 to avoid manual errors
  4. Verify: Run version_verify.ps1 before every release
  5. Tag Immediately: Create Git tag right after version bump commit

Remember: Version inconsistency is a debugging nightmare. Automate to prevent human error.