Difference between revisions of "Qt Quick development process"

From GCompris
Jump to: navigation, search
(Compilation chain: add libgl)
m (Compilation)
(44 intermediate revisions by 5 users not shown)
Line 16: Line 16:
 
= Source code =
 
= Source code =
  
Here is the [http://quickgit.kde.org/?p=gcompris.git official repository] for the source code. Alternatively you can also get the code on [https://github.com/bdoin/GCompris-qt GitHub].
+
Here is the [https://cgit.kde.org/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 34: Line 34:
  
 
<code><pre>
 
<code><pre>
sudo apt-get install qt5-default
+
sudo apt-get install qt5-default qtdeclarative5-dev qtmultimedia5-dev qml-module-qtquick-controls libqt5svg5-dev libqt5xmlpatterns5-dev libqt5sensors5-dev qml-module-qtquick-particles2 qttools5-dev-tools qml-module-qtmultimedia libqt5multimedia5-plugins
sudo apt-get install qtdeclarative5-dev
 
sudo apt-get install qtmultimedia5-dev
 
sudo apt-get install libqt5svg5-dev
 
sudo apt-get install libqt5xmlpatterns5-dev
 
sudo apt-get install libqt5sensors5-dev
 
sudo apt-get install qml-module-qtquick-particles2
 
sudo apt-get install qttools5-dev-tools
 
 
</pre></code>
 
</pre></code>
  
 
= Compilation =
 
= Compilation =
  
[http://www.cmake.org/ 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 2.8.
+
The minimum version to compile GCompris is 2.8 (recommended 3.5.1)
  
* Get the [http://quickgit.kde.org/?p=gcompris.git source code]:
+
* Get the [https://cgit.kde.org/gcompris.git/ source code]:
 
<pre>
 
<pre>
git clone git://anongit.kde.org/gcompris.git
+
git clone https://github.com/gcompris/GCompris-qt
 
</pre>
 
</pre>
 
* Initialize the git submodule(s)
 
* Initialize the git submodule(s)
 
<pre>
 
<pre>
cd gcompris
+
cd GCompris-qt
 
git submodule init && git submodule update
 
git submodule init && git submodule update
 
</pre>
 
</pre>
* Download and Install the latest stable version of [http://qt-project.org/downloads Qt] for Android (This includes QtCreator in the Tools/QtCreator directory)
+
* 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.6, recommended version 5.9). 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
 
* Compile and run it. (No need of giving any arguments to CMake, if QtCreator asks for it)
 
* 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:
 +
* export Qt5_DIR=$HOME/Qt/5.9.3/5.9/lib/cmake/Qt5 (This path varies with your installed version)
 +
* export Qt5Linguist_DIR=$Qt5_DIR/QtLinguist (not sure if needed)
 +
* mkdir build
 +
* cd build
 +
* cmake ..
 +
* make
  
 
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].
Line 74: Line 75:
  
 
* Install doxygen.
 
* Install doxygen.
* Build kapidox from http://quickgit.kde.org/?p=kapidox.git
+
* Build kapidox from https://cgit.kde.org/kapidox.git/
 
* 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 123: Line 124:
  
 
= Coding guidelines =
 
= Coding guidelines =
 +
 +
Take a look at this [http://gcompris.net/wiki/Reviewing_an_activity 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.
 
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.
 
== Resolution independence ==
 
 
Your activity must look nice on tablets and desktops. The resolution and ''dpi'' value may differ a lot.
 
 
=== Images and Graphics ===
 
 
On mobile with high ''dpi'' the size of your images and graphics will look smaller. You must set an initial size related to ApplicationInfo.ratio like this:
 
 
<pre>
 
Image {
 
    id: ball
 
    source: "qrc:/gcompris/src/activities/ballcatch/resource/ball.svg"
 
    sourceSize.height: 100 * ApplicationInfo.ratio
 
}
 
</pre>
 
 
=== Fonts ===
 
 
The situation for fonts is comparable. The [http://doc.qt.io/qt-5/qml-qtquick-text.html#font.pointSize-prop font.pointSize] property of Text-like QML elements handles device independence to a certain degree. An exception are devices with relativ low-dpi and a high resolution (i.e. many tablet devices >= 10'), where fonts are rendered too small when using pointSize.
 
 
For this case we use calculated constant ApplicationInfo.fontRatio, that must be used a factor to a font.pointSize value. This is done automatically when the size is set via the fontSize property of the GCFont type, which is the recommended way to specify font-sizes. Example:
 
 
<pre>
 
GCText {
 
    id: text
 
    text: "Text"
 
    fontSize: 14
 
    font.weight: Font.DemiBold
 
    color: "white"
 
}
 
</pre>
 
 
You can also use the internal pseudo enum values of GCText, that specify some often used font-sizes:
 
 
<pre>
 
    readonly property int tinySize:    10.0
 
    readonly property int smallSize:    12.0
 
    readonly property int regularSize:  14.0
 
    readonly property int mediumSize:  16.0
 
    readonly property int largeSize:    24.0
 
    readonly property int hugeSize:    32.0
 
</pre>
 
 
<pre>
 
GCText {
 
...
 
    fontSize: regularSize
 
...
 
}
 
</pre>
 
 
== Window resize ==
 
 
Your activity must adapt its content properly when the window is resized.
 
 
== Screen rotation ==
 
 
Your activity must support screen rotation. If you use a layout or you specify an item coordinated related to the window width you are safe. If you create absolute coordinate items, you may need to reset them when the screen is changed. To detect a rotation you can add a code like this in your ''ActivityBase'':
 
 
<pre>
 
    onWidthChanged: Activity.widthChanged()
 
</pre>
 
 
== Audio ==
 
 
Creating Audio items is rather slow. If you have a lot of items on the screen, do not create an Audio item for each. Instead create a single Audio and pass it to all your items.
 
 
In order to play audio only if audio has been enabled in the preferences, use the core ''GCAudio'' item instead of ''Audio''. Make sure to use ''import "../../core"''.
 
 
== Background image ==
 
 
You must not use a background image to bring useful informations. It is not possible to keep the background aligned with items when the resolution is changed.
 
  
 
== Adding a configuration for a specific activity ==
 
== Adding a configuration for a specific activity ==
Line 215: Line 145:
 
For the data to be loaded at start of activity, you also need to call "dialogActivityConfig.getInitialConfiguration()" on Component.onCompleted() of your pageComponent item.
 
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 ==
 
== 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.
 
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.
Line 245: Line 176:
 
* If you miss the GL/gl.h header, install it with ''sudo apt-get install mesa-common-dev''
 
* If you miss the GL/gl.h header, install it with ''sudo apt-get install mesa-common-dev''
  
* If you get the error: "The imported target "Qt5::Gui" references the file "Qt5Gui_EGL_LIBRARY-NOTFOUND" but this file does not exist."
+
== Compiling GCompris for Android ==
 
+
You need first to install '''ant''' (java tool) from your favorite package manager.
 
+
Then install openjdk (for example it could be openjdk-8-jdk from your favorite package manager).
  
== Compiling GCompris for Android ==
+
Then you need to download and install android ndk ([https://dl.google.com/android/repository/android-ndk-r10e-linux-x86_64.zip NDK]) and android sdk ([https://dl.google.com/android/repository/tools_r25.2.5-linux.zip SDK]).
You need to download and install android ndk ([https://developer.android.com/tools/sdk/ndk/index.html NDK]) and android sdk ([https://developer.android.com/sdk/index.html SDK]).
 
  
You also need to install the KDE extra-cmake-modules dependency (apt-get install extra-cmake-modules).
+
You also need to install the KDE extra-cmake-modules dependency.
  
To make it easier and because we don't need eclipse contained in adt-bundle-linux-x86-xxxxx, copy the directory sdk under for example ~/Android/ and rename it as android-sdk. Also, rename android-ndk-r9d as android-ndk and copy it under ~/Android/
+
To make it easier and because we don't need eclipse contained in adt-bundle-linux-x86-xxxxx, copy the directory sdk under for example ~/Android/ and rename it as android-sdk. Also, rename android-ndk-r10e as android-ndk and copy it under ~/Android/
  
Then you need to add some environment variables by editing ~/.bashrc to add at the end (put the directories where you installed ndk/sdk):
+
Edit ~/.bashrc:
 
<pre>
 
<pre>
 
export ANDROID_NDK=~/Android/android-ndk
 
export ANDROID_NDK=~/Android/android-ndk
 
export ANDROID_NDK_ROOT=$ANDROID_NDK
 
export ANDROID_NDK_ROOT=$ANDROID_NDK
 
export ANDROID_SDK_ROOT=~/Android/android-sdk
 
export ANDROID_SDK_ROOT=~/Android/android-sdk
export PATH=$PATH:~/Android/android-sdk/platform-tools
+
export PATH=$PATH:$ANDROID_SDK_ROOT/platform-tools:$ANDROID_SDK_ROOT/bin
export Qt5_android=~/Qt5.5.1/5.5/android_armv7/
+
export Qt5_android=~/Qt5.9.0/5.9/android_armv7/
 
</pre>
 
</pre>
  
It may be possible that ccmake tells you that sdk version is not installed for its version 19.
 
Go then to ~/Android/android-sdk/tools/ then start the shell program ./android.
 
Install Kitkat 4.4.1.
 
  
With Qt5.3, you'll probably need to create symbolic links for Qt libraries (if you have the error Qt5.3.0/5.3/android_armv7/lib/libQt5Core.so.5.3.0 not found):
+
You need to install the platform to build in:
 
<pre>
 
<pre>
cd Qt5.3.0/5.3/android_armv7/lib
+
sdkmanager "build-tools;27.0.1"
for f in $(ls *.so); do ln -s $f $f.5.3.0; done
+
sdkmanager "platforms;android-14"
</pre>
+
sdkmanager "platform-tools"
  
(At this point, if you do not find the directory android_armv7, you may have downloaded the wrong qt setup file. You have probably downloaded 
+
The packages need to be located within directory ~/Android/android-sdk.
Qt 5.5.1 for Linux
+
To do that you need to run sdkmanager from within android-sdk path.
instead of
 
Qt 5.5.1 for Android)
 
  
Create a folder at the same level as the gcompris folder and into it type "ccmake -DQt5_DIR=${Qt5_android} -DCMAKE_TOOLCHAIN_FILE=/usr/share/ECM/toolchain/Android.cmake -Wno-dev ../gcompris_developers/ && make && make apk_debug" to get a GCompris apk.
+
If you use ubuntu 18.04 you will need to follow this page to run sdkmanager
This opens ccmake which is a console application. Run the configuration step by typing "C" on you keyboard.
+
https://linoxide.com/linux-how-to/install-android-sdk-manager-ubuntu/
 
+
</pre>
If it tells you "Could not find a package configuration file provided by Qt5", press "e" to set the path for QT5_DIR.
 
To do this, press "enter", this will place the cursor on the first path line. With the down key go to Qt5_DIR line, press again "Enter" then modify the path.
 
For example the path can be: /home/myname/Qt5.3.0/5.3/android_armv7/lib/cmake/Qt5 where Qt5.3.0 is the Qt installation directory.
 
 
 
Then press "G" to build and "E" to quit.
 
 
 
Problems which could occurs while using ccmake:
 
  
* ccmake is telling you that it does not find opengl (qopengl.h:122:21: fatal error: GL/gl.h: No such file or directory) : you are maybe pointing to the wrong path. You are pointing to the qt5 desktop library instead of pointing to the arm libraries: You have maybe pointed to /home/myname/Qt5.5.0/5.5/gcc/lib/cmake/Qt5Core/ when you should point to /home/myname/Qt5.5.0/5.5/android_armv7/lib/cmake/Qt5Core.
 
  
* ccmake is telling you that it does not find ANDROID_DEPLOY_QT: You are maybe pointing to /home/myname/Qt5.5.0/5.5/android_armv7/bin you have to point to the androiddeployqt file /home/myname/Qt5.5.0/5.5/android_armv7/bin/androiddeployqt
 
  
  
This is how ccmake could looks like once started:
+
Create a folder at the same level as the gcompris folder and into it type:
 
<pre>
 
<pre>
ANDROID_ABI                      armeabi                     
+
git submodule init && git submodule update
ANDROID_DEPLOY_QT                /home/myname/Qt5.5.0/5.5/android_armv7/bin/androiddeployqt
+
mkdir build_android && cd build_android
ANDROID_JAVA_API_LEVEL          android-19
+
cmake -DQt5_DIR=${Qt5_android} -DCMAKE_TOOLCHAIN_FILE=/usr/share/ECM/toolchain/Android.cmake -Wno-dev ../ && make && make apk_debug
ANDROID_NATIVE_API_LEVEL        19
 
BUILD_STANDALONE                ON
 
CMAKE_ASM_COMPILER              /home/myname/Development/Android/android-ndk/toolchains/arm-linux-androideabi-4.8/prebuilt/linux-x86/b
 
CMAKE_BUILD_TYPE
 
CMAKE_INSTALL_PREFIX            /home/myname/Development/Android/android-ndk/toolchains/arm-linux-androideabi-4.8/prebuilt/linux-x86/u
 
COMPRESSED_AUDIO                ogg
 
ECM_DIR                          ECM_DIR-NOTFOUND
 
EXECUTABLE_OUTPUT_PATH          /home/myname/Development/GComprisNew/GCompris-qt/bin
 
KF5_DIR                          KF5_DIR-NOTFOUND
 
LIBRARY_OUTPUT_PATH              /home/myname/Development/GComprisNew/GCompris-qt/libs/armeabi
 
LIBRARY_OUTPUT_PATH_ROOT        /home/myname/Development/GComprisNew/GCompris-qt
 
Qt5AndroidExtras_DIR            /home/myname/Qt5.5.0/5.5/android_armv7/lib/cmake/Qt5AndroidExtras
 
Qt5Core_DIR                      /home/myname/Qt5.5.0/5.5/android_armv7/lib/cmake/Qt5Core
 
Qt5Gui_DIR                      /home/myname/Qt5.5.0/5.5/android_armv7/lib/cmake/Qt5Gui
 
Qt5LinguistTools_DIR            /home/myname/Qt5.5.0/5.5/android_armv7/lib/cmake/Qt5LinguistTools
 
Qt5Multimedia_DIR                /home/myname/Qt5.5.0/5.5/android_armv7/lib/cmake/Qt5Multimedia
 
Qt5Network_DIR                  /home/myname/Qt5.5.0/5.5/android_armv7/lib/cmake/Qt5Network
 
Qt5Qml_DIR                      /home/myname/Qt5.5.0/5.5/android_armv7/lib/cmake/Qt5Qml
 
Qt5Quick_DIR                    /home/myname/Qt5.5.0/5.5/android_armv7/lib/cmake/Qt5Quick
 
Qt5Svg_DIR                      /home/myname/Qt5.5.0/5.5/android_armv7/lib/cmake/Qt5Svg
 
Qt5Widgets_DIR                  /home/myname/Qt5.5.0/5.5/android_armv7/lib/cmake/Qt5Widgets
 
Qt5XmlPatterns_DIR              /home/myname/Qt5.5.0/5.5/android_armv7/lib/cmake/Qt5XmlPatterns
 
Qt5Xml_DIR                      /home/myname/Qt5.5.0/5.5/android_armv7/lib/cmake/Qt5Xml
 
QML_BOX2D_LIBRARY                /home/myname/Development/GComprisNew/GCompris-qt/external/qml-box2d/
 
 
 
 
</pre>
 
</pre>
 +
to get a GCompris apk.
  
 +
Ubuntu 18.04: there seem to be cmake lib problems at the moment. Until we find the solution you can add the alternative command. You should replace "yourname".
  
=== Creating the apk ===
+
cmake -DQt5_DIR=/home/yourname/Qt5.9.0/5.9/android_armv7/lib/cmake/Qt5 -DQt5Qml_DIR=/home/yourname/Qt5.9.0/5.9/android_armv7/lib/cmake/Qt5Qml -DQt5Network_DIR=/home/yourname/Qt5.9.0/5.9/android_armv7/lib/cmake/Qt5Network -DQt5Core_DIR=/home/yourname/Qt5.9.0/5.9/android_armv7/lib/cmake/Qt5Core -DQt5Quick_DIR=/home/yourname/Qt5.9.0/5.9/android_armv7/lib/cmake/Qt5Quick -DQt5Gui_DIR=/home/yourname/Qt5.9.0/5.9/android_armv7/lib/cmake/Qt5Gui -DQt5Multimedia_DIR=/home/yourname/Qt5.9.0/5.9/android_armv7/lib/cmake/Qt5Multimedia -DQt5Svg_DIR=/home/yourname/Qt5.9.0/5.9/android_armv7/lib/cmake/Qt5Svg -DQt5Widgets_DIR=/home/yourname/Qt5.9.0/5.9/android_armv7/lib/cmake/Qt5Widgets -DQt5Xml_DIR=/home/yourname/Qt5.9.0/5.9/android_armv7/lib/cmake/Qt5Xml -DQt5XmlPatterns_DIR=/home/yourname/Qt5.9.0/5.9/android_armv7/lib/cmake/Qt5XmlPatterns -DQt5LinguistTools_DIR=/home/yourname/Qt5.9.0/5.9/android_armv7/lib/cmake/Qt5LinguistTools -DQt5Sensors_DIR=/home/yourname/Qt5.9.0/5.9/android_armv7/lib/cmake/Qt5Sensors -DQt5AndroidExtras_DIR=/home/yourname/Qt5.9.0/5.9/android_armv7/lib/cmake/Qt5AndroidExtras -DCMAKE_TOOLCHAIN_FILE=/usr/share/ECM/toolchain/Android.cmake -DECM_DIR=/usr/share/ECM/cmake -Wno-dev ../GCompris-qt && make && make apk_debugcmake -DQt5_DIR=/home/yourname/Qt5.9.0/5.9/android_armv7/lib/cmake/Qt5 -DQt5Qml_DIR=/home/yourname/Qt5.9.0/5.9/android_armv7/lib/cmake/Qt5Qml -DQt5Network_DIR=/home/yourname/Qt5.9.0/5.9/android_armv7/lib/cmake/Qt5Network -DQt5Core_DIR=/home/yourname/Qt5.9.0/5.9/android_armv7/lib/cmake/Qt5Core -DQt5Quick_DIR=/home/yourname/Qt5.9.0/5.9/android_armv7/lib/cmake/Qt5Quick -DQt5Gui_DIR=/home/yourname/Qt5.9.0/5.9/android_armv7/lib/cmake/Qt5Gui -DQt5Multimedia_DIR=/home/yourname/Qt5.9.0/5.9/android_armv7/lib/cmake/Qt5Multimedia -DQt5Svg_DIR=/home/yourname/Qt5.9.0/5.9/android_armv7/lib/cmake/Qt5Svg -DQt5Widgets_DIR=/home/yourname/Qt5.9.0/5.9/android_armv7/lib/cmake/Qt5Widgets -DQt5Xml_DIR=/home/yourname/Qt5.9.0/5.9/android_armv7/lib/cmake/Qt5Xml -DQt5XmlPatterns_DIR=/home/yourname/Qt5.9.0/5.9/android_armv7/lib/cmake/Qt5XmlPatterns -DQt5LinguistTools_DIR=/home/yourname/Qt5.9.0/5.9/android_armv7/lib/cmake/Qt5LinguistTools -DQt5Sensors_DIR=/home/yourname/Qt5.9.0/5.9/android_armv7/lib/cmake/Qt5Sensors -DQt5AndroidExtras_DIR=/home/yourname/Qt5.9.0/5.9/android_armv7/lib/cmake/Qt5AndroidExtras -DCMAKE_TOOLCHAIN_FILE=/usr/share/ECM/toolchain/Android.cmake -DECM_DIR=/usr/share/ECM/cmake -Wno-dev ../GCompris-qt && make && make apk_debug
 
 
To create the apk in your android build directory:
 
<pre>
 
make BuildTranslations
 
make apk_debug
 
</pre>
 
  
 
== Deploying on android device ==
 
== Deploying on android device ==
Line 422: Line 309:
 
</pre>
 
</pre>
 
The package creation can take some time because of the dependencies retrieval.
 
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.<br>
 +
Install [http://www.cmake.org/ CMake]. The minimum version to compile GCompris is 2.8.
 +
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.
 +
Then in console:
 +
<pre>
 +
$ 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
 +
</pre>
 +
 +
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 <pre>~/Qt5.7.0/5.7/clang_64/plugins/</pre> to
 +
<pre>build/bin/GCompris-qt.app/Contents/Plugins/</pre>
  
 
== Getting and compiling translations ==
 
== Getting and compiling translations ==
Line 469: Line 382:
  
 
[[Category:English]]
 
[[Category:English]]
 +
 +
= Reviewing an activity =
 +
The [[Reviewing an activity]] page contains info to help reviewing an activity.

Revision as of 15:15, 1 December 2018

Learning Qt Quick

Some pointers to discover Qt Quick:

A step by step exercise to dig into Qt Quick with the QtCreator development environment:

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
sudo apt-get install cmake-curses-gui # Optional
sudo apt-get install g++
sudo apt-get install libgl1-mesa-dev

Qt5

sudo apt-get install qt5-default qtdeclarative5-dev qtmultimedia5-dev qml-module-qtquick-controls libqt5svg5-dev libqt5xmlpatterns5-dev libqt5sensors5-dev qml-module-qtquick-particles2 qttools5-dev-tools qml-module-qtmultimedia libqt5multimedia5-plugins

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 2.8 (recommended 3.5.1)

git clone https://github.com/gcompris/GCompris-qt
  • Initialize the git submodule(s)
cd GCompris-qt
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.6, recommended version 5.9). 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:

  • export Qt5_DIR=$HOME/Qt/5.9.3/5.9/lib/cmake/Qt5 (This path varies with your installed version)
  • export Qt5Linguist_DIR=$Qt5_DIR/QtLinguist (not sure if needed)
  • mkdir build
  • cd build
  • cmake ..
  • make

To make it run on Android you need first to follow these instructions.

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:

Then do

kgenapidox ./path/to/gcompris-checkout/

and find your documentation under apidocs/.

Adding a new activity

Automatically

Let's say you want to port the algebra_by activity.

cd src/activities
./createit.sh algebra_by

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

Getting old menus

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

You need first to install ant (java tool) from your favorite package manager. Then install openjdk (for example it could be openjdk-8-jdk from your favorite package manager).

Then you need to download and install android ndk (NDK) and android sdk (SDK).

You also need to install the KDE extra-cmake-modules dependency.

To make it easier and because we don't need eclipse contained in adt-bundle-linux-x86-xxxxx, copy the directory sdk under for example ~/Android/ and rename it as android-sdk. Also, rename android-ndk-r10e as android-ndk and copy it under ~/Android/

Edit ~/.bashrc:

export ANDROID_NDK=~/Android/android-ndk
export ANDROID_NDK_ROOT=$ANDROID_NDK
export ANDROID_SDK_ROOT=~/Android/android-sdk
export PATH=$PATH:$ANDROID_SDK_ROOT/platform-tools:$ANDROID_SDK_ROOT/bin
export Qt5_android=~/Qt5.9.0/5.9/android_armv7/


You need to install the platform to build in:

sdkmanager "build-tools;27.0.1"
sdkmanager "platforms;android-14"
sdkmanager "platform-tools"

The packages need to be located within directory ~/Android/android-sdk.
To do that you need to run sdkmanager from within android-sdk path.

If you use ubuntu 18.04 you will need to follow this page to run sdkmanager
https://linoxide.com/linux-how-to/install-android-sdk-manager-ubuntu/



Create a folder at the same level as the gcompris folder and into it type:

git submodule init && git submodule update
mkdir build_android && cd build_android
cmake -DQt5_DIR=${Qt5_android} -DCMAKE_TOOLCHAIN_FILE=/usr/share/ECM/toolchain/Android.cmake -Wno-dev ../ && make && make apk_debug

to get a GCompris apk.

Ubuntu 18.04: there seem to be cmake lib problems at the moment. Until we find the solution you can add the alternative command. You should replace "yourname".

cmake -DQt5_DIR=/home/yourname/Qt5.9.0/5.9/android_armv7/lib/cmake/Qt5 -DQt5Qml_DIR=/home/yourname/Qt5.9.0/5.9/android_armv7/lib/cmake/Qt5Qml -DQt5Network_DIR=/home/yourname/Qt5.9.0/5.9/android_armv7/lib/cmake/Qt5Network -DQt5Core_DIR=/home/yourname/Qt5.9.0/5.9/android_armv7/lib/cmake/Qt5Core -DQt5Quick_DIR=/home/yourname/Qt5.9.0/5.9/android_armv7/lib/cmake/Qt5Quick -DQt5Gui_DIR=/home/yourname/Qt5.9.0/5.9/android_armv7/lib/cmake/Qt5Gui -DQt5Multimedia_DIR=/home/yourname/Qt5.9.0/5.9/android_armv7/lib/cmake/Qt5Multimedia -DQt5Svg_DIR=/home/yourname/Qt5.9.0/5.9/android_armv7/lib/cmake/Qt5Svg -DQt5Widgets_DIR=/home/yourname/Qt5.9.0/5.9/android_armv7/lib/cmake/Qt5Widgets -DQt5Xml_DIR=/home/yourname/Qt5.9.0/5.9/android_armv7/lib/cmake/Qt5Xml -DQt5XmlPatterns_DIR=/home/yourname/Qt5.9.0/5.9/android_armv7/lib/cmake/Qt5XmlPatterns -DQt5LinguistTools_DIR=/home/yourname/Qt5.9.0/5.9/android_armv7/lib/cmake/Qt5LinguistTools -DQt5Sensors_DIR=/home/yourname/Qt5.9.0/5.9/android_armv7/lib/cmake/Qt5Sensors -DQt5AndroidExtras_DIR=/home/yourname/Qt5.9.0/5.9/android_armv7/lib/cmake/Qt5AndroidExtras -DCMAKE_TOOLCHAIN_FILE=/usr/share/ECM/toolchain/Android.cmake -DECM_DIR=/usr/share/ECM/cmake -Wno-dev ../GCompris-qt && make && make apk_debugcmake -DQt5_DIR=/home/yourname/Qt5.9.0/5.9/android_armv7/lib/cmake/Qt5 -DQt5Qml_DIR=/home/yourname/Qt5.9.0/5.9/android_armv7/lib/cmake/Qt5Qml -DQt5Network_DIR=/home/yourname/Qt5.9.0/5.9/android_armv7/lib/cmake/Qt5Network -DQt5Core_DIR=/home/yourname/Qt5.9.0/5.9/android_armv7/lib/cmake/Qt5Core -DQt5Quick_DIR=/home/yourname/Qt5.9.0/5.9/android_armv7/lib/cmake/Qt5Quick -DQt5Gui_DIR=/home/yourname/Qt5.9.0/5.9/android_armv7/lib/cmake/Qt5Gui -DQt5Multimedia_DIR=/home/yourname/Qt5.9.0/5.9/android_armv7/lib/cmake/Qt5Multimedia -DQt5Svg_DIR=/home/yourname/Qt5.9.0/5.9/android_armv7/lib/cmake/Qt5Svg -DQt5Widgets_DIR=/home/yourname/Qt5.9.0/5.9/android_armv7/lib/cmake/Qt5Widgets -DQt5Xml_DIR=/home/yourname/Qt5.9.0/5.9/android_armv7/lib/cmake/Qt5Xml -DQt5XmlPatterns_DIR=/home/yourname/Qt5.9.0/5.9/android_armv7/lib/cmake/Qt5XmlPatterns -DQt5LinguistTools_DIR=/home/yourname/Qt5.9.0/5.9/android_armv7/lib/cmake/Qt5LinguistTools -DQt5Sensors_DIR=/home/yourname/Qt5.9.0/5.9/android_armv7/lib/cmake/Qt5Sensors -DQt5AndroidExtras_DIR=/home/yourname/Qt5.9.0/5.9/android_armv7/lib/cmake/Qt5AndroidExtras -DCMAKE_TOOLCHAIN_FILE=/usr/share/ECM/toolchain/Android.cmake -DECM_DIR=/usr/share/ECM/cmake -Wno-dev ../GCompris-qt && make && make apk_debug

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

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.

If you want to build the translations, you need to install gettext (for msgattrib) and follow the chapter Qt_Quick_development_process#Getting_and_compiling_translations. /!\ Does a Subversion package exist? Maybe https://openrepos.net/content/nieldk/subversion-0?

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

To compile and embed translations, you need to follow the chapter Qt_Quick_development_process#Getting_and_compiling_translations.

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 2.8. 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 and compiling translations

By default, no translation are present in the git repository. We need to get them from the KDE svn KDE i10n svn. You can see the translation status at GCompris translation status.

You need to have subversion and msgattrib installed.

To get all the translation files, you need to create the Makefile using cmake (see above) and type:

make getSvnTranslations

This will copy all the po files to a po/ folder in the source directory.

Once you have done this, you need to run again cmake in order to have all the translations handled. Then, to build the translations used by GCompris, type:

make BuildTranslations

Then go into the bin directory and type ./gcompris-qt to launch the software (or running from QtCreator). In the configuration dialog box, you can choose your language. Restart the application to see the language change.

If you're compiling using Qt Creator, you can go to the Projects tab and in Build Steps, add a build step and check BuildTranslations.

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.