Instalação, configuração do ambiente e o comando `go`

Antes de escrever código, o ambiente que precisaremos deve estar pronto. Muitos iniciantes pulam esta etapa com pressa e pagam o preço depois — erros misteriosos que têm origem em variáveis de ambiente mal configuradas, versões conflitantes ou caminhos incorretos. Dedicar atenção à instalação correta poupa horas de frustração futura.

Go tem uma das instalações mais simples entre linguagens modernas. Não há máquina virtual para instalar, não há gerenciador de pacotes obrigatório, não há dependências externas. Um único arquivo baixado do site oficial é suficiente para ter tudo funcionando.

Instalação no Linux

A forma recomendada no Linux é baixar o tarball oficial e extraí-lo manualmente. Isso garante que você está usando a versão mais recente e tem controle total sobre o local de instalação.

Abra o terminal e execute os comandos abaixo, substituindo a versão pelo número mais atual disponível em https://go.dev/dl:

# Remova qualquer instalação anterior
sudo rm -rf /usr/local/go

# Baixe a versão desejada (ajuste o número conforme o site oficial)
wget https://go.dev/dl/go1.27.1.linux-amd64.tar.gz

# Extraia para /usr/local
sudo tar -C /usr/local -xzf go1.27.1.linux-amd64.tar.gz

Agora adicione o Go ao PATH. Edite o arquivo ~/.bashrc ou ~/.zshrc (dependendo do seu shell) e adicione ao final:

export PATH=$PATH:/usr/local/go/bin:$HOME/go/bin

O segundo caminho, $HOME/go/bin, não é do Go em si: é para onde o go install copia as ferramentas que você instalar mais tarde, como o golangci-lint ou o dlv. Sem ele no PATH, a instalação termina sem erro e o terminal continua respondendo que o comando não existe.

Recarregue o shell:

source ~/.bashrc

Instalação no macOS

No macOS, a forma mais direta é usar o instalador .pkg disponível em https://go.dev/dl. Baixe o arquivo, abra e siga as instruções — o instalador cuida do PATH automaticamente.

Quem prefere usar o Homebrew pode instalar com um único comando:

brew install go

Para verificar qual versão foi instalada:

brew info go

Instalação no Windows

No Windows, baixe o instalador .msi em https://go.dev/dl. Execute o arquivo e siga o assistente. O instalador adiciona Go ao PATH automaticamente.

Após a instalação, abra o Prompt de Comando ou PowerShell e verifique:

go version

Verificando a instalação

Independentemente do sistema operacional, o comando de verificação é sempre o mesmo:

go version

A saída esperada é algo como:

go version go1.27.1 linux/amd64

Se esse comando funcionar, o Go está instalado e acessível no PATH. Se o terminal responder com "comando não encontrado", o problema está na configuração do PATH.

Entendendo o GOPATH e o GOROOT

Esses dois conceitos causam confusão em iniciantes, mas são simples quando explicados com clareza.

GOROOT é o diretório onde o Go foi instalado — normalmente /usr/local/go no Linux e macOS. Você raramente precisará mexer nele diretamente.

GOPATH era, nas versões antigas do Go, o diretório onde todos os projetos e dependências ficavam armazenados. Desde o Go 1.11, com a introdução dos Go Modules, o GOPATH perdeu importância central. Hoje ele guarda duas coisas: os binários instalados com go install, em ~/go/bin, e o cache de módulos baixados, em ~/go/pkg/mod — o go env GOMODCACHE mostra o caminho. Os seus projetos podem ficar em qualquer pasta.

O valor padrão do GOPATH é ~/go (uma pasta chamada go dentro do seu diretório pessoal). Você pode verificar com:

go env GOPATH

Para ver todas as variáveis de ambiente do Go de uma vez:

go env

O comando go: sua principal ferramenta

O executável go não é apenas um compilador. Ele é um conjunto completo de ferramentas para compilar, testar, formatar, documentar e gerenciar dependências. Conhecer seus subcomandos principais é essencial.

go version        # Mostra a versão instalada
go env            # Lista todas as variáveis de ambiente do Go
go build          # Compila o pacote ou programa atual
go run arquivo.go # Compila e executa em uma única etapa
go test           # Executa os testes do pacote atual
go fmt            # Formata o código seguindo o padrão oficial
go vet            # Analisa o código em busca de erros comuns
go install        # Compila e instala um binário
go get            # Adiciona ou atualiza uma dependência
go mod init       # Inicializa um novo módulo Go
go mod tidy       # Remove dependências não usadas e adiciona as faltantes
go doc            # Exibe documentação de pacotes e funções

Cada um desses subcomandos aceita flags adicionais. Para explorar as opções de qualquer subcomando:

go help build
go help test

Criando o primeiro projeto com Go Modules

Desde o Go 1.16, os módulos são o padrão absoluto para gerenciar projetos. Criar um projeto novo é direto:

# Crie um diretório para o projeto
mkdir meu-primeiro-projeto
cd meu-primeiro-projeto

# Inicialize o módulo
go mod init meu-primeiro-projeto

O comando go mod init cria um arquivo chamado go.mod com o seguinte conteúdo inicial:

module meu-primeiro-projeto

go 1.27.1

Esse arquivo é o coração do módulo. Ele registra o nome do módulo e a versão mínima do Go necessária. Quando dependências externas forem adicionadas, elas também aparecerão aqui.

Agora crie o arquivo principal:

touch main.go

Edite main.go com o seguinte conteúdo:

