qt-cmake-template

KO | EN

gitlite — search

#typescript #ai-agents #ai #dsh-plugin #deepseek-harness #open-source #claude-code #codex #cli #developer-tools #react #windows

qt-cmake-template

★ 88 Open GitHub ↗

Project template using CMake / Qt / NSIS or WiX / MinGW or MSVS combined in easy-to-use form

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

DESCRIPTION
==========

This is a template that I created to simplify the development of cross-platform
tools written in Qt/C++. It uses CMake, and forms a nice, solid base on which to
get started with a project, so that you don't need to worry about setting up the
build system, installers, etc...

Suggestions for improvement are very welcome. The licence for the template
itself is ISC. Essentially, do what you like with it. I hope you find it useful.

* A basic example application is included.

* Just tweak your project name and version number in the top-level CMakeLists
  file and you're good to go.

* A `defines.h` file is generated, containing your application name and version.
  You can easily add to this.

* By default, no need to add each of your source files to a CMakeLists file,
  even if you organise them into subdirectories. The price you pay for this is
  needing to invoke `cmake` whenever you add a new source file. This may become
  a pain in teams, but it's trivial to change.

* A Qt resources file is ready and waiting for you to add images or other
  resources to your project.  It's already compiled-in by default.

* The `test` directory is set up for you to make it easy for you to start
  writing unit tests right from the start.

* An application icon file is added to your project in Windows, and you can
  easily overwrite the default one.

* For Windows, supports both WinGW and Visual Studio compilers.

* For Windows, there is a choice between NSIS and WiX-based installers.  Both
  are automatically configured with your choice of project name from the
  top-level CMakeLists file.  When you have chosen which you will use, it is
  straight-forward to remove everything relating to the other one: just edit
  `win/CMakeLists.txt`.

BUILDING IN LINUX
=================

As with any CMake project, create a `build` folder, enter the directory, and
invoke cmake and make:

mkdir build
    cd build
    cmake ..
    make -j <num-jobs>

Where `<num-jobs>` is the number of jobs to run in parallel (usually the number
of cores plus one).

BUILDING IN WINDOWS
===================

Dependencies
------------

### The Qt Libraries
http://qt-project.org/downloads

You can use either the MinGW version, or one of the Visual Studio versions.

### CMake
http://www.cmake.org/cmake/resources/software.html

### NSIS or WiX
http://nsis.sourceforge.net
http://wixtoolset.org

Targets
-------

In Windows, there are two additional "targets" defined in CMake configuration:
* *install*: This target installs the application and the DLLs it depends
  on into the `dist` directory. This is to simplify testing and packaging the
  application. The list of files to install is in `win/CMakeLists.txt`.
* *installer*: This target compiles the WiX installer, but will only be
  available if WiX was found in the PATH, or the `WIX_PATH` CMake variable is
  defined.

Building
--------

### Using QtCreator (Visual Studio or MinGW)

* Open QtCreator.
* File -> Open File or Project
* Open the top-level CMakeLists.txt file in the project folder.
* Choose a build location.
* Click "Run CMake".
* Click "Finish".
* If you want to enable the WiX installer:
    * On the left bar, click "Projects".
    * Next to "Edit build configuration", click "Add" -> "Clone Selected".
    * Name the configuration "installer".
    * Under "Build Steps", expand Details, and check "install" and "installer".
* Click the Build button in the bottom-left-hand corner, shaped like a hammer.

### Using the command-line

#### Visual Studio 2010

* Create a `build` directory in the source directory.
* Open a VS 2010 Command Prompt, and change into the build directory.
* Ensure that the following are on the PATH:
    * CMake's cmake.exe
    * Qt's qmake.exe
    * WiX's candle.exe (if you want the WiX installer)
* Enter the following commands:

```
cmake -G "NMake Makefiles" ..
nmake install
```

* To build the WiX installer, also run:

```
nmake installer
```

#### MinGW

* Create a `build` directory in the source directory.
* Open a Qt MinGW Command Prompt, and change into the build directory.
* Ensure that the following are on the PATH:
    * CMake's cmake.exe
    * Qt's qmake.exe
    * WiX's candle.exe (if you want the WiX installer)
* Enter the following commands:

```
cmake -G "MinGW Makefiles" ..
mingw32-make install
```

* To build the WiX installer, also run:

```
mingw32-make installer
```

### WiX Installer

The WiX Installer is more advanced, and better integrated into Windows. It is
also more complex, and gaining a thorough understanding of how it works requires
time and patience. It may be worth your while reading up on WiX and the Windows
Installer framework in order to reach a deeper understanding. However, I've done
the hard work for you, and unless you have very complex requirements, you should
be able to simply modify this script without any ill effects.

Before the installer will compile successfully, you must generate a fresh UUID
(e.g. using `uuidgen` in Linux), and place this in the `win/installer.cmake.wxs`
file in place of the `YOUR-GENERATED-UUID-HERE` placeholder.

Note that the WiX source file by default expects that your project was built
with Visual Studio 2010, and will attempt to package the Visual Studio 2010
runtime DLLs.  You'll need to modify it by hand if you use a different version
of Visual Studio, or MinGW.  This is very straight-forward.

IMPORTANT: The `installer.cmake.wxs` file is processed by CMake before it is
passed to WiX, and the processed file is placed in the build directory. If
you wish to make any modifications to the installer, make sure that you edit
`installer.cmake.wxs` in the source directory, and not `installer.wxs` in the
build directory, which will be overwritten!

### NSIS Installer

The NSIS installer is quite simple, and it's relatively easy to understand
exactly what it's doing. However, you need to take greater care in ensuring
that whatever is installed is also correctly uninstalled. Also, MSI installers
(such as WiX) are increasingly becoming the norm, especially in corporate
environments, because of their thorough integration with Windows.

In the build directory, you will find an `installer.nsi` file. This is an NSIS
script. Right-click, and click "Compile NSIS Script".  By default, the script
expects that your project was compiled with MinGW, and will attempt to package
the MinGW runtime DLLs.  It is straight-forward to change this.

IMPORTANT: Never modify the `installer.nsi` file found in the build directory,
because it will be overwritten whenever CMake is run.  Always modify the
`installer.nsi.cmake` file in the `win` directory instead.

qt-cmake-template

Explore Similar Repositories

Was this content helpful?

Recent Feedback

Download README