Linux Embarcado: depuração remota em C++ com o Eclipse IDE

09/11/2026

ÍNDICE DE CONTEÚDO

Os novos e poderosos modelos de LLM, sem dúvida, aceleram o ciclo de desenvolvimento. No entanto, existe uma capacidade que eles ainda não conseguem substituir e que continua sendo de extrema importância para qualquer desenvolvedor: a depuração.

Quanto mais poderosas forem as suas ferramentas de depuração, mais rápido você consegue identificar e resolver os problemas que estão atrasando a entrega do seu projeto.

E um obstáculo constante em qualquer projeto que envolva Linux Embarcado em hardware com recursos limitados é…

Como depuramos isso remotamente? Qual é a melhor IDE para depuração remota?

Esse é um desafio recorrente não só em sistemas embarcados, mas também em ambientes de computação de alto desempenho, quando é preciso depurar diretamente em servidores remotos. Infelizmente, as IDEs modernas muitas vezes não oferecem recursos robustos para desenvolvimento e depuração remotos.

Uma das exceções é o Eclipse IDE, considerado por muitos notoriamente difícil de configurar (de fato, ao longo da minha carreira, ouvi isso de muitos desenvolvedores C++ sênior de altíssimo nível).

Por isso, aproveitei a configuração de um novo projeto em C++ rodando em uma Raspberry Pi 3 (usando o Eclipse IDE no Xubuntu 24 para depurar remotamente via SSH no Raspberry Pi OS) para criar este tutorial curto, passo a passo e ilustrado com capturas de tela.

Se este tutorial ajudar pelo menos uma única pessoa, terei cumprido o meu objetivo! 🚀

Guia definitivo de depuração remota em C++ com Eclipse e GDB Server

Este guia prático mostra como configurar o seu ambiente de desenvolvimento para compilação e depuração remotas em C++ usando o Eclipse IDE em um computador Host (notebook/desktop) conectado a uma placa alvo com Linux Embarcado (como Raspberry Pi, Toradex, BeagleBone etc.).

1. Visão geral da arquitetura

Em projetos de Linux Embarcado com binários pesados, interfaces de hardware (I2C/SPI) ou bibliotecas complexas (OpenCV, câmeras, LVGL, libcurl, threads assíncronas), o fluxo de trabalho recomendado é composto por:

Host (notebook/PC): edição do código no Eclipse IDE.
Target (placa remota): compilação (nativa/remota via SSH ou compilação cruzada) e execução do binário monitorada pelo gdbserver.
Conexão: o Eclipse se conecta via SSH/TCP à porta aberta pelo gdbserver para controlar os breakpoints e inspecionar variáveis em tempo real.

2. Pré-requisitos na placa alvo

A. Instale o `gdbserver`

Na placa alvo com Linux, verifique se o pacote do servidor GDB está instalado:

sudo apt update
sudo apt install gdbserver

B. Compile com símbolos de depuração

No seu Makefile ou script de build na placa alvo, garanta que a flag -g esteja incluída em CXXFLAGS, para que as tabelas de símbolos de depuração sejam incorporadas ao executável:

CXXFLAGS = -std=c++17 -g -Wall ...

3. Configuração passo a passo no Eclipse

Passo 1: Configuração da conexão SSH

Acesse Window > Preferences > Remote Development > Connections (ou clique em New… ao lado de Connection na janela de Debug Configuration).

Parâmetros principais:

Host: <IP_DA_SUA_PLACA> (ex.: 192.168.0.148)
User: <USUARIO_REMOTO> (ex.: pi)
Authentication: selecione Password ou Public key based authentication.
Advanced > Port: 22 (deve ser a porta SSH padrão 22. Evite portas de FTP, como 20 ou 21).
Advanced > Timeout: 10
SSH Proxy Settings: defina como Local, com o campo de comando do proxy vazio, para evitar loops recursivos de SSH.

Passo 2: Caminhos da aplicação (aba Main)

Vá em Run > Debug Configurations…, clique com o botão direito em C/C++ Remote Application e selecione New Configuration.

Parâmetros principais:

