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.

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.¹⁾

• {directory-name}.pro
  • The Qt project description file.
  • 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.).

• 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

    qmake

• 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.

• 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}.
  • C++ file based on {yourdialog}.ui.
  • Automatically generated by uic (the user interface compiler), which is itself automatically configured in the Makefile by qmake.

• {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.

• 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).

• 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 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.²⁾

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).

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

   qmake

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

Notes:

• 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.

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

   make

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

   make release

   or

   make debug

   depending on what you want.

2. Launch your application by executing

   ./{directory-name}

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

Notes:

• If you want to remove all intermediate files that the compiler generated (e.g., object files), run

  make clean