Difference between revisions of "Qt Quick development process"
Petitlapin (talk | contribs) (added missing dependencies spotted by one GCi student) |
Petitlapin (talk | contribs) (→Giving the activity title and describing your new activity within the code) |
||
(51 intermediate revisions by 5 users not shown) | |||
Line 1: | Line 1: | ||
{{TOCright}} | {{TOCright}} | ||
= Learning Qt Quick = | = Learning Qt Quick = | ||
+ | |||
+ | <span style="background:#00FF00">''A shorter Qt Quick development process is embedded in GCompris source code. You can find it [https://invent.kde.org/education/gcompris/-/blob/master/HACKING here].''</span> | ||
Some pointers to discover Qt Quick: | Some pointers to discover Qt Quick: | ||
Line 7: | Line 9: | ||
* [http://qmlbook.org/index.html Qml Book] | * [http://qmlbook.org/index.html Qml Book] | ||
− | A step by step exercise to dig into Qt Quick with the QtCreator development environment: | + | A step by step exercise to dig into Qt Quick with the QtCreator [development] environment: |
* [http://qt-project.org/doc/qtcreator QtCreator] | * [http://qt-project.org/doc/qtcreator QtCreator] | ||
+ | |||
+ | The following list provided by Jerome from QtMob forum is a gold mine: | ||
+ | |||
+ | * First step into Qt https://www.cleanqt.io/home | ||
+ | * modules http://doc.qt.io/qt-5/modules-qml.html | ||
+ | * available components http://doc.qt.io/qt-5/qmltypes.html | ||
+ | * basic type http://doc.qt.io/qt-5/qmlbasictypes.html | ||
+ | * positioning gui element(not location) http://doc.qt.io/qt-5/qtquick-positioning-topic.html | ||
+ | * layout http://doc.qt.io/qt-5/qtquicklayouts-index.html | ||
+ | * https://doc.qt.io/qt-5/qtquick-usecase-layouts.html | ||
+ | * Debugging http://doc.qt.io/qt-5/qtquick-debugging.html | ||
+ | * Qml Javascript built-in functions http://doc.qt.io/qt-5/qtqml-javascript-functionlist.html | ||
+ | * Controls 2 https://doc.qt.io/qt-5/qtquickcontrols2-index.html | ||
+ | * https://doc.qt.io/qt-5/qtquick-controls2-qmlmodule.html | ||
+ | |||
+ | In order to debug QML you can use GammaRay from KDAB: | ||
+ | |||
+ | https://github.com/KDAB/GammaRay/wiki/Getting-GammaRay | ||
+ | |||
+ | Here are some videos links to learn how to use it: | ||
+ | |||
+ | * https://youtu.be/vhD1WBaRLZI GammaRay Tutorials (Part 1) - GammaRay Introduction | ||
+ | * https://youtu.be/GefC1-W6TO0 GammaRay Tutorials (Part 2) - How to set up GammaRay on Windows | ||
+ | * https://youtu.be/zlgMaURbvDI GammaRay Tutorials (Part 3) - Add Gammaray Shortcut in Qt Creator | ||
+ | * https://youtu.be/Pk878kZiTRs GammaRay Tutorials (Part 4) - Launch an Application Under GammaRay | ||
+ | * https://youtu.be/mVzcPekvldM GammaRay Tutorials (Part 5) - Why isn't my QtQuick Element visible | ||
+ | * https://youtu.be/bYQ500C7g3w GammaRay Tutorials (Part 6) - GammaRay Quick Scenes Introduction | ||
+ | * https://youtu.be/U24zV26Upc0 GammaRay Tutorials (Part 7) - How to Visualize Bindings | ||
+ | * https://youtu.be/oOzYbW68Q4g GammaRay Tutorials (Part 8) - How to visualize Qt Quick Batching and Overdrawing | ||
= Coding Style = | = Coding Style = | ||
Line 16: | Line 47: | ||
= Source code = | = Source code = | ||
− | Here is the [https:// | + | Here is the [https://invent.kde.org/education/gcompris.git official repository] for the source code. Alternatively you can also get the code on [https://github.com/GCompris/GCompris-qt GitHub]. |
= Compilation prerequisites = | = Compilation prerequisites = | ||
Line 24: | Line 55: | ||
== Compilation chain == | == Compilation chain == | ||
− | + | <pre> | |
− | sudo apt-get install cmake | + | sudo apt-get install cmake g++ libgl1-mesa-dev libssl-dev |
− | + | </pre> | |
− | + | ||
− | sudo apt-get install | + | === Optional === |
− | </pre> | + | |
+ | <pre> | ||
+ | sudo apt-get install cmake-curses-gui | ||
+ | </pre> | ||
+ | |||
+ | Note that openssl is needed since GCompris 0.96 to be able to download the resource files in https. | ||
== Qt5 == | == Qt5 == | ||
− | + | <pre> | |
− | sudo apt-get install | + | sudo apt-get install qtdeclarative5-dev qtmultimedia5-dev qml-module-qtquick-controls libqt5svg5-dev libqt5sensors5-dev qml-module-qtquick-particles2 qttools5-dev-tools qml-module-qtmultimedia libqt5multimedia5-plugins qtquickcontrols2-5-dev qml-module-qtquick-controls2 qt5-image-formats-plugins libqt5charts5-dev |
− | </pre></ | + | </pre> |
+ | |||
+ | == Translations package == | ||
+ | |||
+ | <pre> | ||
+ | sudo apt-get install gettext | ||
+ | </pre> | ||
+ | |||
+ | |||
+ | === For Ubuntu 18.04+ === | ||
+ | |||
+ | In Ubuntu 18.04+ you need to install also qttools5-dev in order to get /usr/lib/x86_64-linux-gnu/cmake/Qt5LinguistTools/Qt5LinguistToolsConfig.cmake. | ||
+ | <pre> | ||
+ | sudo apt install qttools5-dev | ||
+ | </pre> | ||
= Compilation = | = Compilation = | ||
[https://cmake.org/download/ CMake] is a cross-platform free software program for managing the build process of software using a compiler-independent method. | [https://cmake.org/download/ CMake] is a cross-platform free software program for managing the build process of software using a compiler-independent method. | ||
− | The minimum version to compile GCompris is | + | The minimum version to compile GCompris is 3.5 (3.21 is required on Windows to build packages). |
− | * Get the [https:// | + | * Get the [https://invent.kde.org/education/gcompris source code]: |
<pre> | <pre> | ||
− | git clone https:// | + | git clone https://invent.kde.org/education/gcompris.git |
</pre> | </pre> | ||
* Initialize the git submodule(s) | * Initialize the git submodule(s) | ||
Line 51: | Line 101: | ||
git submodule init && git submodule update | git submodule init && git submodule update | ||
</pre> | </pre> | ||
− | * Download and Install the latest stable version of [https://www.qt.io/download-open-source/#section-2 Qt] (This includes QtCreator in the Tools/QtCreator directory. Minimum required version is 5. | + | * Download and Install the latest stable version of [https://www.qt.io/download-open-source/#section-2 Qt] (This includes QtCreator in the Tools/QtCreator directory. Minimum required version is 5.12. For running on Android, download the Android version. |
* Start QtCreator and open the project file CMakeLists.txt at the root of the source code | * Start QtCreator and open the project file CMakeLists.txt at the root of the source code | ||
* Create a build directory and set it in Qt Creator | * Create a build directory and set it in Qt Creator | ||
Line 57: | Line 107: | ||
To compile from the command line you need: | To compile from the command line you need: | ||
− | + | <pre> | |
− | + | mkdir build | |
− | + | cd build | |
− | + | cmake .. | |
− | + | make | |
+ | </pre> | ||
+ | |||
+ | To gain some compilation time if you work on a given activity, you can use the following syntax : | ||
+ | <pre> | ||
+ | make rcc_<activity> && ./bin/gcompris-qt | ||
+ | </pre> | ||
To make it run on Android you need first to follow [http://qt-project.org/doc/qt-5/android-support.html these instructions]. | To make it run on Android you need first to follow [http://qt-project.org/doc/qt-5/android-support.html these instructions]. | ||
+ | If some errors occur, follow this [[cmake compilation trouble]] link. | ||
= Generate core API documentation = | = Generate core API documentation = | ||
Line 74: | Line 131: | ||
* Install doxygen. | * Install doxygen. | ||
− | * Build kapidox from https:// | + | * Build kapidox from https://invent.kde.org/frameworks/kapidox |
* Install doxyqml from https://github.com/agateau/doxyqml. (Note: need at least version 0.2.0 that supports readonly QML properties.) | * Install doxyqml from https://github.com/agateau/doxyqml. (Note: need at least version 0.2.0 that supports readonly QML properties.) | ||
Line 87: | Line 144: | ||
== Automatically == | == Automatically == | ||
− | Let's say you want to | + | Let's say you want to create the algebra_by activity. |
<pre> | <pre> | ||
cd src/activities | cd src/activities | ||
− | ./createit.sh algebra_by | + | ./createit.sh algebra_by "Your Name" xx@yy.org |
</pre> | </pre> | ||
Line 102: | Line 159: | ||
* in src/activities/activities.txt add the directory name of your activity (keep the file sorted). | * in src/activities/activities.txt add the directory name of your activity (keep the file sorted). | ||
* check algebra_by/ActivityInfo.qml that the name references you Qml activity entry point and that the icon point to your icon name (preferred format is svg). | * check algebra_by/ActivityInfo.qml that the name references you Qml activity entry point and that the icon point to your icon name (preferred format is svg). | ||
+ | |||
+ | == Giving the activity title and describing your new activity within the code == | ||
+ | Your activity description needs to be carefully done. It is not only displayed within your activity description screen but is also used to create the GCompris user manual. | ||
+ | The title and description is provided into the ActivityInfo.qml. | ||
+ | |||
+ | <pre> | ||
+ | ActivityInfo { | ||
+ | name: "family/Family.qml" | ||
+ | difficulty: 2 | ||
+ | icon: "family/family.svg" | ||
+ | author: "FirstName LastName &lt;email&gt;" | ||
+ | //: Activity title | ||
+ | title: qsTr("Family") | ||
+ | //: Help title | ||
+ | description: qsTr("Select the name you should call this family member.") | ||
+ | //intro: "Let us understand what to call our relatives" | ||
+ | //: Help goal | ||
+ | goal: qsTr("Learn the relationships in a family, according to the lineal system used in most Western societies.") | ||
+ | //: Help prerequisite | ||
+ | prerequisite: qsTr("Reading skills.") | ||
+ | //: Help manual | ||
+ | manual: qsTr("A family tree is shown.\n" + | ||
+ | "The circles are linked with lines to mark the relations. Married couples are marked with a ring on the link.\n" + | ||
+ | "You are the person in the white circle. Select the name you should call the person in the orange circle.\n") | ||
+ | credit: "" | ||
+ | section: "sciences history" | ||
+ | createdInVersion: 9000 | ||
+ | } | ||
+ | </pre> | ||
+ | |||
+ | In this example: | ||
+ | |||
+ | '''Title''' provides the activity name present in the main menu | ||
+ | |||
+ | (while creating a title, if the activity is played against Tux or against a friend, use parentheses: e.g. : '''Align four (against Tux) - Align four (with your friend)''' | ||
+ | |||
+ | '''Description''' provides the catching sentence, telling what the game is about, it can be found as title when clicking on the question mark button. | ||
+ | |||
+ | '''Goal''' provides the pedagogical goal. It tells what is the aim of this activity, what will be learnt if I play it. | ||
+ | |||
+ | '''Manual''' provides the guide to play the activity. | ||
== Getting old menus == | == Getting old menus == | ||
Line 176: | Line 274: | ||
== Compiling GCompris for Android == | == Compiling GCompris for Android == | ||
− | + | Install openjdk (for example it could be openjdk-8-jdk from your favorite package manager). | |
− | + | ||
+ | To build APK files for android, the minimum required version of Qt is now 5.12.6 (tested with 5.12.9, 5.13.0 and 5.13.1). It fails with 5.12.10 and 5.12.11. | ||
+ | |||
+ | It uses gradle, android ndk r21e and openssl 1.1.1m. | ||
+ | |||
+ | Clang is provided within the NDK android environment. You do not need to install ant anymore, and gradle will download itself automatically during the apk creation. | ||
+ | |||
+ | '''Step 1''': Get ECM sources, build and install them. | ||
+ | |||
+ | ECM or Extra CMake Modules package reduces duplication in CMake scripts across KDE software. | ||
+ | If the ECM version shipped with your distribution is not recent enough, try to get the most recent version from ECM git repository. | ||
+ | |||
+ | To get the sources (tested with 5.90.0), in your ~/home, type: | ||
+ | <pre> | ||
+ | git clone https://invent.kde.org/frameworks/extra-cmake-modules.git | ||
+ | cd extra-cmake-modules | ||
+ | git fetch && git fetch --tags | ||
+ | git checkout v5.90.0 | ||
+ | </pre> | ||
+ | |||
+ | Build and install ECM: | ||
+ | <pre> | ||
+ | cmake -DCMAKE_INSTALL_PREFIX=install . && make && make install | ||
+ | </pre> | ||
− | + | '''Step 2''': Download and set PATH environment variable for android NDK. | |
− | + | Download Android NDK, Revision 21e (January 2021) Linux 64-bit (x86), from the following link: | |
− | + | <pre> | |
+ | https://github.com/android/ndk/wiki/Unsupported-Downloads | ||
+ | </pre> | ||
+ | |||
+ | Create an Android folder in your home: | ||
+ | <pre> | ||
+ | mkdir ~/Android | ||
+ | </pre> | ||
+ | Unzip android-ndk-r21e-linux-x86_64.zip in this directory. | ||
− | Edit ~/.bashrc: | + | Edit the file ~/.bashrc to add the following lines: |
<pre> | <pre> | ||
− | export ANDROID_NDK=~/Android/android-ndk | + | export ANDROID_NDK=~/Android/android-ndk-r21e |
export ANDROID_NDK_ROOT=$ANDROID_NDK | export ANDROID_NDK_ROOT=$ANDROID_NDK | ||
+ | </pre> | ||
+ | Then reload it: | ||
+ | <pre> | ||
+ | source ~/.bashrc | ||
+ | </pre> | ||
+ | |||
+ | '''Step 3''': Download and install android sdk. | ||
+ | |||
+ | Create an android-sdk folder in ~/Android/ . | ||
+ | |||
+ | Download android sdk tools_r25.2.5-linux.zip using the following link: https://dl.google.com/android/repository/tools_r25.2.5-linux.zip . | ||
+ | |||
+ | Place it in the folder ~/Android/android-sdk . | ||
+ | |||
+ | Unzip it. | ||
+ | |||
+ | Execute the program android located in ~/Android/android-sdk/tools. It will open a gui application called Android SDK Manager. | ||
+ | |||
+ | Select the following tools: | ||
+ | |||
+ | - Android SDK Tools 25.2.5 | ||
+ | |||
+ | - Android SDK Platform-tools 29.0.4 | ||
+ | |||
+ | - Android SDK build-tools 28.0.3 | ||
+ | |||
+ | Install them by clicking on the "Install packages" button. | ||
+ | |||
+ | Edit the file ~/.bashrc to add the following lines: | ||
+ | |||
+ | <pre> | ||
export ANDROID_SDK_ROOT=~/Android/android-sdk | export ANDROID_SDK_ROOT=~/Android/android-sdk | ||
− | export PATH=$PATH: | + | export PATH=$PATH:~/Android/android-sdk/platform-tools:$ANDROID_SDK_ROOT/tools/bin |
− | + | </pre> | |
+ | |||
+ | Then reload it | ||
+ | |||
+ | <pre> | ||
+ | source ~/.bashrc | ||
</pre> | </pre> | ||
+ | '''Step 4''': Add Qt5_android environment variable. | ||
+ | |||
+ | Edit the file ~/.bashrc to add the following line: | ||
− | |||
<pre> | <pre> | ||
− | + | export Qt5_android=~/Qt5.13.1/5.13.1/android_armv7/lib/cmake | |
− | + | </pre> | |
− | + | ||
+ | Adapt the path (~/Qt5.13.1/5.13.1/) according to your Qt installation. | ||
− | + | Reload it: | |
− | |||
− | + | <pre> | |
− | + | source ~/.bashrc | |
</pre> | </pre> | ||
+ | '''Step 5''': Compile and build the apk. | ||
+ | Create the folder build_android at the same level as the GCompris-qt folder. | ||
+ | Go in this folder and run the command: | ||
− | |||
<pre> | <pre> | ||
− | + | cmake -DCMAKE_TOOLCHAIN_FILE=~/extra-cmake-modules/install/share/ECM/toolchain/Android.cmake -DQt5_DIR=~/Qt5.13.1/5.13.1/android_armv7/lib/cmake/Qt5/ -DCMAKE_FIND_ROOT_PATH=~/Qt5.13.1/5.13.1/android_armv7/lib/ ../GCompris-qt | |
− | |||
− | cmake - | ||
</pre> | </pre> | ||
− | to | + | Here again you have to adapt the Qt path according to your installation (~/Qt5.13.1/5.13.1), and the path to Android.cmake from extra-cmake-modules as well (~/extra-cmake-modules/install/share/ECM/toolchain/Android.cmake). |
− | + | After cmake has finished, execute the following commands: | |
+ | |||
+ | <pre> | ||
+ | make -j 4 | ||
+ | make apk_debug | ||
+ | </pre> | ||
− | + | You should find the apk file created in build_android/android/ . | |
== Deploying on android device == | == Deploying on android device == | ||
Line 228: | Line 400: | ||
Into the console, type the following command: | Into the console, type the following command: | ||
<pre>adb install -r GCompris-debug.apk</pre> | <pre>adb install -r GCompris-debug.apk</pre> | ||
+ | |||
+ | == Creating an aab and testing it == | ||
+ | Starting Qt5.14, you can know create aab directly. | ||
+ | You need to specify in the cmake command which ABI you want to build using the variables: ANDROID_BUILD_ABI_'''abi'''=ON, where '''abi''' can be any of: armeabi-v7a, arm64-v8a, x86_64 or x86. | ||
+ | |||
+ | For example, to build an aab with all: | ||
+ | <pre> | ||
+ | cmake -DCMAKE_TOOLCHAIN_FILE=/usr/share/ECM/toolchain/Android.cmake -DCMAKE_FIND_ROOT_PATH=~/Qt/5.15.2/android/lib/ -DQt5_DIR=~/Qt/5.15.2/android/lib/cmake/Qt5/ -DANDROID_BUILD_ABI_armeabi-v7a=ON -DANDROID_BUILD_ABI_arm64-v8a=ON -DANDROID_BUILD_ABI_x86_64=ON -DANDROID_BUILD_ABI_x86=ON .. | ||
+ | make -j 4 | ||
+ | make aab_release | ||
+ | </pre> | ||
+ | |||
+ | To test it, you need to download the [https://github.com/google/bundletool/releases bundletool] tool and extract it somewhere. Then run: | ||
+ | <pre> | ||
+ | java -jar <path/to/bundletool>/bundletool.jar build-apks --bundle=GCompris-Android-release-dl-2.1.aab --output=GCompris.apks | ||
+ | </pre> | ||
+ | or to create release apks: | ||
+ | <pre> | ||
+ | java -jar <path/to/bundletool>/bundletool.jar build-apks --bundle=GCompris-Android-release-dl-2.1.aab --output=GCompris.apks --ks=${PASS_FILE} --ks-pass=pass:${PASS_KEY} --ks-key-alias=gcompris | ||
+ | </pre> | ||
+ | |||
+ | To deploy it on your device, connect it (and make sure you have enabled the debug mode via USB using developer mode): | ||
+ | <pre> | ||
+ | java -jar <path/to/bundletool>/bundletool.jar install-apks --apks=GCompris.apks | ||
+ | </pre> | ||
== Compiling GCompris for SailfishOS == | == Compiling GCompris for SailfishOS == | ||
Line 258: | Line 455: | ||
You will probably have the following error at the end: CPack Error: Problem copying the package: /home/mersdk/build_arm/_CPack_Packages/Linux/RPM/gcompris-0.34-Linux.rpm to /home/mersdk/build_arm/gcompris-0.34-Linux.rpm but it's ok. | You will probably have the following error at the end: CPack Error: Problem copying the package: /home/mersdk/build_arm/_CPack_Packages/Linux/RPM/gcompris-0.34-Linux.rpm to /home/mersdk/build_arm/gcompris-0.34-Linux.rpm but it's ok. | ||
You can find the generated package at: /home/mersdk/build_ arm/_CPack_Packages/Linux/RPM/harbour-gcompris-qt-0.34-1.armv7hl.rpm. | You can find the generated package at: /home/mersdk/build_ arm/_CPack_Packages/Linux/RPM/harbour-gcompris-qt-0.34-1.armv7hl.rpm. | ||
− | |||
− | |||
− | |||
You can also build for emulator (replace all armv7hl above with i486). | You can also build for emulator (replace all armv7hl above with i486). | ||
Line 270: | Line 464: | ||
</pre> | </pre> | ||
It should now appear on the emulator. | It should now appear on the emulator. | ||
− | |||
== Compiling GCompris for Ubuntu click == | == Compiling GCompris for Ubuntu click == | ||
Line 289: | Line 482: | ||
cmake -DWITH_UBUNTU=on -DUBUNTU_CLICK=1 -DQt5_DIR=/usr/lib/arm-linux-gnueabihf/cmake/Qt5/ ../GCompris-qt/ && export QT_SELECT=qt5-arm-linux-gnueabihf && make && make DESTDIR=/tmp/click/ install | cmake -DWITH_UBUNTU=on -DUBUNTU_CLICK=1 -DQt5_DIR=/usr/lib/arm-linux-gnueabihf/cmake/Qt5/ ../GCompris-qt/ && export QT_SELECT=qt5-arm-linux-gnueabihf && make && make DESTDIR=/tmp/click/ install | ||
</pre> | </pre> | ||
− | |||
− | |||
Then outside the chroot, you need to run the click command to create the package: | Then outside the chroot, you need to run the click command to create the package: | ||
Line 311: | Line 502: | ||
== Compiling GCompris for Mac OS X == | == Compiling GCompris for Mac OS X == | ||
Compilation on OSX is quite similar to Linux.<br> | Compilation on OSX is quite similar to Linux.<br> | ||
− | Install [http://www.cmake.org/ CMake]. The minimum version to compile GCompris is | + | Install [http://www.cmake.org/ CMake]. The minimum version to compile GCompris is 3.5. |
Download and install [https://www.qt.io/download-open-source/#section-2 Qt] for OSX. | Download and install [https://www.qt.io/download-open-source/#section-2 Qt] for OSX. | ||
Box2D compilation is not yet supported in macOSX, you have to disable it during compilation. | Box2D compilation is not yet supported in macOSX, you have to disable it during compilation. | ||
Line 334: | Line 525: | ||
-Copy the plugins from <pre>~/Qt5.7.0/5.7/clang_64/plugins/</pre> to | -Copy the plugins from <pre>~/Qt5.7.0/5.7/clang_64/plugins/</pre> to | ||
<pre>build/bin/GCompris-qt.app/Contents/Plugins/</pre> | <pre>build/bin/GCompris-qt.app/Contents/Plugins/</pre> | ||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
== Getting translations from the Gtk version == | == Getting translations from the Gtk version == |
Revision as of 14:55, 24 October 2023
Learning Qt Quick
A shorter Qt Quick development process is embedded in GCompris source code. You can find it here.
Some pointers to discover Qt Quick:
A step by step exercise to dig into Qt Quick with the QtCreator [development] environment:
The following list provided by Jerome from QtMob forum is a gold mine:
- First step into Qt https://www.cleanqt.io/home
- modules http://doc.qt.io/qt-5/modules-qml.html
- available components http://doc.qt.io/qt-5/qmltypes.html
- basic type http://doc.qt.io/qt-5/qmlbasictypes.html
- positioning gui element(not location) http://doc.qt.io/qt-5/qtquick-positioning-topic.html
- layout http://doc.qt.io/qt-5/qtquicklayouts-index.html
- https://doc.qt.io/qt-5/qtquick-usecase-layouts.html
- Debugging http://doc.qt.io/qt-5/qtquick-debugging.html
- Qml Javascript built-in functions http://doc.qt.io/qt-5/qtqml-javascript-functionlist.html
- Controls 2 https://doc.qt.io/qt-5/qtquickcontrols2-index.html
- https://doc.qt.io/qt-5/qtquick-controls2-qmlmodule.html
In order to debug QML you can use GammaRay from KDAB:
https://github.com/KDAB/GammaRay/wiki/Getting-GammaRay
Here are some videos links to learn how to use it:
- https://youtu.be/vhD1WBaRLZI GammaRay Tutorials (Part 1) - GammaRay Introduction
- https://youtu.be/GefC1-W6TO0 GammaRay Tutorials (Part 2) - How to set up GammaRay on Windows
- https://youtu.be/zlgMaURbvDI GammaRay Tutorials (Part 3) - Add Gammaray Shortcut in Qt Creator
- https://youtu.be/Pk878kZiTRs GammaRay Tutorials (Part 4) - Launch an Application Under GammaRay
- https://youtu.be/mVzcPekvldM GammaRay Tutorials (Part 5) - Why isn't my QtQuick Element visible
- https://youtu.be/bYQ500C7g3w GammaRay Tutorials (Part 6) - GammaRay Quick Scenes Introduction
- https://youtu.be/U24zV26Upc0 GammaRay Tutorials (Part 7) - How to Visualize Bindings
- https://youtu.be/oOzYbW68Q4g GammaRay Tutorials (Part 8) - How to visualize Qt Quick Batching and Overdrawing
Coding Style
We follow this coding style.
Source code
Here is the official repository for the source code. Alternatively you can also get the code on GitHub.
Compilation prerequisites
For Debian based systems, in order to compile GCompris you need to install the following packages:
Compilation chain
sudo apt-get install cmake g++ libgl1-mesa-dev libssl-dev
Optional
sudo apt-get install cmake-curses-gui
Note that openssl is needed since GCompris 0.96 to be able to download the resource files in https.
Qt5
sudo apt-get install qtdeclarative5-dev qtmultimedia5-dev qml-module-qtquick-controls libqt5svg5-dev libqt5sensors5-dev qml-module-qtquick-particles2 qttools5-dev-tools qml-module-qtmultimedia libqt5multimedia5-plugins qtquickcontrols2-5-dev qml-module-qtquick-controls2 qt5-image-formats-plugins libqt5charts5-dev
Translations package
sudo apt-get install gettext
For Ubuntu 18.04+
In Ubuntu 18.04+ you need to install also qttools5-dev in order to get /usr/lib/x86_64-linux-gnu/cmake/Qt5LinguistTools/Qt5LinguistToolsConfig.cmake.
sudo apt install qttools5-dev
Compilation
CMake is a cross-platform free software program for managing the build process of software using a compiler-independent method. The minimum version to compile GCompris is 3.5 (3.21 is required on Windows to build packages).
- Get the source code:
git clone https://invent.kde.org/education/gcompris.git
- Initialize the git submodule(s)
cd gcompris git submodule init && git submodule update
- Download and Install the latest stable version of Qt (This includes QtCreator in the Tools/QtCreator directory. Minimum required version is 5.12. For running on Android, download the Android version.
- Start QtCreator and open the project file CMakeLists.txt at the root of the source code
- Create a build directory and set it in Qt Creator
- Compile and run it. (No need of giving any arguments to CMake, if QtCreator asks for it)
To compile from the command line you need:
mkdir build cd build cmake .. make
To gain some compilation time if you work on a given activity, you can use the following syntax :
make rcc_<activity> && ./bin/gcompris-qt
To make it run on Android you need first to follow these instructions. If some errors occur, follow this cmake compilation trouble link.
Generate core API documentation
KDE uses kapidox, a wrapper around doxygen to generate API documentation. Kapidox uses doxyqml for generating documentation for QML code.
In GCompris we document all classes in the src/core/ directory.
To build this API documentation you need:
- Install doxygen.
- Build kapidox from https://invent.kde.org/frameworks/kapidox
- Install doxyqml from https://github.com/agateau/doxyqml. (Note: need at least version 0.2.0 that supports readonly QML properties.)
Then do
kgenapidox ./path/to/gcompris-checkout/
and find your documentation under apidocs/.
Adding a new activity
Automatically
Let's say you want to create the algebra_by activity.
cd src/activities ./createit.sh algebra_by "Your Name" xx@yy.org
And you're done, you can run CMake again in QtCreator and your activity should appear on the list.
Manually
You must create a directory for your activity in src/activities. In it, create an ActivityInfo.qml, CMakeLists.txt and your qml entry point AlgebraBy.qml.
- in src/activities/activities.txt add the directory name of your activity (keep the file sorted).
- check algebra_by/ActivityInfo.qml that the name references you Qml activity entry point and that the icon point to your icon name (preferred format is svg).
Giving the activity title and describing your new activity within the code
Your activity description needs to be carefully done. It is not only displayed within your activity description screen but is also used to create the GCompris user manual. The title and description is provided into the ActivityInfo.qml.
ActivityInfo { name: "family/Family.qml" difficulty: 2 icon: "family/family.svg" author: "FirstName LastName <email>" //: Activity title title: qsTr("Family") //: Help title description: qsTr("Select the name you should call this family member.") //intro: "Let us understand what to call our relatives" //: Help goal goal: qsTr("Learn the relationships in a family, according to the lineal system used in most Western societies.") //: Help prerequisite prerequisite: qsTr("Reading skills.") //: Help manual manual: qsTr("A family tree is shown.\n" + "The circles are linked with lines to mark the relations. Married couples are marked with a ring on the link.\n" + "You are the person in the white circle. Select the name you should call the person in the orange circle.\n") credit: "" section: "sciences history" createdInVersion: 9000 }
In this example:
Title provides the activity name present in the main menu
(while creating a title, if the activity is played against Tux or against a friend, use parentheses: e.g. : Align four (against Tux) - Align four (with your friend)
Description provides the catching sentence, telling what the game is about, it can be found as title when clicking on the question mark button.
Goal provides the pedagogical goal. It tells what is the aim of this activity, what will be learnt if I play it.
Manual provides the guide to play the activity.
If your activity is an existing one, you can move its ported ActivityInfo and icon:
git mv tools/menus/algebra_by.qml src/activities/algebra_by/AlgebraBy.qml git mv tools/menus/resource/algebra_by.svg src/activities/algebra_by/algebra_by
Extending another activity
If the activity is just an extension of an existing one you have to create it either manually or automatically and then change you .qml file to extend another one. The 'erase_clic' activity is a good example.
In your .qml file:
- just import the activity you want to extend with for example: import "qrc:/gcompris/src/activities/erase"
- instead of have your root item being an 'ActivityBase' you just create an object of the base type you want to extend like Erase.
- Use a property to pass parameters to your base item and customize it
Coding guidelines
Take a look at this check list to have a high level check list before asking for a review.
Keep only small Javascript in the QML code, all the game logic must be in your Javascript file. This makes it easier to read the activity logic. It is possible to have several Javascript files if needed. The QML files must be seen as the graphical interface description and the Javascript the logic of the game.
Adding a configuration for a specific activity
Each activity can have a specific configuration (for example, changing the locale of the activity, having different modes...). A simple example can be found on Traffic activity where you can change between images and colors to display the cars.
To add configuration, you need to add the "config" value in the Bar. Then you have to add a DialogActivityConfig item where you will define the component item of the dialog. You need to define the following functions:
- setDefaultValues to set the values when displaying the configuration.
- onLoadData which is called to load the existing data from configuration.
- onSaveData which is called to save the configuration in configuration file and where you can also send signals to dynamically change current activity settings.
The data should be set in "dataToSave" attribute which is a map (pairs of key, values) where the keys are strings and values are javascript var (can be strings, lists...).
Accessing the component items can be done using: dialogActivityConfig.configItem.
For the data to be loaded at start of activity, you also need to call "dialogActivityConfig.getInitialConfiguration()" on Component.onCompleted() of your pageComponent item.
Compilation on different platforms
Compiling GCompris for Desktop
You can still use QtCreator to develop. Within it, open the CMakeLists.txt on top-level of GCompris. Select a directory (create a folder at same level as the gcompris folder for example) and then click on "Run CMake" button then finish.
To compile GCompris on command line, you can create a directory GCompris-qt-build at same level as the gcompris folder, go into it and type "cmake ../gcompris && make". You have the possibility to check which activities you want to compile or not.
If you want to create an auto extractible package for linux platforms, you need to launch cmake using: "cmake -DBUILD_STANDALONE=ON ../gcompris && make".
Troubleshooting
- If you get the error: "The imported target "Qt5::Gui" references the file "Qt5Gui_EGL_LIBRARY-NOTFOUND" but this file does not exist."
sudo apt-get install libgl1-mesa-glx
try again If this still shows the same error or tells you - /usr/bin/ld: cannot find -lGL - do :
on a 32 bits system cd /usr/lib/i386-linux-gnu sudo ln -s /usr/lib/i386-linux-gnu/mesa/libGL.so.1 libGL.so on a 64 bits system cd /usr/lib/x86_64-linux-gnu sudo ln -s /usr/lib/x86_64-linux-gnu/mesa/libGL.so.1 libGL.so
- If you miss the GL/gl.h header, install it with sudo apt-get install mesa-common-dev
Compiling GCompris for Android
Install openjdk (for example it could be openjdk-8-jdk from your favorite package manager).
To build APK files for android, the minimum required version of Qt is now 5.12.6 (tested with 5.12.9, 5.13.0 and 5.13.1). It fails with 5.12.10 and 5.12.11.
It uses gradle, android ndk r21e and openssl 1.1.1m.
Clang is provided within the NDK android environment. You do not need to install ant anymore, and gradle will download itself automatically during the apk creation.
Step 1: Get ECM sources, build and install them.
ECM or Extra CMake Modules package reduces duplication in CMake scripts across KDE software. If the ECM version shipped with your distribution is not recent enough, try to get the most recent version from ECM git repository.
To get the sources (tested with 5.90.0), in your ~/home, type:
git clone https://invent.kde.org/frameworks/extra-cmake-modules.git cd extra-cmake-modules git fetch && git fetch --tags git checkout v5.90.0
Build and install ECM:
cmake -DCMAKE_INSTALL_PREFIX=install . && make && make install
Step 2: Download and set PATH environment variable for android NDK.
Download Android NDK, Revision 21e (January 2021) Linux 64-bit (x86), from the following link:
https://github.com/android/ndk/wiki/Unsupported-Downloads
Create an Android folder in your home:
mkdir ~/Android
Unzip android-ndk-r21e-linux-x86_64.zip in this directory.
Edit the file ~/.bashrc to add the following lines:
export ANDROID_NDK=~/Android/android-ndk-r21e export ANDROID_NDK_ROOT=$ANDROID_NDK
Then reload it:
source ~/.bashrc
Step 3: Download and install android sdk.
Create an android-sdk folder in ~/Android/ .
Download android sdk tools_r25.2.5-linux.zip using the following link: https://dl.google.com/android/repository/tools_r25.2.5-linux.zip .
Place it in the folder ~/Android/android-sdk .
Unzip it.
Execute the program android located in ~/Android/android-sdk/tools. It will open a gui application called Android SDK Manager.
Select the following tools:
- Android SDK Tools 25.2.5
- Android SDK Platform-tools 29.0.4
- Android SDK build-tools 28.0.3
Install them by clicking on the "Install packages" button.
Edit the file ~/.bashrc to add the following lines:
export ANDROID_SDK_ROOT=~/Android/android-sdk export PATH=$PATH:~/Android/android-sdk/platform-tools:$ANDROID_SDK_ROOT/tools/bin
Then reload it
source ~/.bashrc
Step 4: Add Qt5_android environment variable.
Edit the file ~/.bashrc to add the following line:
export Qt5_android=~/Qt5.13.1/5.13.1/android_armv7/lib/cmake
Adapt the path (~/Qt5.13.1/5.13.1/) according to your Qt installation.
Reload it:
source ~/.bashrc
Step 5: Compile and build the apk.
Create the folder build_android at the same level as the GCompris-qt folder.
Go in this folder and run the command:
cmake -DCMAKE_TOOLCHAIN_FILE=~/extra-cmake-modules/install/share/ECM/toolchain/Android.cmake -DQt5_DIR=~/Qt5.13.1/5.13.1/android_armv7/lib/cmake/Qt5/ -DCMAKE_FIND_ROOT_PATH=~/Qt5.13.1/5.13.1/android_armv7/lib/ ../GCompris-qt
Here again you have to adapt the Qt path according to your installation (~/Qt5.13.1/5.13.1), and the path to Android.cmake from extra-cmake-modules as well (~/extra-cmake-modules/install/share/ECM/toolchain/Android.cmake).
After cmake has finished, execute the following commands:
make -j 4 make apk_debug
You should find the apk file created in build_android/android/ .
Deploying on android device
To deploy, plug you computer to your tablet. Go into you tablet preferences, switch on the developer mode.
Into the console, type the following command:
adb install -r GCompris-debug.apk
Creating an aab and testing it
Starting Qt5.14, you can know create aab directly. You need to specify in the cmake command which ABI you want to build using the variables: ANDROID_BUILD_ABI_abi=ON, where abi can be any of: armeabi-v7a, arm64-v8a, x86_64 or x86.
For example, to build an aab with all:
cmake -DCMAKE_TOOLCHAIN_FILE=/usr/share/ECM/toolchain/Android.cmake -DCMAKE_FIND_ROOT_PATH=~/Qt/5.15.2/android/lib/ -DQt5_DIR=~/Qt/5.15.2/android/lib/cmake/Qt5/ -DANDROID_BUILD_ABI_armeabi-v7a=ON -DANDROID_BUILD_ABI_arm64-v8a=ON -DANDROID_BUILD_ABI_x86_64=ON -DANDROID_BUILD_ABI_x86=ON .. make -j 4 make aab_release
To test it, you need to download the bundletool tool and extract it somewhere. Then run:
java -jar <path/to/bundletool>/bundletool.jar build-apks --bundle=GCompris-Android-release-dl-2.1.aab --output=GCompris.apks
or to create release apks:
java -jar <path/to/bundletool>/bundletool.jar build-apks --bundle=GCompris-Android-release-dl-2.1.aab --output=GCompris.apks --ks=${PASS_FILE} --ks-pass=pass:${PASS_KEY} --ks-key-alias=gcompris
To deploy it on your device, connect it (and make sure you have enabled the debug mode via USB using developer mode):
java -jar <path/to/bundletool>/bundletool.jar install-apks --apks=GCompris.apks
Compiling GCompris for SailfishOS
You need to download and install the sailfishOS SDK (SDK). Once done, you need to start the mersdk virtual machine:
VBoxManage startvm MerSDK
And ssh into it:
ssh -p 2222 -i ~/SailfishOS/vmshare/ssh/private_keys/engine/mersdk mersdk@localhost
In order to build you need to install cmake and git:
sb2 -t SailfishOS-armv7hl -m sdk-install -R zypper install cmake git
Then, you need to log in armv7hl:
sb2 -t SailfishOS-armv7hl
Clone the source code and on a separate folder type:
cmake -DSAILFISHOS=1 -DBUILD_ARCH=armv7hl ../gcompris/ && make package
You will probably have the following error at the end: CPack Error: Problem copying the package: /home/mersdk/build_arm/_CPack_Packages/Linux/RPM/gcompris-0.34-Linux.rpm to /home/mersdk/build_arm/gcompris-0.34-Linux.rpm but it's ok. You can find the generated package at: /home/mersdk/build_ arm/_CPack_Packages/Linux/RPM/harbour-gcompris-qt-0.34-1.armv7hl.rpm.
You can also build for emulator (replace all armv7hl above with i486). To install on emulator, run the SailfishOS emulator and copy the rpm into it. You can copy it from the mersdk vm using the shared folders to get it from the mersdk and on your host:
scp -P 2223 -i ~/SailfishOS/vmshare/ssh/private_keys/SailfishOS_Emulator/nemo harbour-gcompris-qt-0.34_1-1.i486.rpm nemo@localhost:RPMS ssh -p 2223 -i ~/SailfishOS/vmshare/ssh/private_keys/SailfishOS_Emulator/nemo nemo@localhost pkcon install-local harbour-gcompris-qt-0.34-1_1.i486.rpm
It should now appear on the emulator.
Compiling GCompris for Ubuntu click
You need to have a ubuntu OS installed and the ubuntu sdk (sudo apt-get install ubuntu-sdk).
Clone the source code in a GCompris-qt folder.
Then, you need to create the chroot environment (it can take some time) and log into it:
sudo click chroot -a armhf -f ubuntu-sdk-14.10 create sudo click chroot -a armhf -f ubuntu-sdk-14.10 run
You can use a newer one instead of 14.10.
Inside the chroot, you need to manually install the QtQuickControls module and run the compilation command:
apt-get install qml-module-qtquick-controls:armhf cmake -DWITH_UBUNTU=on -DUBUNTU_CLICK=1 -DQt5_DIR=/usr/lib/arm-linux-gnueabihf/cmake/Qt5/ ../GCompris-qt/ && export QT_SELECT=qt5-arm-linux-gnueabihf && make && make DESTDIR=/tmp/click/ install
Then outside the chroot, you need to run the click command to create the package:
click build /tmp/click/
This will create the click package.
Compiling GCompris for Windows
Compilation on Windows has been tested with mingw only. Download and install Qt for Windows with mingw (http://www.qt.io/). You also need to install NSIS (NSIS homepage).
Then, in a in Qt/mingw console:
cmake -G"MinGW Makefiles" ..\gcompris && mingw32-make && mingw32-make package.
The package creation can take some time because of the dependencies retrieval.
Compiling GCompris for Mac OS X
Compilation on OSX is quite similar to Linux.
Install CMake. The minimum version to compile GCompris is 3.5.
Download and install Qt for OSX.
Box2D compilation is not yet supported in macOSX, you have to disable it during compilation.
Then in console:
$ git clone https://github.com/gcompris/GCompris-qt.git $ cd GCompris-qt $ git submodule init && git submodule update $ export Qt5_DIR=$HOME/Qt5.7.0/5.7/clang_64/lib/cmake/Qt5/ (This path would vary with your Qt5 folder location) $ mkdir build $ cd build $ cmake -DQML_BOX2D_MODULE=disabled .. $ make
This should successfully build GCompris on your Mac. To run, start the GCompris-qt.app file in build/bin/ folder.
Issues: If you face issues regarding no 'svg/image load'.
-Copy the plugins from
~/Qt5.7.0/5.7/clang_64/plugins/
to
build/bin/GCompris-qt.app/Contents/Plugins/
Getting translations from the Gtk version
When adding a Gtk ported activity in the QtQuick version, if you used the strings for texts of the Gtk version, you can update all existing translation files. For this, first you need to update existing translation files using (this will add the new strings which will be untranslated for now):
make UpdateTranslations
Then, using the convertPo.py tool (and the updateAll.sh which applies it to all translations), you can update the files to get the translations from the Gtk version (if they existed).
Adding resources
- For resources, you have to put them in the resource directory of your activity
- A compiled qrc file named youractivity.rcc is auto generated by the compilation chain
- You must run cmake again to have new resources included in the qrc
- If you change a resource, a simple make will update the rcc file
- To reference your resource, use a qrc:/ url in the source. The path is:
qrc:/gcompris/src/activities/*youractivity*/resource/*myfile.svg*
Reviewing an activity
The Reviewing an activity page contains info to help reviewing an activity.