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

==== Project description files ====
=== Explicitly generated ===
    * **''{directory-name}.pro''**
      * The [[qt:pro_files|Qt project description file]].
      * Created by running <code bash>qmake -project</code>
      * 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 <code bash>qmake</code>

==== 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 [[http://doc.qt.nokia.com/stable/resources.html|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 [[pro files|{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 ''[[pro files|{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.((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.))

==== Creating a project ====
  - Create a new directory to contain your project that carries the name of your project.
  - Create a main.cpp file in that directory that contains some skeleton code (e.g., [[HelloWorld]]).
  - Execute <code bash>qmake -project</code> in a terminal shell in the project directory. This will generate a ''[[pro files|{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 ''[[pro files|{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 ====
  - Create the desired *.h, *.cpp, *.ui, and *.qrc source files in the project directory and edit to your heart's content.
  - Edit ''[[pro files|{directory-name}.pro]]'' to reflect the added files.
  - Run  <code bash>qmake</code> 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 ====
  - If you did //not// configure the ''[[pro files|{directory-name}.pro]]'' file to build both release and debug versions, build the project by executing <code bash>make</code> in the project directory. If you //did// specify release and/or debug builds in ''[[pro files|{directory-name}.pro]]'', then run <code bash>make release</code> or <code bash>make debug</code> depending on what you want.
  - Launch your application by executing <code bash>./{directory-name}</code> 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 <code bash>make clean</code>