이 페이지에서

사전 컴파일된 헤더 사용

사전 컴파일된 헤더(PCH)는 일부 컴파일러에서 지원하는 성능 향상 기능으로, 안정적인 코드 본문을 컴파일하고 코드의 컴파일된 상태를 바이너리 파일에 저장합니다. 이후 컴파일 시 컴파일러는 저장된 상태를 불러와 지정된 파일의 컴파일을 계속 진행합니다. 안정된 코드를 다시 컴파일할 필요가 없기 때문에, 이후의 각 컴파일 작업은 더 빠르게 수행됩니다.

qmake는 다음을 포함한 일부 플랫폼 및 빌드 환경에서 사전 컴파일된 헤더의 사용을 지원합니다:

  • Windows
    • nmake
    • Visual Studio 프로젝트(VS 2008 이상)
  • macOS, iOS, tvOS 및 watchOS
    • Makefile
    • Xcode
  • 유닉스
    • GCC 3.4 이상
    • clang

프로젝트에 사전 컴파일된 헤더 추가하기

사전 컴파일된 헤더에는 프로젝트 전체에서 안정적이고 정적인 코드가 포함되어 있어야 합니다. 일반적인 사전 컴파일된 헤더는 다음과 같이 보일 수 있습니다:

// 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

참고: C 파일용 사전 컴파일된 헤더파일에는 C++ 코드가 포함될 수 없으므로, C++ 헤더 포함 문과 C 헤더 포함 문은 별도로 구분해야 합니다.

프로젝트 옵션

프로젝트에서 사전 컴파일된 헤더를 사용하려면 프로젝트 파일에서 PRECOMPILED_HEADER 변수만 정의하면 됩니다:

PRECOMPILED_HEADER = stable.h

qmake가 나머지 작업을 처리하여 사전 컴파일된 헤더 파일의 생성 및 사용을 보장합니다. 구성에서 사전 컴파일된 헤더를 지원하는 경우 qmake가 이를 자동으로 처리하므로, ` HEADERS`에 사전 컴파일된 헤더 파일을 직접 포함할 필요는 없습니다.

Windows를 대상으로 하는 MSVC 및 g++ 사양은 기본적으로 precompile_header 를 활성화합니다.

이 옵션을 사용하면 프로젝트 파일의 조건부 블록을 실행하여 사전 컴파일된 헤더를 사용할 때 설정을 추가할 수 있습니다. 예를 들면 다음과 같습니다:

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

MSVC nmake 타깃의 C 파일에서도 사전 컴파일된 헤더를 사용하려면 CONFIG 변수에 precompile_header_c 를 추가하십시오. 헤더가 C++에서도 사용되며 C++ 키워드나 포함 문이 포함된 경우, 이를 #ifdef __cplusplus)로 묶어주십시오.

발생할 수 있는 문제에 대한 참고 사항

일부 플랫폼에서는 사전 컴파일된 헤더 파일의 파일 이름 확장자가 다른 오브젝트 파일의 확장자와 동일합니다. 예를 들어, 다음 선언은 동일한 이름을 가진 두 개의 서로 다른 오브젝트 파일이 생성되도록 할 수 있습니다:

PRECOMPILED_HEADER = window.h
SOURCES            = window.cpp

이와 같은 잠재적인 충돌을 방지하려면, 사전 컴파일될 헤더 파일에는 구별 가능한 이름을 지정하십시오.

예제 프로젝트

Qt 배포판의 examples/qmake/precompile 디렉터리에서 다음 소스 코드를 찾을 수 있습니다:

mydialog.ui

다음 이미지는 Qt Creator 의 디자인 모드에서 mydialog.ui 파일을 보여줍니다. 편집 모드에서 코드를 확인할 수 있습니다.

디자인 모드의 대화 상자 스크린샷

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.