Guia de instalação

Já tens alguma destas ferramentas?

Quem vem do 1.º ano tem muitas vezes o VS Code instalado; o Git, em regra, não. Num terminal (menu Iniciar → Terminal):

git --version
code --version

• Git "não é reconhecido": o caso habitual. Instalar o Git for Windows (Passo 1).
• Git responde com 2.4x ou superior: está feito. Confirmar que o Credential Manager existe (git config --global credential.helper deve responder manager); se não, reinstalar o Git for Windows por cima.
• VS Code já instalado: Help → Check for Updates (a extensão Flutter precisa de uma versão recente) e passar diretamente ao Passo 2, o Flutter SDK, que é um download de 2 GB e convém começar cedo.
• Projetos antigos em Documentos ou no OneDrive: não faz mal; os desta UC vão para C:\dev.

Ordem recomendada na aula 1

Os downloads são a parte lenta. Arranca-os por esta ordem nos primeiros minutos da aula e deixa-os correr durante a teoria. Os tamanhos são aproximados.

Instalar pela mesma ordem à medida que os downloads terminam. O Android Studio pode ficar a descarregar o SDK em segundo plano enquanto o resto se instala.

Windows, passo a passo

Testado com Windows 10 e 11 de 64 bits. Precisas de uma conta com permissão para instalar programas.

Passo 1: Git, VS Code e Android Studio

1. Git for Windows. Corre o instalador com as opções por defeito, com duas confirmações: em Choosing the default editor escolhe Use Visual Studio Code as Git's default editor (se o VS Code já estiver instalado; senão deixa o Vim, muda-se depois), e confirma que Git Credential Manager está selecionado. É ele que te vai deixar entrar no GitHub pelo browser sem escrever passwords.
2. Visual Studio Code. Instalador User Installer. Marca Add to PATH e Add "Open with Code" action. No fim, abre-o e instala a extensão Flutter (autor Dart Code) pelo menu Extensions, Ctrl+Shift+X, escrevendo "Flutter" na caixa de pesquisa. É a primeira da lista.

   

3. Android Studio. Instalador com as opções por defeito. No primeiro arranque escolhe a instalação Standard e aceita as licenças: descarrega o SDK, as platform-tools e um emulador. Deixa correr; volta aqui quando terminar. No fim aparece o ecrã inicial abaixo.

   

4. Modo de programador do Windows. O Flutter precisa dele para criar symlinks quando compila plugins. Abre o menu Iniciar, escreve Definições de programador (ou corre start ms-settings:developers num terminal) e liga o interruptor Modo de programador; confirma o aviso. Sem isto, mais tarde aparece o erro Building with plugins requires symlink support.

Passo 2: Flutter SDK pelo VS Code

1. No VS Code abre a paleta de comandos, Ctrl+Shift+P, escreve flutter new e escolhe Flutter: Create New Project (a documentação ainda lhe chama "Flutter: New Project"; é o mesmo comando).

   

2. Quando perguntar pelo SDK, escolhe Download SDK.
3. Na janela de pasta escolhe C:\dev. O SDK fica em C:\dev\flutter.
4. Carrega em Clone Flutter e espera. Se parecer parado mais de 15 minutos, cancela e repete.
5. Quando aparecer, carrega em Add SDK to PATH. Se aparecer um aviso sobre Google Analytics, carrega em OK.
6. Fecha o VS Code e todos os terminais e volta a abrir. O PATH só se aplica a janelas novas.
7. Abre um terminal novo (menu Iniciar → Terminal ou PowerShell) e confirma:

   flutter --version

   Deve responder com Flutter 3.4x e Dart 3.1x. Se disser que flutter não é reconhecido, vê os problemas frequentes.

Passo 3: SDK do Android e licenças

1. No Android Studio: ecrã inicial → menu de três pontos (More Actions) → SDK Manager. Abre a janela Settings na secção Android SDK.

   

2. Separador SDK Platforms: a plataforma mais recente (API 36 ou superior) deve estar com o estado Installed. A linha Android SDK Location no topo diz onde o SDK ficou; anota-a.

   

3. Separador SDK Tools: marca Android SDK Command-line Tools (latest), além de Build-Tools, Platform-Tools e Emulator, e carrega em Apply e depois OK. As command-line tools são o componente que mais vezes falta.

   

4. Num terminal aceita as licenças, respondendo y a todas:

   flutter doctor --android-licenses

5. Diagnóstico:

   flutter doctor

   Precisas de ✓ em Flutter, Android toolchain e Android Studio. Avisos sobre Visual Studio (é para apps de desktop Windows) e Chrome podem ser ignorados.

