In this blog post, I present a tutorial on setting up and using one of the libraries from the new KDE Frameworks 5, a collection of add-ons to Qt. Specifically, we'll look at KArchive and what is involved in setting up KArchive on Ubuntu Desktop Linux.
Note: If you are reading this after April 2014, there may be a beta or later release available and some of the details and software versions described here may be out of date. Check the links listed under References for the latest information.
The KDE project(1) has started an initiative called KDE Frameworks 5 to refactor their libraries and make them easier to use from Qt 5 applications. The Qt Developer Days 2013 conferences included several talks on KDE Frameworks 5.
The full framework provides about 57 libraries. Of these, 19 are so-called Tier 1 libraries, which have no dependencies other than system libraries and Qt itself. The higher tier libraries have dependencies on other KDE Frameworks 5 libraries. The code is released under the GNU GPL and LGPL licenses, similar to Qt.
A Tech Preview(2) of KDE Frameworks 5 was released on January 7, 2014.
In this tutorial, I'll discuss how to install and use one of the Tier 1 libraries, KArchive, from the Tech Preview. The tutorial is targeted at Ubuntu Desktop Linux 13.10, as it is one of the most common platforms used by Qt developers. The details may be slightly different if you choose to use another Linux distribution.
KArchive(3) is a library for creating, reading, writing and manipulating file archives. It provides easy to use classes for manipulation of archive file formats like zip and tar. It also provides transparent compression and decompression of data, using formats like gzip, via a subclass of QIODevice.
If you need to work with archive files, KArchive provides a cross-platform and easy to use solution that is usually superior to other alternatives, such as calling command line programs directly.
As one of the simpler, stable and easily understood KDE Frameworks, I chose this as the example for this tutorial. Other Tier 1 frameworks are similar to set up and use.
Although KArchive is a Tier 1 framework and has no dependencies on software other than Qt, there are some requirements to build it.
Obviously, you need Qt and the basic C++ development tools, all of which you likely have installed if you are a Qt developer. Qt 5.2.0 or later is needed.
To support bzip format archive compression, the zlib library is needed. This is a required library for KArchive. On Ubuntu Linux this is provided by the packages zlib1g and zlib1g-dev.
Support for bzip2 format compression is recommended. The relevant Ubuntu packages to install are libbz2-1.0 and libbz2-dev.
Also recommended is the lzma library to support xz compressed files and data streams. The Ubuntu packages for this are liblzma5 and liblzma-dev.
CMake is also required. I'll cover that in the next section. When building the software, CMake will report on the status of the dependencies found or missing and the required versions, so it should be clear at that point if you have a dependency problem or not.
CMake(4) is a cross-platform Makefile generator. The Tech Preview of KDE Frameworks 5 requires CMake version 2.8.12 or later. Unfortunately, Ubuntu 13.10 ships version 2.8.11. Thus, you need to build the newer version of CMake yourself.
This is quite straightforward and can be done by following these steps. Download the latest version of CMake from http://www.cmake.org/cmake/resources/software.html. At the time of this writing, the version was 126.96.36.199. Select the "Unix/Linux Source" and download the file, e.g. cmake-188.8.131.52.tar.gz.
As per the INSTALL file, extract the source file into a working directory, run the bootstrap script, build it using make and then install it. By default it goes under the /usr/local directory.
I used the following commands when I built it:
% wget http://www.cmake.org/files/v2.8/cmake-184.108.40.206.tar.gz % tar xzvf cmake-220.127.116.11.tar.gz % cd cmake-18.104.22.168 % ./bootstrap % make % sudo make install
When you subsequently use CMake, ensure you are running the version you just built. Make sure the installed location of CMake (e.g. /usr/local/bin) is ahead of the Ubuntu version of CMake in your search path, or explicitly specify the full path to CMake when you run it (e.g. /usr/local/bin/cmake).
Installing Extra CMake Modules (ECM)
As well as CMake, the KDE Frameworks 5 requires something called CMake Extra Modules or ECM. It is available from KDE from the same location as KArchive. I built it as follows:
% wget http://download.kde.org/unstable/frameworks/4.95.0/extra-cmake-modules-0.0.9.tar.xz % tar xJvf extra-cmake-modules-0.0.9.tar.xz % cd extra-cmake-modules-0.0.9 % cmake . % make % sudo make install
Now we are finally ready to build the KArchive library. The Tech Preview can be downloaded from http://download.kde.org/unstable/frameworks/4.95.0/ (you want the .tar.xz file when building on Linux).
Extract the source code to a working directory and build it using CMake as per the INSTALL file. I built it as follows:
% wget http://download.kde.org/unstable/frameworks/4.95.0/karchive-4.95.0.tar.xz % tar xJvf karchive-4.95.0.tar.xz % cd karchive-4.95.0 % mkdir build % cd build % cmake .. -DCMAKE_BUILD_TYPE=debug -DCMAKE_INSTALL_PREFIX=/usr/local % make % sudo make install
This builds a debug version of the library and installs it under /usr/local. You can adjust the CMake command line accordingly if you want other options. See the INSTALL file for details.
If all went well, you now have a KArchive library that is ready for use.
Building and Running the Examples
KArchive comes with a couple of example programs illustrating basic usage of the library. I encourage you to study, build and run them.
The first is a simple "hello world" program that creates a zip archive containing one file. The complete source code to do this is only about ten lines of code. From the KArchive source directory, you can build and run it as follows:
% cd examples/helloworld % cmake . % make % ./helloworld
When run, it creates a file hello.zip containing one file:
% unzip -l hello.zip Archive: hello.zip Length Date Time Name --------- ---------- ----- ---- 31 2014-02-06 12:10 world --------- ------- 31 1 file
The other example can be found in examples/tarlocalfiles. It shows how to add local files and directories to a compressed tar format archive. It can be built in a similar manner.
The following commands will do the trick. In this case, let's follow common practice with CMake and build outside of the source directory:
% cd examples/tarlocalfiles % mkdir build % cd build % cmake .. % make
The compiled program, tarlocalfiles, creates a compressed tar archive of the filenames passed to it. Here is an example of running it and examining the contents of the file it created:
% ./tarlocalfiles * % tar tzvf myFiles.tar.gz -rw-r--r-- tranter/tranter 12416 2014-02-06 12:13 CMakeCache.txt -rw-r--r-- tranter/tranter 1433 2014-02-06 12:13 CMakeFiles/22.214.171.124/CMakeCCompiler.cmake -rw-r--r-- tranter/tranter 1577 2014-02-06 12:13 CMakeFiles/126.96.36.199/CMakeCXXCompiler.cmake ... -rw-r--r-- tranter/tranter 22 2014-02-14 13:28 CMakeFiles/tarlocalfiles.dir/progress.make -rw-r--r-- tranter/tranter 1693 2014-02-06 12:13 cmake_install.cmake -rw-r--r-- tranter/tranter 4893 2014-02-14 13:28 Makefile -rw------- tranter/tranter 2 2014-02-14 13:28 myFiles.tar.gz -rwxr-xr-x tranter/tranter 18171 2014-02-06 12:13 tarlocalfiles
By studying the source code for the examples, you can gain insight into how to use the libraries. Full API documentation for the libraries is also available, although it may be incomplete until closer to the final release.
In the past, the KDE libraries had many dependencies on the core of KDE and were difficult to use in pure Qt applications. They were also based on Qt 4. The move to KDE Frameworks 5 makes it much easier to use these libraries from Qt 5-based applications.
As a developer, you should become familiar with the functionality that the libraries offer so you can leverage them in your own programs and avoid writing code that already exists. You'll save time and improve code quality.
Some of the KDE Frameworks 5 may eventually show up in Qt itself. The QCommandLineParser class introduced in Qt 5.2.0 is an example of this.
While still in Tech Preview, you can access the latest KDE Frameworks 5 source code from Git(5). Expect to see an official release around the middle of this year.
- www.kde.org, KDE Project website
- dot.kde.org/2014/01/07/frameworks-5-tech-preview, Announcement of KDE Frameworks 5 Tech Preview
- projects.kde.org/projects/frameworks/karchive, KArchive website
- www.cmake.org, CMake Project website
- projects.kde.org/projects/frameworks/karchive/repository, Latest KArchive version from Git