En esta página

Uso de encabezados precompilados

Los encabezados precompilados (PCH) son una característica de rendimiento compatible con algunos compiladores que permite compilar un conjunto estable de código y almacenar el estado compilado del código en un archivo binario. Durante las compilaciones posteriores, el compilador cargará el estado almacenado y continuará compilando el archivo especificado. Cada compilación posterior es más rápida, ya que no es necesario volver a compilar el código estable.

qmake admite el uso de encabezados precompilados en algunas plataformas y entornos de compilación, entre los que se incluyen:

  • Windows
    • nmake
    • Proyectos de Visual Studio (VS 2008 y posteriores)
  • macOS, iOS, tvOS y watchOS
    • Makefile
    • Xcode
  • Unix
    • GCC 3.4 y versiones posteriores
    • clang

Cómo añadir encabezados precompilados a tu proyecto

El encabezado precompilado debe contener código que sea estable y estático en todo el proyecto. Un encabezado precompilado típico podría tener este aspecto:

// Add C includes here

#if defined __cplusplus
// Add C++ includes here
#include <stdlib>
#include <iostream>
#include <vector>
#include <QApplication> // Qt includes
#include <QPushButton>
#include <QLabel>
#include "thirdparty/include/libmain.h"
#include "my_stable_class.h"
...
#endif

Nota: Un archivo de encabezado precompilado debe separar las inclusiones de C de las de C++, ya que el archivo de encabezado precompilado para archivos C no puede contener código C++.

Opciones del proyecto

Para que tu proyecto utilice encabezados precompilados, solo tienes que definir la variable PRECOMPILED_HEADER en el archivo de tu proyecto:

PRECOMPILED_HEADER = stable.h

qmake se encargará del resto, para garantizar la creación y el uso del archivo de encabezado precompilado. No es necesario incluir el archivo de encabezado precompilado en ` HEADERS`, ya que qmake lo hará si la configuración admite encabezados precompilados.

Las especificaciones de MSVC y g++ destinadas a Windows habilitan precompile_header de forma predeterminada.

Con esta opción, puedes activar bloques condicionales en tu archivo de proyecto para añadir ajustes al utilizar encabezados precompilados. Por ejemplo:

precompile_header:!isEmpty(PRECOMPILED_HEADER) {
DEFINES += USING_PCH
}

Para utilizar el encabezado precompilado también en los archivos C del objetivo nmake de MSVC, añade precompile_header_c a la variable CONFIG. Si el encabezado se utiliza también para C++ y contiene palabras clave o inclusiones de C++, envuélvelas entre #ifdef __cplusplus).

Notas sobre posibles problemas

En algunas plataformas, la extensión del nombre de los archivos de encabezado precompilados es la misma que la de otros archivos objeto. Por ejemplo, las siguientes declaraciones pueden provocar que se generen dos archivos objeto diferentes con el mismo nombre:

PRECOMPILED_HEADER = window.h
SOURCES            = window.cpp

Para evitar posibles conflictos como estos, asigne nombres distintivos a los archivos de cabecera que vayan a precompilarse.

Proyecto de ejemplo

Puede encontrar el siguiente código fuente en el directorio examples/qmake/precompile de la distribución de Qt:

mydialog.ui

La siguiente imagen muestra el archivo mydialog.ui en el modo Diseño de Qt Creator. Puede ver el código en el modo Edición.

Captura de pantalla del cuadro de diálogo en modo de diseño

stable.h

/* Add C includes here */

#if defined __cplusplus
/* Add C++ includes here */

# include <iostream>
# include <QApplication>
# include <QPushButton>
# include <QLabel>
#endif

myobject.h

#include <QObject>

class MyObject : public QObject
{
public:
    MyObject();
    ~MyObject();
};

myobject.cpp

#include <iostream>
#include <QDebug>
#include <QObject>
#include "myobject.h"

MyObject::MyObject()
    : QObject()
{
    std::cout << "MyObject::MyObject()\n";
}

util.cpp

void util_function_does_nothing()
{
    // Nothing here...
    int x = 0;
    ++x;
}

main.cpp

#include <QApplication>
#include <QPushButton>
#include <QLabel>
#include "myobject.h"
#include "mydialog.h"

int main(int argc, char **argv)
{
    QApplication app(argc, argv);

    MyObject obj;
    MyDialog dialog;

    dialog.connect(dialog.aButton, SIGNAL(clicked()), SLOT(close()));
    dialog.show();

    return app.exec();
}

precompile.pro

TEMPLATE  = app
LANGUAGE  = C++
CONFIG   += cmdline precompile_header

# Use Precompiled headers (PCH)
PRECOMPILED_HEADER  = stable.h

HEADERS   = stable.h \
            mydialog.h \
            myobject.h
SOURCES   = main.cpp \
            mydialog.cpp \
            myobject.cpp \
            util.cpp
FORMS     = mydialog.ui

© 2026 The Qt Company Ltd. Documentation contributions included herein are the copyrights of their respective owners. The documentation provided herein is licensed under the terms of the GNU Free Documentation License version 1.3 as published by the Free Software Foundation. Qt and respective logos are trademarks of The Qt Company Ltd. in Finland and/or other countries worldwide. All other trademarks are property of their respective owners.