Setup ambiente di sviluppo su WSL

Guida per far girare il sito Jekyll da WSL, replicabile da zero.

Contesto e problema

Il repository si trova su un percorso Windows OneDrive che contiene spazi:

/mnt/c/Users/FabioCannas/OneDrive - Alveo/progetti 20260616/azuremeetupcasteddu/azuremeetupcasteddu.github.io

Ruby/Bundler non gestiscono gli spazi nel percorso di installazione delle gem. Con la configurazione di default (BUNDLE_PATH: "vendor/bundle", cioè gem installate dentro la cartella del progetto) l’avvio fallisce con:

/usr/lib/ruby/3.3.0/bundled_gems.rb:69:in `require': cannot load such file -- /mnt/c/Users/FabioCannas/OneDrive (LoadError)

Il percorso viene troncato al primo spazio (.../OneDrive), da cui il LoadError.

Soluzione: installare le gem in un percorso senza spazi nel filesystem nativo di WSL (la home utente), lasciando il codice dov’è su OneDrive.

Prerequisiti

Se Ruby non è installato:

sudo apt update
sudo apt install -y ruby-full build-essential

Setup passo-passo

Esegui i comandi da un terminale WSL, dalla cartella del progetto.

# 1. Vai nella cartella del progetto (attenzione agli spazi: usa le virgolette)
cd "/mnt/c/Users/FabioCannas/OneDrive - Alveo/progetti 20260616/azuremeetupcasteddu/azuremeetupcasteddu.github.io"

# 2. Scegli una cartella per le gem FUORI dal percorso con spazi (filesystem nativo WSL)
GEMDIR="$HOME/.bundle-gems/azuremeetupcasteddu"
mkdir -p "$GEMDIR"

# 3. Configura Bundler per usare quel percorso (salvato in .bundle/config, locale al repo)
bundle3.3 config set --local path "$GEMDIR"

# 4. Installa le dipendenze
bundle3.3 install

# 5. Verifica
bundle3.3 exec jekyll -v      # -> jekyll 3.10.0

Alias di comodità (opzionale)

Dato che esiste solo bundle3.3, aggiungi degli alias alla tua ~/.bashrc:

cat >> ~/.bashrc <<'EOF'

# Ruby 3.3 bundler convenience aliases (no plain 'bundle' on PATH)
alias bundle=bundle3.3
alias bundler=bundler3.3
EOF

source ~/.bashrc

Dopodiché puoi usare direttamente bundle e bundler.

Avviare il sito in locale

bundle exec jekyll serve

Il sito è raggiungibile su http://127.0.0.1:4000 (o l’URL indicato nell’output).

Nota: il codice è su /mnt/c (OneDrive), quindi le build sono più lente e a volte il rilevamento automatico delle modifiche non funziona. In quel caso usa il polling:

bundle exec jekyll serve --force_polling

Note importanti