Project: selecione o projeto do seu workspace local do Eclipse (<NOME_DO_PROJETO>).
C/C++ Application: informe o caminho local do executável ou o nome do binário (<NOME_DO_EXECUTAVEL>).
Observação: se você compila nativamente na placa alvo, crie um arquivo local fictício (touch <NOME_DO_EXECUTAVEL> && chmod +x <NOME_DO_EXECUTAVEL>) para passar na validação do Eclipse.
Build Configuration: selecione Select Automatically ou Use Active e garanta que a opção Disable auto build esteja marcada em Build (if required) before launching.
Connection: escolha a conexão SSH que você configurou (<USUARIO_REMOTO>@<IP_DA_SUA_PLACA>).
Remote Absolute File Path for C/C++ Application: informe a localização exata do binário na placa alvo:
/home/<USUARIO_REMOTO>/<PASTA_DO_PROJETO>/<NOME_DO_EXECUTAVEL>
Skip download to target path: MARQUE ESTA OPÇÃO para evitar que o Eclipse sobrescreva o binário na placa.

Passo 3: Opções do depurador e do GDB

Mude para a aba Debugger.

Parâmetros principais:

Stop on startup at: main (pausa automaticamente no ponto de entrada da sua aplicação).
GDB debugger: gdb-multiarch (para depuração multiplataforma) ou gdb.
GDB command file: .gdbinit

Observação sobre os launchers: na parte de baixo da janela, clique em Select other… e escolha Using GDB (DSF) Automatic Remote Debugging Launcher ou C/C++ Remote GDB Launcher.

Passo 4: Configurações do Gdbserver

Dentro da aba Debugger, abra a subaba Gdbserver Settings.

Parâmetros principais:

Gdbserver path: /usr/bin/gdbserver
Port number: 2345 (porta padrão de comunicação entre o Eclipse e a placa alvo).

4. Fluxo de execução e saída do shell remoto

Quando você clica em Debug, o Eclipse executa automaticamente o gdbserver na placa remota via SSH:

Comando executado na placa alvo:

/usr/bin/gdbserver :2345 /home/<USUARIO_REMOTO>/<PASTA_DO_PROJETO>/<NOME_DO_EXECUTAVEL>;exit

Saída na placa alvo:

Process /home/<USUARIO_REMOTO>/<PASTA_DO_PROJETO>/<NOME_DO_EXECUTAVEL> created; pid = 1750
Listening on port 2345
Remote debugging from host ::ffff:<IP_DO_HOST>, port 59378

5. Como depurar com breakpoints

Mude de perspectiva: abra a Debug Perspective no Eclipse (Window > Perspective > Open Perspective > Debug).
Defina os breakpoints: dê um duplo clique na margem esquerda, ao lado de qualquer linha de código no editor, para adicionar um marcador azul de breakpoint.
Atalhos de controle:
- F8 (Resume / ▶): continua a execução até o próximo breakpoint.
- F6 (Step Over / ↷): executa a linha atual sem entrar nas funções.
- F5 (Step Into / ↴): entra na chamada de função.
- F7 (Step Return / ⬆): sai da função atual.
- Ctrl + F2 (Terminate / ⏹): encerra a sessão e interrompe o processo remoto.

6. Guia de solução de problemas

Erro: “Program does not exist”

Causa: o Eclipse verifica se existe um arquivo executável local no Host antes de iniciar a execução.
Solução: crie um arquivo fictício localmente, na raiz do seu projeto:
```
touch <NOME_DO_EXECUTAVEL> && chmod +x <NOME_DO_EXECUTAVEL>
```

Erro: “Error during file upload”

Causa: o Eclipse tenta enviar o binário via SFTP antes de depurar.
Solução: marque a opção Skip download to target path na aba Main das Debug Configurations.

Erro: “java.lang.StackOverflowError”

Causa: loops circulares de proxy SSH ou configuração incorreta da porta SSH no Eclipse.
Solução:
1. Defina a porta da conexão SSH como 22 (não use a porta 20, de FTP).
2. Defina SSH Proxy Settings como Local, com o campo de comando vazio.
3. Troque o launcher em Select other… para GDB (DSF) Automatic Remote Debugging Launcher.

O depurador trava em sinais internos do sistema operacional

Causa: o GDB intercepta sinais entre threads (SIGPIPE, SIGUSR1 etc.).
Solução: vá em Window > Preferences > C/C++ > Debug > GDB > Signals e desmarque a opção Suspend para os sinais da aplicação que não são críticos.