User Tools

Site Tools


Project structure

There are two views you can take toward how Qt projects are structured: the file view and the workflow view. Depending on how your brain works and/or the issue you are trying to understand, one of these will work better than the other. In all probability, both will be useful at some point.

The file view

A Qt project is a collection of project description files, source code files, resource files, and binary output files. Some of these files must be explicitly generated using a text editor or similar tool, others are automatically generated by the build process.1)

Project description files

Explicitly generated

  • {directory-name}.pro
    • Created by running
      qmake -project
    • May require hand editing (e.g. to add/remove source files, specify whether debug and/or release build should be available, etc.).

Automatically generated

  • Makefile, Makefile.debug, and Makefile.release
    • Standard files for use by make (Linux and OS X) or nmake (Windows) to do the actual project build.
    • Automatically generated when you run

Source files

Explicitly generated

  • main.cpp
    • The project's main C++ file containing the main function.
    • The name of this file is a convention, not a requirement.
  • {yourclass}.h and {yourclass}.cpp
    • C++ class header and implementation files for a class that you derived from QObject (if needed).
    • Probably contains Q_OBJECT, a Qt macro used to implement signals and slots.
    • There may be more than one of these.
  • {yourdialog}.ui
    • A description of a Qt GUI.
    • Typically created using Qt Designer.

Automatically generated

  • moc_{yourclass}.cpp
    • Implementation file corresponding to YourClass after the Q_OBJECT macro has been fully expanded and other QObject foo is resolved.
      • In other words, this is pure C++.
    • Automatically generated by moc (the meta-object compiler), which is itself automatically configured in the Makefile by qmake.
  • ui_{yourdialog}.:?: FIXME
    • C++ :?: file based on {yourdialog}.ui.
    • Automatically generated by uic (the user interface compiler), which is itself automatically configured in the Makefile by qmake.


Explicitly generated

  • {resources}.qrc
    • A Qt resource collection file specifying the location of icons and other resources for your project.
    • You can have more than one of these.
    • Automatically processed by rcc (the Qt resources compiler) if mentioned in {directory-name}.pro.

Automatically generated

  • qrc_{resources}.cpp
    • cpp file that contains data for the resources mentioned in {resources}.qrc as static C++ arrays of compressed binary data.
    • Automatically generated and linked to the project when qmake is run (assuming it's mentioned in the *.pro file).

Binary output

  • Compiled binaries will end up in {directory-name}.
  • If {directory-name}.pro has been configured for both release and debug, then object files will be {directory-name}/release or {directory-name}/debug depending on how you invoked make (or nmake). Otherwise, object files will also be in {directory-name}.

The workflow view

The typical Qt project workflow consists of the following major phases: creating a project, adding files to a project, building and testing a project. These are discussed below.2)

Creating a project

  1. Create a new directory to contain your project that carries the name of your project.
  2. Create a main.cpp file in that directory that contains some skeleton code (e.g., HelloWorld).
  3. Execute
    qmake -project

    in a terminal shell in the project directory. This will generate a {directory-name}.pro project description file.

  • Notes:
    • If any *.cpp or *.h files already exist in the directory when you run qmake -project, they will be included in the generated {directory-name}.pro. Having a main.cpp before you run qmake -project will make the resulting *.pro file much easier to work with.
    • You should probably run qmake -project only once during the life of a project. After the *.pro file's initial generation, you will need to edit it manually to add/remove files from the project (see the next section).

Adding files

  1. Create the desired *.h, *.cpp, *.ui, and *.qrc source files in the project directory and edit to your heart's content.
  2. Edit {directory-name}.pro to reflect the added files.
  3. Run

    to generate a new Makefile, debug and release sub-directories (if needed), and and other support files.


  • Repeat the above as needed.
  • Whenever you add new files, be sure to reflect those changes into the *.pro file and rerun qmake before running building and testing.
  • Assuming {directory-name}.pro is correctly configured, the Makefile generated by qmake will automagically be configured to call moc and uic as needed.

Building and testing

  1. If you did not configure the {directory-name}.pro file to build both release and debug versions, build the project by executing

    in the project directory. If you did specify release and/or debug builds in {directory-name}.pro, then run

    make release


    make debug

    depending on what you want.

  2. Launch your application by executing

    in the project directory (or use your file manager to launch the executable, or load the executable into a debugger or …).


  • If you want to remove all intermediate files that the compiler generated (e.g., object files), run
    make clean
The explicit/automatic dichotomy holds true whether you are using an IDE or a simple command line based environment. However, an IDE will typically manage the explicit generation of may of the files for you (e.g., *.pro files).
These phases hold true whether you are using a IDE or a simple command line based environment. However, an IDE will typically manage many of these tasks for you.
qt/project_structure.txt · Last modified: 2011/04/01 12:01 by mithat