Um erro comum ao compilar programas em C é o undefined reference to 'funcao', mesmo quando o cabeçalho correspondente foi incluído corretamente. Esse problema geralmente não está relacionado à inclusão do arquivo .h, mas sim à ausência do arquivo-fonte .c no processo de linkagem.

Considere o seguinte cenário:

// main.c
#include "modulo.h"

int main(void) {
    funcao_do_modulo();
    return 0;
}

// modulo.c
#include "modulo.h"

void funcao_do_modulo(void) {
    // implementação
}

// modulo.h
#ifndef MODULO_H
#define MODULO_H

void funcao_do_modulo(void);

#endif

Ao executar apenas gcc main.c -o programa, o linker falhará com undefined reference to 'funcao_do_modulo'. Isso ocorre porque o compilador processa apenas main.c e seu cabeçalho, mas nunca vê a definição em modulo.c.

A solução correta é compilar todos os arquivos-fonte necessários:

gcc main.c modulo.c -o programa

Ou, usando etapas explícitas:

gcc -c main.c -o main.o
gcc -c modulo.c -o modulo.o
gcc main.o modulo.o -o programa

Automatizando com Makefile

Em projetos maiores, gerenciar múltiplos arquivos manualmente torna-se inviável. Um Makefile resolve isso declarando dependências e regras de construção.

Exemplo de estrutura de projeto:

.
├── app.c
├── lib/
│   ├── utils.c
│   └── utils.h
└── Makefile

Makefile básico:

CC = gcc
CFLAGS = -Wall -Wextra

app: app.o lib/utils.o
	$(CC) $^ -o $@

app.o: app.c lib/utils.h
	$(CC) $(CFLAGS) -c $< -o $@

lib/utils.o: lib/utils.c lib/utils.h
	$(CC) $(CFLAGS) -c $< -o $@

.PHONY: clean
clean:
	rm -f *.o lib/*.o app

Neste exemplo, o uso de $@ (alvo), $< (primeira dependência) e $^ (todas as dependências) evita repetição e melhora a manutenção.

Evitando Definições em Cabeçalhos

Outro erro frequente é colocar definições (não apenas declarações) em arquivos .h. Por exemplo:

// ERRADO: modulo.h
int contador_global = 0;  // definição!
void funcao(void);

Se múltiplos arquivos incluírem modulo.h, cada unidade de compilação terá sua própria cópia de contador_global, resultando em erro de multiple definition na linkagem.

A abordagem correta:

// modulo.h
#ifndef MODULO_H
#define MODULO_H

extern int contador_global;  // apenas declaração
void funcao(void);

#endif

// modulo.c
#include "modulo.h"

int contador_global = 0;  // definição única aqui

void funcao(void) { /* ... */ }

Ordem de Inclusão e Tipos Opaquos

Erros como #231-D: declaration is not visible outside of function ou incompatibilidade de tipos de struct geralmente indicam que uma esrtutura foi usada antes de ser totalmente declarada.

Exemplo problemático:

// main.c
#include "config.h"  // contém função que usa struct dados_conf

struct dados_conf {
    int valor;
};

int main() {
    struct dados_conf cfg;
    inicializar(&cfg);  // erro se config.h não conhece a struct completa
}

Solução: declare a struct completa antes de qualquer uso, preferencialmente em um cabeçalho incluído antes das funções que a utilizam.

// types.h
struct dados_conf {
    int valor;
};

// config.h
#include "types.h"
void inicializar(struct dados_conf *cfg);

// main.c
#include "types.h"
#include "config.h"

Alternativamente, use ponteiros para structs opacos em interfaces públicas, expondo apenas declarações incompletas nos cabeçalhos.