Tutorial 1: installazione e prima build

Cloni shuffle_engine, compili i suoi core puri, esegui i test e un esempio. Non servono una scheda audio, JUCE o Tracktion. Circa 15 minuti, quasi tutti di compilazione.

1. Cosa serve

Strumento	Versione	Note
Compilatore C++	C++20	Visual Studio 2026 (Windows), Xcode con Apple Clang (macOS), GCC o Clang (Linux)
CMake	3.25 o successiva	i preset usano la versione 6 del formato; Visual Studio 2026 include già CMake e Ninja
Ninja	una versione recente	per i preset core-only e linux
Git	qualsiasi	le dipendenze (Catch2 per i test, librerie dei codec, miniaudio, libremidi, header degli SDK dei plugin) vengono scaricate durante la configurazione
Python 3	facoltativo	tools/check_repo.py, solo se modifichi il framework

JUCE 9.0.3 e Tracktion Engine sono facoltativi: shuffle_engine non ne ha mai bisogno. Ti servono solo per gli adapter JUCE e Tracktion, che stanno nel satellite shuffle_juce (lo usano il tutorial 3 e la variante JUCE del tutorial 2).

2. Scarica il codice

git clone https://github.com/ShuffleFramework/shuffle_engine.git
cd shuffle_engine

Su Windows tieni il checkout e le cartelle di build in percorsi brevi (per esempio D:\dev\shuffle_engine): alcuni percorsi generati sono lunghi.

3. Compila solo i core

Il preset core-only compila tutti i core, gli adapter che non usano JUCE (port di piattaforma, socket del sistema operativo, codec, miniaudio, libremidi) e gli esempi che li usano.

cmake --preset core-only
cmake --build --preset core-only
ctest --preset core-only

Su Windows lancia questi comandi da una Developer PowerShell for VS 2026, così Ninja trova il compilatore, oppure usa il preset windows-msvc (passo 4).

ctest esegue tutti i programmi di test e tutti gli esempi. Gli esempi sono test con l’etichetta examples:

ctest --preset core-only -L examples

4. Compila sulla tua piattaforma

Ogni piattaforma desktop ha il suo preset. Nessuno compila codice JUCE.

# Windows (Visual Studio 2026, x64)
cmake --preset windows-msvc
cmake --build --preset windows-msvc
ctest --preset windows-msvc

# macOS (Xcode, universal binary)
cmake --preset macos
cmake --build --preset macos
ctest --preset macos

# Linux (Ninja, Release)
cmake --preset linux
cmake --build --preset linux
ctest --preset linux

Per gli adapter JUCE e Tracktion, clona shuffle_juce accanto a shuffle_engine (trova da solo il checkout ../shuffle_engine) e configuralo con i suoi preset, indicando i tuoi checkout locali (sostituisci i percorsi):

cd ..
git clone https://github.com/ShuffleFramework/shuffle_juce.git
cd shuffle_juce
cmake --preset windows-msvc -DJUCE_HOME=<path to JUCE 9.0.3> -DTRACKTION_HOME=<path to tracktion_engine>

Senza JUCE_HOME la build scarica JUCE alla versione fissata (9.0.3), e senza TRACKTION_HOME scarica Tracktion al commit fissato; vedi Using CMake e il README di shuffle_juce.

Altri preset: ios e android (solo build, vedi Ship on mobile and the web), wasm (i core in WebAssembly, test eseguiti con Node.js), linux-clang-rtsan e linux-clang-asan (controlli real-time e sanitizer su Linux con Clang 20), linux-clang-coverage (copertura del codice per il rapporto di qualità).

5. Lancia un esempio a mano

Gli alberi di build stanno in cmake-build/<preset>/. Con il preset core-only:

./cmake-build/core-only/examples/example_timecode_basics
./cmake-build/core-only/examples/example_setlist_show

Con windows-msvc i programmi sono in cmake-build\windows-msvc\examples\Release\. Ogni esempio stampa quello che fa ed esce con 0. Leggi il suo main.cpp accanto all’output: l’elenco è in examples/README.md.

Cosa hai adesso

• tutti i core compilati e testati sulla tua macchina, pochi millisecondi per test, senza hardware audio;
• gli esempi, che sono il miglior punto di partenza per il tuo codice.

Avanti: Tutorial 2, la tua prima app.

Se qualcosa non va

Sintomo	Soluzione
Could not find toolchain file: .../android.toolchain.cmake	hai scelto il preset android; imposta ANDROID_NDK_HOME oppure scegli un altro preset
la configurazione si ferma durante il download	la build scarica Catch2 e le librerie dei codec; controlla la rete o il proxy, oppure disattiva i codec con -DSHUFFLE_ENGINE_WITH_CODECS=OFF
un test di un dispositivo MIDI o audio si blocca	un servizio MIDI o audio del sistema operativo bloccato può fermare l’elenco dei dispositivi; riavvia quel servizio, oppure escludi i test che aprono dispositivi reali (etichetta engine): ctest --preset windows-msvc -LE engine
un messaggio di errore nella build	leggilo: i controlli in fase di build indicano il file e dicono cosa cambiare