package main

import "fmt"

func main() {
    fmt.Println("Projeto Go inicializado com sucesso.")
}

Para executar sem compilar explicitamente:

go run .

O ponto significa “o pacote desta pasta”. Muitos tutoriais usam go run main.go, que funciona enquanto o programa cabe num arquivo só; quando surgir um segundo arquivo no pacote, digamos um util.go com uma função usada pelo main, esse comando compila apenas o main.go e falha com undefined para tudo o que está no outro arquivo. O go run . compila o pacote inteiro.

Para compilar e gerar um binário executável:

go build -o meu-app
./meu-app

A flag -o define o nome do binário gerado. Sem ela, o nome vem do caminho do módulo, e não da pasta: um módulo github.com/fulano/meu-app gera meu-app mesmo que a pasta se chame outra coisa.

Escolhendo um editor

Go funciona bem com qualquer editor que tenha suporte à linguagem. As duas opções mais usadas pela comunidade são:

Visual Studio Code com a extensão oficial golang.go. Oferece autocompletar, navegação de código, execução de testes inline, depuração integrada e formatação automática ao salvar. É a escolha mais popular entre iniciantes e profissionais.

GoLand da JetBrains. Uma IDE comercial dedicada exclusivamente ao Go. Possui recursos avançados de refatoração e análise estática. Recomendada para quem trabalha em projetos de grande porte.

Para instalar a extensão no VS Code, abra o painel de extensões e pesquise por Go. Após instalar, o editor solicitará a instalação das ferramentas auxiliares (gopls, dlv, staticcheck). Aceite todas: o gopls, servidor de linguagem que alimenta o autocompletar, é mantido pela equipe do Go; o dlv (Delve, o depurador) e o staticcheck são projetos da comunidade, adotados como padrão pela própria extensão.

Estrutura recomendada de um projeto simples

Não existe uma estrutura obrigatória imposta pelo compilador, mas a comunidade converge em torno de algumas convenções:

meu-projeto/
├── go.mod
├── go.sum
├── main.go
├── internal/
│   └── servico/
│       └── servico.go
└── pkg/
    └── util/
        └── util.go

• main.go — ponto de entrada da aplicação.
• internal/ — pacotes internos que não devem ser importados por projetos externos.
• pkg/ — pacotes que podem ser reutilizados por outros projetos. É convenção de parte da comunidade, não regra: o guia oficial de organização de módulos não usa pkg/, e muitos projetos põem esses pacotes direto na raiz. Já o internal/ é imposto pelo compilador: importar exemplo.com/a/internal/seg de outro módulo falha com use of internal package ... not allowed.

Em projetos pequenos, um único main.go na raiz é perfeitamente aceitável. A complexidade da estrutura deve crescer junto com a complexidade do projeto.

Com o go version respondendo, o ~/go/bin no PATH e um módulo criado com go mod init, o ambiente está completo — e não vai pedir muito mais do que isso daqui em diante. Dos subcomandos da lista, três entram na rotina desde o primeiro dia: go run . para experimentar, go vet para pegar o erro que compila e gofmt, de preferência rodando sozinho no editor a cada vez que o arquivo é salvo.

Fontes e leituras recomendadas

• Página de downloads oficial — Sempre obtenha o instalador aqui para garantir a versão mais recente e segura. https://go.dev/dl/

• Documentação sobre Go Modules — Guia completo e oficial sobre o sistema de módulos. https://go.dev/ref/mod

• Extensão Go para VS Code — Repositório e documentação da extensão oficial. https://github.com/golang/vscode-go

• GoLand JetBrains — IDE dedicada ao Go com período de avaliação gratuito. https://www.jetbrains.com/go/

• Go by Example: Hello World — Primeiro exemplo comentado do site de referência prática. https://gobyexample.com/hello-world

• Referência completa do comando go — Documentação de todos os subcomandos e flags. https://pkg.go.dev/cmd/go

Exercícios

Exercício 1

Você clona um projeto da empresa, roda go build e, em vez de compilar, o terminal começa a baixar "go1.28.0". Um colega diz que é vírus. O que está acontecendo, e como você faria o mesmo projeto falhar em vez de baixar algo?

Exercício 2

Um tutorial de 2019 manda criar o projeto em ~/go/src/github.com/usuario/projeto e instalar uma ferramenta com go get golang.org/x/tools/cmd/stringer. Você segue os dois passos com o Go 1.27, numa pasta sem go.mod. O que acontece em cada um, e qual é o jeito atual?

Exercício 3

Um projeto tem main.go e util.go, ambos no pacote main, e o main chama uma função definida no util.go. O go build funciona, mas o go run main.go falha. Por quê? E que nome terá o binário gerado pelo go build se o módulo se chama github.com/fulano/meu-app e a pasta se chama pasta-diferente?

Exercício 4

Uma empresa mantém dois módulos: exemplo.com/a, uma biblioteca com um pacote em internal/seg, e exemplo.com/b, um serviço. Um desenvolvedor do serviço precisa de uma função de internal/seg e a importa diretamente. O que acontece? Esse bloqueio é convenção do time ou regra da ferramenta, e quais são as saídas honestas?

Exercício 5

Depois de rodar go install golang.org/x/tools/cmd/stringer@latest sem nenhum erro, um colega digita stringer e o terminal responde que o comando não existe. Ele reinstala duas vezes, com o mesmo resultado. Onde o binário foi parar, e como você confirmaria isso sem adivinhar?