O que é o PATH, e quando é que precisas de mexer nele

Quando escreves flutter num terminal, o Windows tem de descobrir onde está o programa com esse nome. Procura-o numa lista de pastas chamada PATH. Se a pasta C:\dev\flutter\bin não estiver nessa lista, o Windows responde que o comando não é reconhecido, mesmo com o Flutter instalado.

O PATH é uma variável de ambiente: um valor com nome, guardado pelo Windows, que todos os programas podem ler. Não é um ficheiro que edites; altera-se numa janela de definições. O botão Add SDK to PATH do VS Code faz essa alteração por ti, e em regra não precisas de fazer mais nada. Só mexes à mão se, num terminal novo, flutter --version continuar a dizer que o comando não é reconhecido.

Alterar o PATH à mão (só se precisares)

1. Abre o menu Iniciar e escreve variáveis de ambiente. Escolhe Editar as variáveis de ambiente da conta (em inglês, Edit environment variables for your account). Abre-se a janela Variáveis de Ambiente.
2. Na metade de cima, Variáveis de utilizador, seleciona a linha Path e carrega em Editar….
3. Na janela seguinte carrega em Novo, escreve C:\dev\flutter\bin e carrega em OK. Depois OK na janela anterior, e OK outra vez.
4. Fecha todos os terminais e o VS Code, abre um terminal novo e corre flutter --version.

Passo 4: Windows Defender e antivírus

O Defender analisa cada ficheiro que o Flutter e o Gradle escrevem, e isso torna a primeira compilação muito mais lenta; alguns antivírus chegam a apagar o flutter.bat. Adiciona C:\dev às exclusões: Definições → Privacidade e segurança → Segurança do Windows → Proteção contra vírus e ameaças → Gerir definições → Exclusões → Adicionar pasta.

macOS, passo a passo

1. Terminal: xcode-select --install. Instala as ferramentas de linha de comandos, que incluem o Git. Em Mac com chip Apple, se for pedido, instala também o Rosetta: softwareupdate --install-rosetta.
2. Instala o VS Code e a extensão Flutter.
3. Instala o Android Studio com a instalação Standard.
4. No VS Code: ⌘+Shift+P → Flutter: Create New Project → Download SDK → pasta ~/dev → Clone Flutter → Add SDK to PATH. Fecha e reabre o Terminal.
   Alternativa manual: extrai o zip para ~/dev e corre echo 'export PATH="$HOME/dev/flutter/bin:$PATH"' >> ~/.zprofile.
5. SDK Manager do Android Studio: Android SDK Command-line Tools. Depois flutter doctor --android-licenses e flutter doctor.
6. Opcional, para iOS: instala o Xcode pela App Store (mais de 10 GB), depois sudo sh -c 'xcode-select -s /Applications/Xcode.app/Contents/Developer && xcodebuild -runFirstLaunch', sudo xcodebuild -license, xcodebuild -downloadPlatform iOS e o CocoaPods. Não é obrigatório na UC.

Linux (Ubuntu e Debian), passo a passo

1. Pacotes de base:

   sudo apt-get update -y && sudo apt-get upgrade -y
   sudo apt-get install -y curl git unzip xz-utils zip libglu1-mesa

2. Instala o VS Code (pacote .deb) e a extensão Flutter; instala o Android Studio com a instalação Standard.
3. No VS Code: Ctrl+Shift+P → Flutter: Create New Project → Download SDK → pasta ~/dev → Clone Flutter → Add SDK to PATH. Fecha e reabre o terminal.
   Alternativa manual: tar -xf ~/Downloads/flutter_linux_*-stable.tar.xz -C ~/dev/ e echo 'export PATH="$HOME/dev/flutter/bin:$PATH"' >> ~/.bashrc.
4. SDK Manager: Android SDK Command-line Tools. Depois flutter doctor --android-licenses e flutter doctor.
5. Para o telemóvel por USB: sudo apt-get install -y android-sdk-platform-tools-common e sudo usermod -aG plugdev $USER; termina a sessão e volta a entrar.

Git e GitHub

Em todos os sistemas. O objetivo é conseguires clonar, alterar, fazer commit e push a partir do VS Code até ao fim da semana.

1. Conta GitHub. Cria uma em github.com/signup com o teu email da escola ou pessoal. O nome de utilizador vai aparecer no teu currículo: escolhe um que possas mostrar a um empregador. Confirma o email.
2. Identidade nos commits. Num terminal, com o teu nome e o email da conta GitHub:

   git config --global user.name "Nome Apelido"
   git config --global user.email "o-teu-email@exemplo.pt"
   git config --global init.defaultBranch main

   Se instalaste o Git antes do VS Code, define agora o editor: git config --global core.editor "code --wait".
