Installare Flutter da zero: SDK, flutter doctor e primo progetto

Vai su docs.flutter.dev/get-started/install e scegli il tuo sistema operativo. Scarica l'archivio dell'SDK stabile (canale stable) ed estrailo in una cartella senza spazi e senza caratteri accentati nel percorso.

Percorsi consigliati:

Sistema	Percorso consigliato
Windows	C:\src\flutter
macOS / Linux	~/development/flutter

⚠️ Evita C:\Program Files\ su Windows: richiede permessi elevati e Flutter avrà problemi a scrivere nella propria cartella.

In alternativa puoi clonare il repository ufficiale con Git (comodo per aggiornare l'SDK in futuro) usando il comando qui sotto.

# macOS / Linux
mkdir -p ~/development && cd ~/development
git clone https://github.com/flutter/flutter.git -b stable

# Windows (PowerShell)
# mkdir C:\src ; cd C:\src
# git clone https://github.com/flutter/flutter.git -b stable

Perché il comando flutter funzioni da qualsiasi terminale devi aggiungere la cartella flutter/bin alla variabile d'ambiente PATH.

Windows: cerca "Modifica le variabili di ambiente per il tuo account" → seleziona Path → Modifica → Nuovo → inserisci C:\src\flutter\bin → conferma e riapri il terminale.

macOS / Linux: aggiungi la riga di export al file di configurazione della tua shell (~/.zshrc per zsh, ~/.bashrc per bash), poi ricarica la shell.

Infine verifica con flutter --version: la prima esecuzione scarica alcune dipendenze e può richiedere qualche minuto.

# Aggiungere al PATH (zsh su macOS)
echo 'export PATH="$HOME/development/flutter/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc

# Verifica
flutter --version
# Flutter 3.x.x • channel stable • https://github.com/flutter/flutter.git
# Tools • Dart 3.x.x • DevTools 2.x.x

flutter doctor è il diagnostico integrato: controlla tutti i componenti necessari e ti dice cosa manca.

Legenda dei simboli:

• ✓ (verde): componente a posto.
• ! (giallo): funziona ma manca qualcosa di opzionale (es. Xcode se non sviluppi per iOS).
• ✗ (rosso): blocco reale, va risolto.

Usa flutter doctor -v per il dettaglio completo: mostra i percorsi rilevati ed è fondamentale per capire perché un controllo fallisce.

💡 Non serve avere tutto verde: se sviluppi solo per Android su Windows, la riga di Xcode resterà segnalata e va benissimo.

flutter doctor

# Esempio di output:
# [✓] Flutter (Channel stable, 3.x.x, on macOS 14)
# [✗] Android toolchain - develop for Android devices
#     ✗ cmdline-tools component is missing
# [!] Xcode - develop for iOS and macOS
# [✓] Chrome - develop for the web
# [✓] VS Code (version 1.9x)
# [✓] Connected device (2 available)

flutter doctor -v   # versione dettagliata

L'errore rosso più comune riguarda la toolchain Android. Procedi così:

1. Installa Android Studio (include SDK e strumenti da riga di comando).
2. Aprilo → Settings → Languages & Frameworks → Android SDK → SDK Tools → spunta Android SDK Command-line Tools (latest) e Android SDK Platform-Tools → Apply.
3. Accetta le licenze dal terminale con flutter doctor --android-licenses (rispondi y a tutte).
4. Installa i plugin Flutter e Dart in Android Studio, oppure l'estensione Flutter se usi VS Code.

Su macOS, per sviluppare anche per iOS: installa Xcode dall'App Store, poi esegui i comandi di configurazione qui sotto.

Rilancia flutter doctor dopo ogni correzione fino a eliminare i simboli rossi che ti interessano.

# Licenze Android
flutter doctor --android-licenses

# Solo macOS, per il supporto iOS
sudo xcode-select --switch /Applications/Xcode.app/Contents/Developer
sudo xcodebuild -runFirstLaunch
sudo gem install cocoapods

Ora crei l'app. Il nome del progetto deve essere in snake_case (minuscolo, con underscore): mia_prima_app va bene, MiaPrimaApp no.

Il comando genera la struttura standard:

• lib/main.dart → il punto di ingresso, dove scriverai il codice Dart.
• pubspec.yaml → dipendenze, asset e metadati del progetto.
• android/, ios/, web/ → i progetti nativi per ogni piattaforma.
• test/ → i test automatici.

Con l'opzione --platforms puoi limitare le piattaforme generate e mantenere il progetto più leggero.

cd ~/progetti
flutter create mia_prima_app
cd mia_prima_app

# Solo alcune piattaforme:
# flutter create --platforms=android,ios,web mia_prima_app

# Scarica le dipendenze dichiarate in pubspec.yaml
flutter pub get

Controlla i dispositivi disponibili con flutter devices. Se non ne vedi nessuno:

• Emulatore Android: aprilo dal Device Manager di Android Studio, oppure via terminale con flutter emulators --launch <id>.
• Dispositivo fisico Android: attiva Opzioni sviluppatore → Debug USB, collega il cavo e autorizza il computer.
• Simulatore iOS (solo macOS): open -a Simulator.
• Web: usa flutter run -d chrome, non serve alcun emulatore ed è il modo più rapido per partire.

Lancia flutter run: la prima build è lenta (compila anche la parte nativa), le successive saranno molto più veloci.

flutter devices
flutter emulators
flutter emulators --launch Pixel_7_API_34

# Avvio
flutter run              # sceglie/chiede il dispositivo
flutter run -d chrome    # sul browser

# Durante l'esecuzione, nel terminale:
#  r  -> hot reload
#  R  -> hot restart
#  q  -> esci

Apri lib/main.dart nell'editor e sostituisci il contenuto con il codice qui sotto: una app minimale che mostra un testo al centro dello schermo.

Cosa fa il codice:

• runApp() monta il widget radice e avvia l'applicazione.
• MaterialApp fornisce tema, routing e le convenzioni Material Design.
• Scaffold dà la struttura base della schermata (appBar, body).
• Center + Text mostrano il messaggio.

Salva il file (Ctrl/Cmd + S): con flutter run attivo l'hot reload aggiorna l'app in meno di un secondo, mantenendo lo stato. Cambia il testo o il Colors.indigo in Colors.teal e osserva il risultato immediato.

import 'package:flutter/material.dart';

void main() {
  runApp(const MiaPrimaApp());
}

class MiaPrimaApp extends StatelessWidget {
  const MiaPrimaApp({super.key});

  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      title: 'Mia Prima App',
      debugShowCheckedModeBanner: false,
      theme: ThemeData(
        colorSchemeSeed: Colors.indigo,
        useMaterial3: true,
      ),
      home: const HomePage(),
    );
  }
}

class HomePage extends StatelessWidget {
  const HomePage({super.key});

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(title: const Text('Benvenuto in Flutter')),
      body: const Center(
        child: Text(
          'Ambiente configurato correttamente! 🎉',
          textAlign: TextAlign.center,
          style: TextStyle(fontSize: 20),
        ),
      ),
    );
  }
}