Rutas de inclusión de C++: configurar la búsqueda de encabezados

Una ruta de inclusión es un directorio que un compilador de C++ tiene en cuenta al resolver un encabezado nombrado por una directiva #include. Añade el directorio de encabezados de tu proyecto a la configuración de compilación cuando un archivo fuente incluye un encabezado que no está en una ubicación que el compilador ya busque. La directiva pertenece al código fuente; la ruta de inclusión pertenece a los ajustes del compilador o de la compilación.

¿Qué es una ruta de inclusión de C++?

Un proyecto puede mantener las declaraciones en un directorio de encabezados y la implementación en archivos fuente. En el ejemplo de Bash siguiente, el directorio temporal del proyecto contiene esta estructura: tmp_dir/ → include/message.h y src/main.cpp.

Si main.cpp contiene #include <message.h>, el compilador necesita saber que include/ es un directorio de búsqueda. Una ruta de inclusión no es una copia del encabezado ni cambia su contenido; le indica al compilador dónde puede buscar mientras procesa la inclusión. Los encabezados del sistema y de la cadena de herramientas también se encuentran a través de ubicaciones configuradas por el compilador y el entorno de compilación.

Cómo configurar las rutas de inclusión de C++

Elige el ajuste que corresponda a la compilación que uses. Mantén el directorio de encabezados y su ruta coherentes entre las compilaciones locales, las configuraciones del IDE y la automatización.

Opciones del compilador

En GCC o un compilador compatible, -I añade un directorio a la configuración de búsqueda de encabezados. Este ejemplo de Bash autónomo crea un proyecto pequeño en un directorio temporal, para que puedas ejecutarlo desde cualquier directorio de trabajo.

tmp_dir=$(mktemp -d)
trap 'rm -rf "$tmp_dir"' EXIT
mkdir -p "$tmp_dir/include" "$tmp_dir/src"
cat > "$tmp_dir/include/message.h" <<'HEADER'
#pragma once
#define MESSAGE "Hello from the project header"
HEADER
cat > "$tmp_dir/src/main.cpp" <<'SOURCE'
#include <iostream>
#include <message.h>

int main() {
    std::cout << MESSAGE << '\n';
}
SOURCE
g++ -I"$tmp_dir/include" "$tmp_dir/src/main.cpp" -o "$tmp_dir/app"
"$tmp_dir/app"

Hello from the project header

La opción -I recibe el directorio que contiene el encabezado, no el nombre del archivo de encabezado. Aquí el compilador recibe src/main.cpp y escribe el ejecutable en el directorio temporal con -o. Con Microsoft C++ (cl), usa /I seguido del directorio; la sintaxis de la opción depende del compilador.

Ajustes de proyecto del IDE

En Visual Studio, añade el directorio de encabezados al ajuste Additional Include Directories del proyecto, dentro de las opciones de inclusión de C/C++. Las etiquetas exactas de las páginas de propiedades pueden variar según la versión de Visual Studio y el tipo de proyecto. Aplica el ajuste a la configuración y la plataforma que compiles, como Debug y x64, y usa las variables de directorio del proyecto cuando ayuden a mantener las rutas portables. Otros IDE exponen ajustes equivalentes de directorios de inclusión del compilador o del proyecto; comprueba que la configuración de compilación activa los utilice.

Makefile

Coloca la opción del compilador en las opciones de compilación del Makefile para que cada compilación de un fuente la reciba. Por ejemplo, el ajuste relevante puede escribirse como CXXFLAGS += -Iinclude; la regla de compilación debe usar $(CXXFLAGS) al compilar los archivos fuente. El compilador elegido determina la opción: un Makefile que invoque cl de Microsoft necesita /Iinclude en su lugar. Esto es una ilustración de sintaxis, no un Makefile completo ni una compilación ejecutada.

Cómo funciona la búsqueda de encabezados de C++

La directiva #include le pide al preprocesador que procese un encabezado con nombre. Las ubicaciones consideradas dependen de la forma de la directiva, del archivo que la contiene, de las opciones del compilador y de la implementación. No supongas que todos los compiladores buscan en una lista universal en el mismo orden ni que comprueban automáticamente los directorios padre de un proyecto.

Cuando no se encuentra un encabezado, verifica la ortografía y las mayúsculas, y luego confirma que el directorio configurado sea el que contiene el archivo. Comprueba que la opción o la propiedad del IDE llegue a la invocación del compilador para la configuración que estás compilando. Si el encabezado se incluye desde otro encabezado, ten en cuenta la ubicación del archivo que lo incluye y las reglas documentadas del compilador. Una compilación detallada o una opción del compilador que imprima las rutas de búsqueda puede ayudar a mostrar qué configuración está activa; el comando de diagnóstico disponible varía según la cadena de herramientas.

#include "..." frente a #include <...>

La forma con comillas, #include "message.h", suele buscar primero en el directorio del archivo que la incluye y después seguir las reglas de búsqueda adicionales de la implementación. La forma con corchetes angulares, #include <message.h>, usa las ubicaciones de búsqueda configuradas de la implementación. El comportamiento de búsqueda restante exacto está definido por la implementación, así que consulta la documentación de tu compilador cuando el orden importe.

Estas formas no son etiquetas estrictas para encabezados «personalizados» y «estándar». Un encabezado del proyecto puede usar corchetes angulares cuando su directorio está configurado, como en el ejemplo anterior; una forma con comillas puede nombrar cualquier encabezado alcanzable según las reglas de búsqueda de la implementación. Elige una forma acorde con las convenciones del proyecto y ten en cuenta que las rutas configuradas del compilador siguen determinando si el nombre se resuelve.