3. Teste completo. No GitHub, carrega em New repository, chama-lhe pdm-teste, marca Add a README file e cria. Copia o URL do repositório (botão verde Code → HTTPS). Depois, no VS Code: paleta de comandos → Git: Clone → cola o URL → escolhe a pasta C:\dev (ou ~/dev) → Open quando perguntar.

   

4. Se aparecer um aviso amarelo Restricted Mode ao abrir a pasta, carrega em Manage e depois em Trust. O VS Code faz esta pergunta a qualquer pasta que ainda não conhece; sem confiar, as extensões, incluindo a do Flutter, ficam desligadas.

   

5. Edita o README.md, acrescenta uma linha, grava (Ctrl+S). Abre a vista Source Control: ícone dos três círculos ligados na barra da esquerda, ou paleta → View: Show Source Control. Escreve uma mensagem na caixa, carrega em Commit e depois em Sync Changes (ou Publish Branch).

   

6. Na primeira vez o Git Credential Manager abre o browser para autorizares o acesso ao GitHub. Autoriza. Não voltas a precisar de password neste computador.
7. Abre o repositório no GitHub e confirma que a alteração lá está. A partir daqui o Git está a funcionar.

Onde correr a app: telemóvel ou emulador

Precisas de um dos dois até à aula de sexta-feira; na primeira aula não é necessário nenhum. O telemóvel é mais rápido e mais real; o emulador serve se não tiveres Android ou cabo, mas pede um portátil com 16 GB de RAM para ser agradável.

Opção A: telemóvel Android

1. Opções de programador. Definições → Acerca do telemóvel → carrega 7 vezes em Número de compilação (em alguns modelos está em Informações do software ou Versão).
2. Depuração USB. Definições → Sistema → Opções de programador → Depuração USB. Em Xiaomi e Redmi ativa também Instalar via USB.
3. Cabo. Usa um cabo de dados; muitos cabos baratos só carregam. No telemóvel escolhe Transferência de ficheiros se perguntar, e aceita Permitir depuração USB para este computador, com "Permitir sempre".
4. Windows: se o telemóvel não aparecer no passo seguinte, instala o driver USB do fabricante. Para Google Pixel e muitos outros, o Google USB Driver instala-se pelo SDK Manager, separador SDK Tools.
5. Confirma:

   flutter devices

   Deve aparecer o modelo com android-arm64. Se aparecer unauthorized, há um pedido à espera no ecrã do telemóvel.

Opção B: emulador Android

1. No Windows, o emulador precisa da Plataforma de Hipervisor do Windows. O Android Studio pede para a ativar na primeira vez e reinicia o computador. Se não pedir: menu Iniciar → Ativar ou desativar funcionalidades do Windows → marca Plataforma de Hipervisor do Windows → OK → reinicia.
2. Ecrã inicial do Android Studio → menu de três pontos → Virtual Device Manager. Abre o Device Manager; carrega no + para criar um dispositivo.

   

3. Escolhe Medium Phone ou um Pixel recente, Next, aceita a imagem de sistema sugerida (descarrega cerca de 1 GB), Finish.

   

4. Arranca-o pelo triângulo no Device Manager. Quando o ecrã do Android aparecer, confirma num terminal:

   flutter emulators
   flutter devices

Verificação e primeira app

O terminal pode ser o do Windows (menu Iniciar → Terminal ou PowerShell) ou o do VS Code: menu Terminal → New Terminal, ou Ctrl+`. É o mesmo.

1. Diagnóstico completo:

   flutter doctor -v

2. Cria e corre a app de exemplo, dentro da pasta de trabalho:

   cd C:\dev
   flutter create ola_mobile
   cd ola_mobile
   flutter run

   No macOS e Linux, cd ~/dev. Se houver mais do que um dispositivo (telemóvel e emulador), o Flutter pergunta qual usar. A primeira compilação descarrega o Gradle e demora vários minutos. Quando a app abrir, carrega no botão + e vê o contador subir.
3. Com a app a correr, abre a pasta ola_mobile no VS Code, edita lib/main.dart, muda um texto, grava, e carrega em r no terminal. A alteração aparece no telemóvel sem reiniciar: é o hot reload.

Problemas frequentes

Se nada disto resolver: resolução de problemas oficial, ou o fórum do Moodle com a mensagem de erro completa.

Checklist da semana 1