[Project logo]
[Cool PNGs to attract people]
[Project short info]
[Project usage example GIFs]
-
CMake v3.21+ – found at https://cmake.org/
-
Python 3 – found at https://www.python.org/
- Conan –
pip install conan
- Conan –
-
Qt 6 – found at https://www.qt.io/
-
C++ compiler that can compile Qt – needs to support the C++17 standard:
conan install conan/ --build=missing
cmake . -G [generator] -T [toolset] --build [PathToBuiltProject]
Example:
cmake . -G "Visual Studio 16 2019" -T v143 -Bbuild
You can use your local IDE or CMake again:
cmake --build [pathToBuiltProject] --config [configuration] -j4 -DCMAKE_TOOLCHAIN_FILE=[pathToConanToolchainFile]
Example:
cmake --build build --config release -j4 -DCMAKE_TOOLCHAIN_FILE=conan/conan_toolchain.cmake
[List of features]
Need to add a new library
If this is not a Qt library, modify conan/conanfile.txt:
[requires]
{...Other libraries...}
{Your Library Name Here Taken From https://conan.io/center/}
[generators]
CMakeDeps
CMakeToolchain
Example:
[requires]
zlib/1.2.11
libcurl
[generators]
CMakeDeps
CMakeToolchain
Remember to run Conan after the changes:
conan install conan/ --build=missing
Now they are available but not added to the CMake project itself. To do that, modify cmake/Modules.cmake:
set(Modules {Libraries From Conan})
set(QtModules {Qt Modules})
Example:
set(Modules ZLIB libcurl)
set(QtModules Widgets Network)
If your library cannot be found on ConanCenter, you could try going for Artifactory, but this requires some effort. You can always use plain CMake and modify CMakeLists.txt
, preferably including another CMake file in cmake
directory.
Qt is not found, despite being installed
Ensure that these environment variables are set properly:
-
Qt6_DIR -
[path_to_Qt]/[version]/[compiler]/lib/cmake/Qt6
example:C:/Qt/6.5.1/msvc2019_64/lib/cmake/Qt6
-
Qt6GuiTools_DIR -
[path_to_Qt]/[version]/[compiler]/lib/cmake/Qt6GuiTools
example:/usr/lib/x86_64-linux-gnu/6.5.1/clang_64/lib/cmake/Qt6GuiTools
-
Qt6CoreTools_DIR -
[path_to_Qt]/[version]/[compiler]/lib/cmake/Qt6CoreTools
example:D:/Qt/6.3/msvc2019_64/lib/cmake/Qt6CoreTools
Missing or wrong libraries | Profile errors
Ensure conan/conanfile.txt
has listed all the needed libraries under [requires]
section.
Run:
conan install conan/ --build=missing
In case of a wrong architecture of the libraries and other possible profile errors, read: https://docs.conan.io/2.0/reference/config_files/profiles.html
If you don't have a profile, create one:
conan profile new default --detect
Changing the name of the project
To change the name of the project, you must correct a few entries:
By default, the file starts with:CMakeLists.txt
cmake_minimum_required(VERSION 3.21) project("qt-template" LANGUAGES CXX)
Change
"qt-template"
to the name of your project.Example:
cmake_minimum_required(VERSION 3.21) project("myproject" LANGUAGES CXX)
If you host your project on a GitHub repository and wish to use GitHub Actions for automatic deployment, you must provide a name that matches the repository name. It has to be lowercase. Otherwise, you need to change
${{ steps.repoName.outputs.name }}
to your project's executable/library name (it is the CMake project name, unless you tinkered withCMakeLists.txt
) in these files:.github/workflows/macos.yml
.github/workflows/ubuntu.yml
.github/workflows/windows.yml
If the name contains whitespace characters, you will need to enclose the entire entry in either
"
or'
. Example:files: build/install/${{ steps.repoName.outputs.name }}_macOS_${{ steps.versionTag.outputs.tag }}.tar.gz
Becomes:
files: "build/install/Parrots and Cats_macOS_${{ steps.versionTag.outputs.tag }}.tar.gz"
config.desktop
The
Exec
option should contain the project's executable/library name (it is CMake project name, unless you tinkered withCMakeLists.txt
), while theName
is up to your choice.Change these entries:
Name=Qt Template Exec=qt-template
Example:
Name=Parrots That Sing Exec=birds-and-stuff
Changing the icon of the project
Put your icon image in PNG format into a folder icon/
and rename it, so it matches this convention:
icon_[width]x[height].png
Example:
icon_256x256.png
The resolution should be one of these:
- 16x16
- 32x32
- 48x48
- 64x64
- 128x128
- 256x256
Further below, I will mention some scripts that use ImageMagick, so you need to install it, if you want to use them. On Ubuntu, it can be done by:
sudo apt install imagemagick
Beware that depending on your OS version, you can get either ImageMagick 6 or ImageMagick 7. Unix scripts contain [script]_ImageMagick7.sh
versions, in case you did not obtain ImageMagick 6, but ImageMagick 7.
You can provide an icon with any resolution, and it will be rescaled to the other valid resolutions, if you use the script:
Windows
/icon/WinScripts/rescale.bat
Unix
/icon/UnixScripts/rescale.sh
or/icon/UnixScripts/rescale_ImageMagick7.sh
If there are multiple icons with different resolutions, the highest resolution will be used to create other valid icons. They will overwrite any already existing ones! If you want to use different icons for different resolutions, provide them manually and do not use the script.
This is sufficient for Linux, but there are two other scripts, so the Windows and macOS applications will have icons too.
To generate an icon for Windows, use:
Windows
/icon/WinScripts/createIco.bat
Unix
/icon/UnixScripts/createIco.sh
or/icon/UnixScripts/createIco_ImageMagick7.sh
macOS icon is slightly tricky on Windows, as we do not have a ready script. I recommend using WSL or another form of virtualization (i.e.: VirtualBox or Docker) and running the Unix script /icon/UnixScripts/createIcns.sh
.
If you are on macOS, you can do this the native way, using iconutil. Otherwise, run /icon/UnixScripts/createIcns.sh
, which requires png2icns
library. On Ubuntu you can install it by:
sudo apt install icnsutils
Docs shouldn't contain private members
If your project is a library, you might not want to add the private and protected members to your documentation. Editing one line in .github/workflows/doxygen.yml
can change this behaviour. Find this step:
- name: Generate documents and deploy
uses: DenverCoder1/[email protected]
with:
github_token: ${{ secrets.GITHUB_TOKEN }}
branch: docs
config_file: doxygen/Doxyfile_dev
And change it to:
- name: Generate documents and deploy
uses: DenverCoder1/[email protected]
with:
github_token: ${{ secrets.GITHUB_TOKEN }}
branch: docs
config_file: doxygen/Doxyfile
If you want to further customize output and its display, all files related to documentation are stored in /doxygen
folder.
This project follows these C++ Core Guidelines, and it would be fun if you followed them too. If you don't, someone will correct your code. An ugly contribution is better than no contribution. Thanks!
This project is licensed under the CC0 1.0 Universal; see the LICENSE file for details. It also uses the Qt library and possibly some of its additional modules that are licensed under the LGPL, but none of its code is present in this repository. Also note that Qt itself uses other third-party libraries under different license terms.