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"
...
#endifNota: 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.hqmake 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.cppPara 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.

stable.h
/* Add C includes here */
#if defined __cplusplus
/* Add C++ includes here */
# include <iostream>
# include <QApplication>
# include <QPushButton>
# include <QLabel>
#endifmyobject.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.