frameworks/kirigami/README.md

0001 # Kirigami
0002
0003 QtQuick plugins to build user interfaces based on the KDE UX guidelines
0004
0005 ## Introduction
0006
0007 Kirigami is a set of QtQuick components at the moment targeted for mobile use (in the future desktop as well) targeting both Plasma Mobile and Android. It’s not a whole set of components, all the “Primitive” ones like buttons and textboxes are a job for QtQuickControls (soon QtQuickControls2) but it’s a set of high level components to make the creation of applications that look and feel great on mobile as well as desktop devices and follow the Kirigami Human Interface Guidelines.
0008
0009 ## Build examples to desktop
0010
0011 Build all examples available
0012
0013 ```sh
0014 mkdir build
0015 cd build
0016 cmake .. -DBUILD_EXAMPLES=ON
0017 make
0018 ```
0019
0020 Then, you can run:
0021
0022 ```sh
0023 ./examples/applicationitemapp/applicationitemapp
0024 # or
0025 ./examples/galleryapp/kirigami2gallery
0026 ```
0027
0028 ## Build the gallery example app on Android
0029
0030 Make sure to install **android-sdk**, **android-ndk** and **android-qt5-arch**, where **arch** should be the same architecture that you aim to deploy.
0031
0032 ```sh
0033 mkdir build
0034 cd build
0035 cmake .. \
0036     -DQTANDROID_EXPORTED_TARGET=kirigami2gallery \
0037     -DBUILD_EXAMPLES=on \
0038     -DANDROID_APK_DIR=../examples/galleryapp \
0039     -DECM_DIR=/path/to/share/ECM/cmake \
0040     -DCMAKE_TOOLCHAIN_FILE=/usr/share/ECM/toolchain/Android.cmake \
0041     -DECM_ADDITIONAL_FIND_ROOT_PATH=/path/to/Qt5.7.0/5.7/{arch} \
0042     -DCMAKE_PREFIX_PATH=/path/to/Qt5.7.0/5.7/{arch}/path/to/Qt5Core \
0043     -DANDROID_NDK=/path/to/Android/Sdk/ndk-bundle \
0044     -DANDROID_SDK_ROOT=/path/to/Android/Sdk/ \
0045     -DANDROID_SDK_BUILD_TOOLS_REVISION=26.0.2 \
0046     -DCMAKE_INSTALL_PREFIX=/path/to/dummy/install/prefix
0047 ```
0048
0049 You need a `-DCMAKE_INSTALL_PREFIX` to somewhere in your home, but using an absolute path.
0050
0051 If you have a local checkout of the breeze-icons repo, you can avoid the cloning of the build dir
0052 by passing also `-DBREEZEICONS_DIR=/path/to/existing/sources/of/breeze-icons`
0053
0054 ```sh
0055 make create-apk-kirigami2gallery
0056 ```
0057
0058 Apk will be generated at `./kirigami2gallery_build_apk/build/outputs/apk/kirigami2gallery_build_apk-debug.apk`.
0059
0060 To directly install on a phone:
0061
0062 ```sh
0063 adb install -r ./kirigami2gallery_build_apk/build/outputs/apk/kirigami2gallery_build_apk-debug.apk
0064 ```
0065
0066 To perform this, your device need to be configureted with `USB debugging` and `install via USB` in `Developer options`.
0067
0068 > Some ambient variables must be set before the process: `ANDROID_NDK`, `ANDROID_SDK_ROOT`, `Qt5_android` and `JAVA_HOME`
0069
0070 ```sh
0071 export ANDROID_NDK=/path/to/android-ndk
0072 export ANDROID_SDK_ROOT=/path/to/android-sdk
0073 export Qt5_android=/path/to/android-qt5/5.7.0/{arch}
0074 export PATH=$ANDROID_SDK_ROOT/platform-tools/:$PATH
0075 # adapt the following path to your ant installation
0076 export ANT=/usr/bin/ant
0077 export JAVA_HOME=/path/to/lib/jvm/java-8-openjdk/
0078 ```
0079
0080 # Build on your application Android, ship it together Kirigami
0081
0082 1) Build kirigami
0083
0084    Use the same procedure mentioned above (but without `BUILD_EXAMPLES` switch):
0085     - `cd` into kirigami sources directory;
0086     - Execute build script:
0087         ```sh
0088         mkdir build
0089         cd build
0090
0091         cmake ..  \
0092             -DCMAKE_TOOLCHAIN_FILE=/path/to/share/ECM/toolchain/Android.cmake\
0093             -DCMAKE_PREFIX_PATH=/path/to/Qt5.7.0/5.7/android_armv7/\
0094             -DCMAKE_INSTALL_PREFIX=/path/to/dummy/install/prefix\
0095             -DECM_DIR=/path/to/share/ECM/cmake
0096
0097         make
0098         make install
0099         ```
0100     - Note: omit the `make create-apk-kirigami2gallery` step.
0101
0102 2) Build your application
0103
0104    This guide assumes that you build your application with CMake and use [Extra CMake Modules (ECM)](https://api.kde.org/ecm/) from KDE frameworks.
0105     - `cd` into your application sources directory;
0106     - Replace `$yourapp` with the actual name of your application;
0107     - Execute build script:
0108         ```sh
0109         mkdir build
0110         cd build
0111
0112         cmake .. \
0113             -DCMAKE_TOOLCHAIN_FILE=/path/to/share/ECM/toolchain/Android.cmake \
0114             -DQTANDROID_EXPORTED_TARGET=$yourapp \
0115             -DANDROID_APK_DIR=../examples/galleryapp/ \
0116             -DCMAKE_PREFIX_PATH=/path/to/Qt5.7.0/5.7/android_armv7/ \
0117             -DCMAKE_INSTALL_PREFIX=/path/to/dummy/install/prefix
0118
0119         make
0120         make install
0121         make create-apk-$yourapp
0122         ```
0123     - Note: `-DCMAKE_INSTALL_PREFIX` directory will be the same as where Kirigami was installed,
0124     since you need to create an apk package that contains both the kirigami build and the
0125     build of your application.
0126
0127 # Build an application with qmake
0128
0129 * Use `examples/minimalqmake` example as a template.
0130 * It links statically for Android, but on desktop systems it links to the shared library provided by your distribution. However, static linking mode may be useful for other systems such as iOS or Windows.
0131 * Static linking only: clone `kirigami` and `breeze-icons` git repositories under the 3rdparty folder.
0132 * Android only: in your `main()` call `KirigamiPlugin::getInstance().registerTypes();` to register QML types.
0133 * QtCreator should be able to deploy on Android out of the box via auto-detected Android Kit, provided that SDK, NDK and other relevant tools are installed.