🚀 CLion Configuration Guide for AudioLab¶

Purpose: Complete setup guide for JetBrains CLion IDE optimized for cross-platform C++20 audio development with JUCE and CMake.

Target Audience: AudioLab developers preferring JetBrains IDEs or requiring advanced CMake integration.

Prerequisites: - CLion 2023.3+ (required for C++20 modules support) - CMake 3.28+ - Ninja build system - JUCE 7.0.5+

Why CLion?¶

Advantages over other IDEs:

Feature	CLion	Visual Studio	VSCode
CMake Integration	⭐⭐⭐⭐⭐ Native, best-in-class	⭐⭐⭐ Good	⭐⭐ Requires extensions
Cross-Platform	⭐⭐⭐⭐⭐ Windows/macOS/Linux	⭐⭐ Windows only	⭐⭐⭐⭐⭐ All platforms
Refactoring Tools	⭐⭐⭐⭐⭐ AI-powered	⭐⭐⭐ Good	⭐⭐ Basic
Code Analysis	⭐⭐⭐⭐⭐ Clang-Tidy built-in	⭐⭐⭐⭐ PVS-Studio	⭐⭐⭐ Extensions needed
Debugging	⭐⭐⭐⭐ GDB/LLDB	⭐⭐⭐⭐⭐ MSVC best	⭐⭐⭐⭐ Good
Price	💰 Paid ($199/year)	💰 Free (Community)	💰 Free

Best For: - Teams working on Windows/macOS/Linux simultaneously - Developers prioritizing CMake over solution files - Projects requiring advanced refactoring (rename, extract method, etc.) - Those who prefer JetBrains ecosystem (IntelliJ, PyCharm, etc.)

Initial Setup¶

1. Install CLion¶

Download: jetbrains.com/clion/download

System Requirements: - RAM: 8GB minimum, 16GB+ recommended (CMake indexing is RAM-intensive) - Disk: 3GB for IDE + 5GB for caches - CPU: Multi-core (CLion uses background threads for analysis)

License Options: - Free for students/educators: jetbrains.com/student - Free trial: 30 days - Paid: $199/year (individual), $599/year (organization)

2. First Launch Configuration¶

On first launch, CLion will ask about:

