User Tools

Site Tools


qt:project_structure

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
      qmake

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.

Resources

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

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