Import Settings: Skip (we'll configure from scratch)
Keymap: Choose based on preference
Default: CLion keymap (recommended)
Visual Studio: For VS users transitioning
macOS: For Mac users
Theme: Choose Dark (better for audio work) or Light
Plugins: Skip for now (we'll install specific ones later)

3. Set Environment Variables¶

Before opening project, ensure:

Windows:

setx JUCE_PATH "C:\JUCE"
setx VST3_SDK_PATH "C:\SDKs\VST_SDK\vst3sdk"

macOS/Linux:

export JUCE_PATH=~/JUCE
export VST3_SDK_PATH=~/SDKs/vst3sdk

# Add to ~/.bashrc or ~/.zshrc for persistence
echo 'export JUCE_PATH=~/JUCE' >> ~/.zshrc
echo 'export VST3_SDK_PATH=~/SDKs/vst3sdk' >> ~/.zshrc

Verify:

echo $JUCE_PATH  # Should print path

4. Open AudioLab Project¶

File → Open → C:\AudioDev\audio-lab

CLion will: 1. Detect CMakeLists.txt 2. Load CMake project 3. Index codebase (5-10 minutes first time) 4. Create .idea/ directory (settings storage)

Wait for indexing to complete (status bar shows progress).

1️⃣ CMake Profiles¶

Path: Settings → Build, Execution, Deployment → CMake

CMake profiles define different build configurations (Debug, Release, etc.).

Profile Configuration¶

Create 3 profiles for AudioLab:

Profile 1: Debug¶

Setting	Value
Name	Debug
Build type	Debug
CMake options	`-DJUCE_DEBUG=1 -DJUCE_ENABLE_ASSERTIONS=1`
Build directory	`build/Debug`
Toolchain	Default (or select specific compiler)
Generator	Ninja
Build options	`-j 16` (parallel jobs, adjust to CPU cores)

Why Debug: - Full debug symbols (.pdb or .dSYM) - Assertions enabled (catches bugs early) - No optimization (easier to step through code) - Use for: Development, debugging crashes, stepping through JUCE

Profile 2: Release¶

Setting	Value
Name	Release
Build type	Release
CMake options	`-DJUCE_OPTIMISE=1 -DJUCE_DISABLE_ASSERTIONS=1`
Build directory	`build/Release`
Toolchain	Default
Generator	Ninja
Build options	`-j 16`

Why Release: - Maximum optimization (-O3 / /O2) - No debug symbols (faster, smaller binaries) - Assertions disabled - Use for: Performance testing, final builds, distribution

Profile 3: RelWithDebInfo (Recommended for Profiling)¶

Setting	Value
Name	RelWithDebInfo
Build type	RelWithDebInfo
CMake options	`-DJUCE_OPTIMISE=1 -DJUCE_DEBUG=1`
Build directory	`build/RelWithDebInfo`
Toolchain	Default
Generator	Ninja
Build options	`-j 16`

Why RelWithDebInfo: - Optimized like Release (-O2) - Debug symbols included (can profile and debug) - Best for: Performance profiling, finding hot spots, optimizing DSP

Advanced CMake Options¶

For all profiles, consider adding:

-DCMAKE_EXPORT_COMPILE_COMMANDS=ON    # For clangd, code analysis
-DJUCE_BUILD_EXAMPLES=OFF              # Skip JUCE examples (faster build)
-DJUCE_BUILD_EXTRAS=OFF                # Skip JUCE tools (Projucer, etc.)
-DCMAKE_CXX_STANDARD=20                # Ensure C++20
-DCMAKE_C_COMPILER=clang               # Use Clang (macOS/Linux)
-DCMAKE_CXX_COMPILER=clang++           # Use Clang++ (faster than GCC)

Environment Variables (pass to CMake):

-DJUCE_PATH=$JUCE_PATH
-DVST3_SDK_PATH=$VST3_SDK_PATH

Switching Profiles¶

Method 1: Bottom toolbar → Select profile dropdown → Choose Debug/Release/RelWithDebInfo

Method 2: Keyboard shortcut - macOS: Cmd+Shift+A → Type "Switch CMake Profile" - Windows/Linux: Ctrl+Shift+A → Type "Switch CMake Profile"

When to switch: - Development: Use Debug - Performance testing: Use RelWithDebInfo - Final build: Use Release

2️⃣ Code Style Configuration¶

Path: Settings → Editor → Code Style → C/C++

Base Style: LLVM (Modified)¶

Scheme dropdown → Select LLVM
Click Duplicate → Name: AudioLab
Apply modifications below:

Tabs and Indents¶

Setting	Value
Tab size	4
Indent	4
Continuation indent	8
Use tab character	❌ OFF (use spaces)

Why 4 spaces: JUCE standard, matches most audio codebases.

Spaces¶

Setting	Value
Before parentheses
- Function declaration	❌ OFF
- Function call	❌ OFF
- if/for/while	✅ ON
Around operators	✅ ON
After comma	✅ ON
Before comma	❌ OFF

Example:

void processBlock(AudioBuffer<float>& buffer, int numSamples)  // No space before (
{
    if (numSamples > 0)  // Space after if
    {
        for (int i = 0; i < numSamples; ++i)  // Spaces around <, +
        {
            buffer.setSample(0, i, 1.0f);  // Spaces after commas
        }
    }
}

Braces¶

Setting	Value
Class/struct declaration	Next line
Function declaration	Next line
if/else/for/while	Next line
Namespace	Same line

Example:

namespace audiolab {  // Namespace: same line

class MyProcessor  // Class: next line
{
public:
    void process()  // Function: next line
    {
        if (condition)  // if: next line
        {
            doSomething();
        }
    }
};

}  // namespace audiolab

Blank Lines¶

Setting	Value
Around class	1
Around function	1
After header	1

Wrapping and Alignment¶

Setting	Value
Right margin (columns)	120
Wrap on typing	✅ ON
Function parameters	Wrap if long
Align parameters	✅ ON

Example:

// Function with many parameters (wrapped and aligned)
void processAudio(AudioBuffer<float>& inputBuffer,
                  AudioBuffer<float>& outputBuffer,
                  int numSamples,
                  double sampleRate,
                  bool shouldNormalize);

Pointer and Reference Alignment¶

Setting	Value
Pointer alignment	Left (Type* var)
Reference alignment	Left (Type& var)

Example:

// Correct (left alignment)
float* data = buffer.getWritePointer(0);
const juce::String& name = plugin.getName();

// Wrong (right alignment)
float *data;      // ❌
String &name;     // ❌

Namespace Indentation¶

Setting	Value
Indent namespace members	❌ OFF

Example:

namespace audiolab {

class MyClass  // Not indented (standard practice)
{
};

}  // namespace audiolab

Access Specifier Indentation¶

Setting	Value
Indent access specifiers	❌ OFF (align with class)

Example:

class MyClass
{
public:  // Not indented (aligns with class brace)
    void publicMethod();

private:  // Same level
    int privateData;
};

Export Code Style¶

Save configuration: 1. Settings → Editor → Code Style → C/C++ 2. Scheme → AudioLab → Gear icon ⚙️ → Export → IntelliJ IDEA code style XML 3. Save as: AudioLab_CodeStyle.xml (in this directory) 4. Commit to Git for team sharing

3️⃣ Inspections & Code Analysis¶

Path: Settings → Editor → Inspections

CLion has powerful static analysis via Clang-Tidy integration.

Enable Critical Inspections¶

C/C++ → Clang-Tidy:

[✅] Enable Clang-Tidy inspections
[✅] Use .clang-tidy file if available

Clang-Tidy checks:
  [✅] performance-*           (all performance checks)
  [✅] modernize-*             (C++11/14/17/20 modernization)
  [✅] readability-*           (code clarity)
  [✅] bugprone-*              (common bugs)
  [✅] clang-analyzer-*        (static analysis)
  [ ] cppcoreguidelines-*     (too strict, optional)

C/C++ → General:

[✅] Unused include directive
[✅] Redundant qualifier
[✅] Mismatched array new/delete
[✅] Suspicious return statement
[✅] Infinite recursion

C/C++ → Code Quality:

[✅] Memory management issues
[✅] Potential memory leak
[✅] Use after free
[✅] Null pointer dereference (when possible)

Disable Noisy Inspections¶

Spelling:

[❌] Typo in string literal
[❌] Typo in comment
Reason: Audio code has many "non-word" terms (ADSR, LFO, VST3, etc.)

Proofreading (if installed):

[❌] Grammar checking
Reason: Comments often use technical shorthand

Configure Clang-Tidy¶

Create .clang-tidy in project root (if not exists):

---
Checks: >
  -*,
  bugprone-*,
  performance-*,
  readability-*,
  modernize-*,
  clang-analyzer-*,
  -modernize-use-trailing-return-type,
  -readability-magic-numbers,
  -readability-implicit-bool-conversion

WarningsAsErrors: ''

HeaderFilterRegex: '.*'

CheckOptions:
  - key:   readability-identifier-naming.ClassCase
    value: CamelCase
  - key:   readability-identifier-naming.FunctionCase
    value: camelBack
  - key:   readability-identifier-naming.VariableCase
    value: camelBack
  - key:   readability-identifier-naming.ConstantCase
    value: UPPER_CASE

Apply: - CLion auto-detects .clang-tidy - Run analysis: Code → Inspect Code

Running Code Analysis¶

Full Project Analysis:

Code → Inspect Code → Whole project → OK
Wait for analysis (5-30 minutes depending on project size)
Review results in Inspection Results panel

Single File Analysis:

Open file → Code → Inspect Code → Current File

Fix Issues: - Click issue → Press Alt+Enter → Select fix - Batch fix: Select multiple issues → Apply Fix

4️⃣ External Tools¶

Path: Settings → Tools → External Tools

Configure external tools for quick access to command-line utilities.

Tool 1: Format with clang-format¶

Purpose: Auto-format code using .clang-format file.

Setting	Value
Name	Format with clang-format
Program	`clang-format` (or full path: `/usr/bin/clang-format`)
Arguments	`-i $FilePath$`
Working directory	$ProjectFileDir$
Output filters	(empty)

Macros Explained: - $FilePath$ : Full path to current file - $ProjectFileDir$ : Project root directory - -i: In-place formatting (modifies file directly)

Usage: - Right-click file → External Tools → Format with clang-format - Or assign keyboard shortcut: Ctrl+Alt+Shift+F

Alternative: Use CLion's built-in formatting: - Code → Reformat Code (Ctrl+Alt+L / Cmd+Option+L)

Tool 2: Run Plugin in Reaper¶

Purpose: Launch Reaper with test project to debug plugin.

Windows: | Setting | Value | |---------|-------| | Name | Run Plugin in Reaper | | Program | C:\Program Files\REAPER (x64)\reaper.exe | | Arguments | $ProjectFileDir$\test_projects\debug.rpp | | Working directory | $ProjectFileDir$ |

macOS: | Setting | Value | |---------|-------| | Program | /Applications/REAPER.app/Contents/MacOS/REAPER | | Arguments | $ProjectFileDir$/test_projects/debug.rpp |

Linux: | Setting | Value | |---------|-------| | Program | /usr/bin/reaper | | Arguments | $ProjectFileDir$/test_projects/debug.rpp |

Usage: - Build plugin first (Ctrl+F9) - Tools → External Tools → Run Plugin in Reaper - Reaper loads with plugin inserted - Attach debugger: Run → Attach to Process → Select reaper

Tool 3: Run PluginVal (VST3 Validator)¶

Purpose: Validate plugin compliance with VST3 standard.

Setting	Value
Name	Validate Plugin (PluginVal)
Program	`pluginval` (or full path)
Arguments	`--strictness-level 5 --validate "$ProjectFileDir$/build/Debug/MyPlugin.vst3"`
Working directory	$ProjectFileDir$

Usage: - After building plugin - Tools → External Tools → Validate Plugin - Check output for warnings/errors - Fix issues before distribution

Tool 4: Generate Doxygen Documentation¶

Purpose: Generate API docs from comments.

Setting	Value
Name	Generate Doxygen Docs
Program	`doxygen`
Arguments	`Doxyfile`
Working directory	`$ProjectFileDir$/docs`

Usage: - Ensure Doxyfile exists in docs/ - Tools → External Tools → Generate Doxygen Docs - Open docs/html/index.html in browser

Assigning Keyboard Shortcuts to External Tools¶

Path: Settings → Keymap

Search: External Tools
Expand → Find your tool (e.g., "Format with clang-format")
Right-click → Add Keyboard Shortcut
Press desired keys (e.g., Ctrl+Alt+Shift+F)
Apply

Suggested Shortcuts: | Tool | Shortcut | |------|----------| | Format with clang-format | Ctrl+Alt+Shift+F | | Run Plugin in Reaper | Ctrl+Alt+R | | Validate Plugin | Ctrl+Alt+V |

5️⃣ Run Configurations¶

Path: Run → Edit Configurations

Run configurations define how to build, run, and debug your project.

Configuration 1: Build Plugin (Default)¶

Type: CMake Application

Setting	Value
Name	Build AudioLab Plugin
Target	`MyPlugin_Standalone` (or your plugin target)
Executable	`MyPlugin_Standalone.exe` (auto-detected)
Program arguments	(empty)
Working directory	$ProjectFileDir$
Environment variables	`JUCE_PATH=C:\JUCE`

Usage: - Click green hammer 🔨 (Shift+F10) to build - Click green play ▶️ (Shift+F10) to run standalone plugin

Configuration 2: Run Unit Tests¶

Type: CMake Application

Setting	Value
Name	Run Unit Tests
Target	`MyPlugin_Tests` (Catch2 test executable)
Executable	`MyPlugin_Tests.exe`
Program arguments	`--reporter console --success`
Working directory	$ProjectFileDir$

Usage: - Run → Run 'Run Unit Tests' - See test results in console - Failed tests highlighted in red

Configuration 3: Debug Plugin in Reaper¶

Type: Custom Build Application

Setting	Value
Name	Debug Plugin in Reaper
Executable	`C:\Program Files\REAPER (x64)\reaper.exe`
Program arguments	`$ProjectFileDir$\test_projects\debug.rpp`
Working directory	$ProjectFileDir$
Before launch	Build (select Debug profile)

Steps: 1. Build plugin (Debug profile) 2. Copy plugin to Reaper VST3 folder (automatic via CMake post-build) 3. Launch Reaper with test project 4. Attach debugger: Run → Attach to Local Process → reaper.exe

Alternative: Use CLion's remote debugger (requires Reaper GDB stub).

Configuration 4: Attach to Process (Generic)¶

Type: Remote Debug

Setting	Value
Name	Attach to Process
Debugger	GDB (Linux), LLDB (macOS), MSVC (Windows)
Process filter	(leave empty, will prompt on launch)

Usage: 1. Run plugin in DAW manually 2. Run → Attach to Process 3. Select DAW process (e.g., Reaper.exe, Ableton Live.exe) 4. Debugger attaches, breakpoints active

Configuration 5: Profile with Perf (Linux Only)¶

Type: Custom Build Application

Setting	Value
Name	Profile with Perf
Executable	`/usr/bin/perf`
Program arguments	`record -g -- $CMakeCurrentProductFile$`
Working directory	$ProjectFileDir$

Usage: - Run → Profile with Perf - Generate perf.data - Analyze: perf report

6️⃣ Recommended Plugins¶

Path: Settings → Plugins → Marketplace

Essential Plugins¶

Plugin	Purpose	Install
.ignore	Syntax highlighting for `.gitignore`	Search → Install
Markdown Navigator Enhanced	Rich markdown editing with preview	Search → Install
String Manipulation	Case conversion, sorting, etc.	Search → Install
CMake Plus	Enhanced CMake support	Search → Install
Rainbow Brackets	Color-matched braces/brackets	Search → Install

Audio Development Plugins (Optional)¶

Plugin	Purpose
Hex Viewer	View binary audio files
BinEd	Hex editor with waveform preview (3^rd party)
PlantUML Integration	UML diagrams from text

Productivity Plugins¶

Plugin	Purpose
Key Promoter X	Learn keyboard shortcuts
GitToolBox	Enhanced Git integration
Presentation Assistant	Display shortcuts during presentations
Code Glance	Minimap (Sublime-style)

Installing Plugins¶

Settings → Plugins → Marketplace
Search plugin name
Click Install
Restart CLion when prompted

7️⃣ Keyboard Shortcuts¶

Essential Shortcuts (Learn These!)¶

Navigation: | Action | Windows/Linux | macOS | |--------|---------------|-------| | Go to file | Ctrl+Shift+N | Cmd+Shift+O | | Go to class | Ctrl+N | Cmd+O | | Go to symbol | Ctrl+Alt+Shift+N | Cmd+Alt+O | | Go to definition | Ctrl+B | Cmd+B | | Find usages | Alt+F7 | Opt+F7 | | Go back | Ctrl+Alt+← | Cmd+[ | | Go forward | Ctrl+Alt+→ | Cmd+] |

Editing: | Action | Windows/Linux | macOS | |--------|---------------|-------| | Comment line | Ctrl+/ | Cmd+/ | | Reformat code | Ctrl+Alt+L | Cmd+Opt+L | | Optimize imports | Ctrl+Alt+O | Ctrl+Opt+O | | Duplicate line | Ctrl+D | Cmd+D | | Delete line | Ctrl+Y | Cmd+Backspace | | Move line up/down | Ctrl+Shift+↑/↓ | Cmd+Shift+↑/↓ |

Build & Run: | Action | Windows/Linux | macOS | |--------|---------------|-------| | Build | Ctrl+F9 | Cmd+F9 | | Run | Shift+F10 | Ctrl+R | | Debug | Shift+F9 | Ctrl+D | | Stop | Ctrl+F2 | Cmd+F2 |

Debugging: | Action | Windows/Linux | macOS | |--------|---------------|-------| | Toggle breakpoint | Ctrl+F8 | Cmd+F8 | | Step over | F8 | F8 | | Step into | F7 | F7 | | Step out | Shift+F8 | Shift+F8 | | Resume | F9 | F9 | | Evaluate expression | Alt+F8 | Opt+F8 |

Refactoring: | Action | Windows/Linux | macOS | |--------|---------------|-------| | Rename | Shift+F6 | Shift+F6 | | Extract method | Ctrl+Alt+M | Cmd+Opt+M | | Extract variable | Ctrl+Alt+V | Cmd+Opt+V | | Inline | Ctrl+Alt+N | Cmd+Opt+N | | Change signature | Ctrl+F6 | Cmd+F6 |

Search: | Action | Windows/Linux | macOS | |--------|---------------|-------| | Search everywhere | Double Shift | Double Shift | | Find in files | Ctrl+Shift+F | Cmd+Shift+F | | Replace in files | Ctrl+Shift+R | Cmd+Shift+R |

Custom Shortcuts (Recommended)¶

How to customize: 1. Settings → Keymap 2. Search action name 3. Right-click → Add Keyboard Shortcut 4. Press desired keys

Suggested: | Action | Shortcut | Why | |--------|----------|-----| | Run External Tool: Format | Ctrl+Alt+Shift+F | Quick formatting | | Run External Tool: Reaper | Ctrl+Alt+R | Launch plugin in DAW | | Switch CMake Profile | Ctrl+Shift+P | Toggle Debug/Release | | Show CMake Tool Window | Alt+C | Quick access to CMake |

8️⃣ Exporting & Importing Settings¶

Exporting Settings (Full)¶

Create settings archive:

File → Manage IDE Settings → Export Settings
Select:
  [✅] Code style schemes
  [✅] Editor → Inspections
  [✅] Editor → Code Style
  [✅] Tools → External Tools
  [✅] Build, Execution, Deployment → CMake
  [✅] Keymap
  [ ] Editor → File templates (optional)

Save as: AudioLab_CLion_Settings.zip
Location: C:\AudioDev\audio-lab\2 - FOUNDATION\03_INFRA\...\clion\

Commit to Git:

cd C:\AudioDev\audio-lab
git add "2 - FOUNDATION/03_INFRA/03_00_development_environment/03_00_01_ide_configurations/clion/AudioLab_CLion_Settings.zip"
git commit -m "Add CLion team settings"
git push

Importing Settings¶

New team member setup:

1. Install CLion
2. Clone AudioLab repository
3. File → Manage IDE Settings → Import Settings
4. Select: AudioLab_CLion_Settings.zip
5. Click OK
6. Restart CLion
7. Open project: C:\AudioDev\audio-lab

Verification: - Check CMake profiles: 3 profiles (Debug, Release, RelWithDebInfo) - Check code style: Settings → Code Style → C/C++ → Scheme: "AudioLab" - Check external tools: Settings → Tools → External Tools → See "Format with clang-format", etc.

Selective Import (Code Style Only)¶

Import just code style XML:

Settings → Editor → Code Style → C/C++
Scheme gear icon ⚙️ → Import Scheme → IntelliJ IDEA code style XML
Select: AudioLab_CodeStyle.xml
Apply

Settings Synchronization (JetBrains Account)¶

For individual use (not recommended for team):

Settings → Settings Sync → Enable Settings Sync
Log in with JetBrains account
Settings stored in cloud, synced across machines

Note: Team should use Git-based settings sharing (export/import), not cloud sync.

Export Script (Automated)¶

Create: export_clion_settings.sh (see next section for full script)

Usage:

cd C:\AudioDev\audio-lab\2 - FOUNDATION\03_INFRA\...\clion
./export_clion_settings.sh

What it exports: - Settings ZIP - Code style XML - CMake profiles (documented in README) - Run configurations (as XML) - External tools (as XML)

Troubleshooting¶

Issue 1: CMake Configuration Failed¶

Symptoms: - "CMake Error: Could not find CMAKE_CXX_COMPILER" - "JUCE_PATH not found"

Solutions:

Check CMake installation:
```
cmake --version  # Should be 3.28+
```
If missing: Install via cmake.org

Check compiler:

# Windows
cl  # Should show MSVC version

# macOS
clang++ --version  # Should show Apple clang

# Linux
g++ --version  # Should show GCC 11+

Set JUCE_PATH:

echo $JUCE_PATH  # Should print /path/to/JUCE
# If empty, add to environment

Reload CMake:
Tools → CMake → Reset Cache and Reload Project

Issue 2: IntelliSense Errors (Red Squiggles)¶

Symptoms: - Valid code shows red underlines - "Cannot resolve symbol" errors - Autocomplete not working

Solutions:

Invalidate caches:

File → Invalidate Caches → Invalidate and Restart
Wait for re-indexing (5-10 minutes)

Check compile_commands.json:
```
# Should exist:
C:\AudioDev\audio-lab\build\Debug\compile_commands.json
```
If missing: Add to CMake options: -DCMAKE_EXPORT_COMPILE_COMMANDS=ON
Check include paths:
Right-click file → Open File in → CMake Settings
Verify include paths include JUCE modules
Force rescan:
Tools → CMake → Rescan CMake Project

Issue 3: Debugger Not Stopping at Breakpoints¶

Symptoms: - Breakpoint icon is hollow (not filled) - Debugger runs past breakpoints - "No debug symbols found"

Solutions:

Check build type:
Switch to Debug profile (not Release)
Release builds strip debug symbols
Rebuild:
```
Build → Rebuild Project
```

Check symbols:

# Windows
dumpbin /symbols MyPlugin.dll | findstr "debug"

# macOS/Linux
nm MyPlugin.so | grep debug

Verify executable path:
Run → Edit Configurations → Check "Executable" points to Debug build

Issue 4: CLion Freezes During Indexing¶

Symptoms: - IDE unresponsive - Status bar: "Indexing... 42%" - High RAM usage (>16GB)

Solutions:

Increase RAM allocation:

Help → Edit Custom VM Options
Add: -Xmx8192m  (8GB RAM for CLion)
Restart CLion

Exclude large directories:

Right-click folder in Project view
→ Mark Directory as → Excluded
Exclude: build/, .git/, third_party/ (if copies)

Disable unnecessary features:

Settings → Tools → Python Integrated Tools → Uncheck
Settings → Languages & Frameworks → JavaScript → Uncheck
(If not using Python/JS in project)

Use SSD:
Move project to SSD (not HDD)
Indexing is I/O intensive

Issue 5: External Tools Not Found¶

Symptoms: - "Cannot run program 'clang-format': No such file or directory" - External tool fails silently

Solutions:

Use full path:

Program: /usr/bin/clang-format  (not just clang-format)

Check PATH:

which clang-format  # Should print path
# If empty, install: sudo apt install clang-format (Linux)

Test command:

clang-format --version  # Should print version

Add to PATH (Windows):

System Environment Variables → PATH → Add C:\Program Files\LLVM\bin
Restart CLion

Advanced Tips¶

Set bookmark: - Press F11 on line - Choose number (0-9) or letter

Go to bookmark: - Press Ctrl+0-9 (or letter)

Use case: Quickly jump between header/implementation, or between different DSP sections.

Tip 2: Use TODO Bookmarks¶

Add TODO:

// TODO: Implement SIMD optimization
// FIXME: Memory leak in buffer allocation
// NOTE: This uses Bark scale, not linear

View TODOs: - View → Tool Windows → TODO - See all TODOs across project

Tip 3: Use Scratch Files for Testing¶

Create scratch: - File → New → Scratch File → C++ - Quick C++ file for testing snippets - Not part of project (no Git tracking)

Use case: Test JUCE API calls, math formulas, algorithm prototypes.

Tip 4: Use Local History as Backup¶

View local history: - Right-click file → Local History → Show History - See all changes (even if not committed to Git)

Revert: - Select old version → Revert

Use case: Accidentally deleted code, want to recover before last commit.

Tip 5: Use Structure View for Large Files¶

Open structure: - View → Tool Windows → Structure - See outline: classes, functions, variables

Use case: Navigate large DSP files (500+ lines).

Resources¶

Official Documentation¶

JUCE-Specific¶

Community¶

AudioLab Discord - #clion channel
AudioLab GitHub Discussions

Checklist: Post-Setup Verification¶

[✅] CLion 2023.3+ installed
[✅] JUCE_PATH environment variable set
[✅] Project opened (C:\AudioDev\audio-lab)
[✅] CMake indexing complete (no errors)
[✅] 3 CMake profiles created (Debug, Release, RelWithDebInfo)
[✅] Code style scheme "AudioLab" active
[✅] Clang-Tidy inspections enabled
[✅] External tools configured (clang-format, Reaper)
[✅] Run configurations created (Build, Tests, Debug)
[✅] Recommended plugins installed (.ignore, Markdown Navigator)
[✅] Keyboard shortcuts customized (optional)
[✅] Settings exported to AudioLab_CLion_Settings.zip
[✅] Can build project (Ctrl+F9)
[✅] Can run standalone (Shift+F10)
[✅] Can debug with breakpoints (Shift+F9)
[✅] IntelliSense autocomplete works (juce::AudioBuffer<float>)
[✅] Code analysis runs without errors (Code → Inspect Code)

If all checked: Ready for AudioLab development! 🎉

AudioLab_CodeStyle.xml - Code style configuration (to be created)
AudioLab_CLion_Settings.zip - Full settings export (to be created)
export_clion_settings.sh - Export automation script (to be created)
run_configurations/ - XML files for run configs (to be created)

Last Updated: 2025-01-XX Author: AudioLab DevOps Team Version: 1.0.0

Questions? Ask in #clion Discord channel or open GitHub issue.

🚀 CLion Configuration Guide for AudioLab¶

📚 Table of Contents¶

Why CLion?¶

Initial Setup¶

1. Install CLion¶

2. First Launch Configuration¶

3. Set Environment Variables¶

4. Open AudioLab Project¶

1️⃣ CMake Profiles¶

Profile Configuration¶

Profile 1: Debug¶

Profile 2: Release¶

Profile 3: RelWithDebInfo (Recommended for Profiling)¶

Advanced CMake Options¶

Switching Profiles¶

2️⃣ Code Style Configuration¶

Base Style: LLVM (Modified)¶

Tabs and Indents¶

Spaces¶

Braces¶

Blank Lines¶

Wrapping and Alignment¶

Pointer and Reference Alignment¶

Namespace Indentation¶

Access Specifier Indentation¶

Export Code Style¶

3️⃣ Inspections & Code Analysis¶

Enable Critical Inspections¶

Disable Noisy Inspections¶

Configure Clang-Tidy¶

Running Code Analysis¶

4️⃣ External Tools¶

Tool 1: Format with clang-format¶

Tool 2: Run Plugin in Reaper¶

Tool 3: Run PluginVal (VST3 Validator)¶

Tool 4: Generate Doxygen Documentation¶

Assigning Keyboard Shortcuts to External Tools¶

5️⃣ Run Configurations¶

Configuration 1: Build Plugin (Default)¶

Configuration 2: Run Unit Tests¶

Configuration 3: Debug Plugin in Reaper¶

Configuration 4: Attach to Process (Generic)¶

Configuration 5: Profile with Perf (Linux Only)¶

6️⃣ Recommended Plugins¶

Essential Plugins¶

Audio Development Plugins (Optional)¶

Productivity Plugins¶

Installing Plugins¶

7️⃣ Keyboard Shortcuts¶

Essential Shortcuts (Learn These!)¶

Custom Shortcuts (Recommended)¶

8️⃣ Exporting & Importing Settings¶

Exporting Settings (Full)¶

Importing Settings¶

Selective Import (Code Style Only)¶

Settings Synchronization (JetBrains Account)¶

Export Script (Automated)¶

Troubleshooting¶

Issue 1: CMake Configuration Failed¶

Issue 2: IntelliSense Errors (Red Squiggles)¶

Issue 3: Debugger Not Stopping at Breakpoints¶

Issue 4: CLion Freezes During Indexing¶

Issue 5: External Tools Not Found¶

Advanced Tips¶

Tip 1: Use Bookmarks for Navigation¶

Tip 2: Use TODO Bookmarks¶

Tip 3: Use Scratch Files for Testing¶

Tip 4: Use Local History as Backup¶

Tip 5: Use Structure View for Large Files¶

Resources¶

Official Documentation¶

JUCE-Specific¶

Community¶

Checklist: Post-Setup Verification¶

Related Files¶