- 1 Introducing yourself
- 2 Coding style and licensing
- 3 Committing stuff
- 4 Tools
- 5 Hacking
We like to know who you are! If you want to start hacking on Calligra you are very welcome. Come and join us on #calligra on irc.freenode.org (or #krita if Krita grabbed your interest). Send a mail to [email protected] and tell us who you are and what you're working on.
Coding style and licensing
Be aware of the KDE-wide set of policies: | Policies for Developers. If anythinghere confuses you, don't hesitate to ask.
Please follow the [ coding style guidelines]! Change the configuration of your editor if necessary. Some editors can have per-project settings.
All files must have a license. For Calligra you can use LGPL v2+ (all libraries, most aplications, most plugins) or GPL v2+. For some plugins, LGPL version 2.1 (no plus) is acceptable as well. Your full, real name must be in the license header.
After your patch gets a "Ship it!", ask a Calligra developer to commit the patch for you. Once you have shown to are comfortable putting together acceptable patches, you can apply for a Developer account. This will then allow to push your patches yourself to the Calligra codebase.
Anatomy of a Commit message
- Title: A one line description about the commit. Make sure that the title is relevant so that searching later becomes easy.
- blank line
- Description: Detailed description about the commit.
There are a couple of useful tags:
BUG: <bugnumber> Marks the bug as fixed by CC'ing the commit message to <bugnumber>[email protected] This keyword will also be used to automatically extract entries for the release changelog.
CCBUG: <bugnumber> CC's to the bugreport by sending mail to <bugnumber>@bugs.kde.org
CCMAIL: <email-address> CC's to the given e-mail address.
Some other useful commit key words:
* GUI: Indicates a user visible change in the user interface. This is used to make the documentation team aware of such changes.This keyword can appear anywhere on a line. * GIT_SILENT Marks the commit message "silent" by adding "(silent)" to the subject of the mail to allow filtering out trivial commits. Use this tag carefully and only for really uninteresting, uncontroversial commits.
You do not need a specific IDE to work on Calligra. Some IDE's people use are KDevelop, Qt Creator, Eclipse. Others use plain editors: Kate, Kwrite, vi(m), Emacs. It's a matter of your personal preference!
CMake is the build system for Calligra. KDE has many extensions to vanilla cmake, so there is no full manual available.
Calligra has a suite of nearly two hundred unittests. Unittests are run regularly to ensure that we have a minimum of regressions. After writing code, you should always run the relevant unittests!
To be able to run unit tests, you need to explicitely enable them in the build configuration. To do so, set the KDE4_BUILD_TESTS variable to "ON", either by issuing the command cmake -DKDE4_BUILD_TESTS=ON, or by running ccmake .. Both commands must be executed in the build directory. You can then run the test with make test, or individually in the tests directories. It is recommended to call make install before running tests.
If you fix any bug or any feature it should be accompained by ideally unit test cases. calligratests containing lot of good documents to test. So if you make any feature try to run calligratests so that it will ensure no breakage.
Valgrind and kcachegrind
Valgrind is used for three things: check errors in memory handling (memory leaks and accessing deleted memory), analyzing memory consumption and analyzing the performance of an application.
- Memory errors: valgrind --tool=memcheck --error-limit=no app args
- Memory consumption: valgrind --tool=massif app args
- Performance profiling: valgrind --tool=callgrind app args
At program termination, a file callgrind.out.pid will be generated, which can be loaded into KCachegrind.
More information at using valgring
Techbase is a wiki where all the developer information about kde is stored. Calligra is built on KDE, so this is a very valuable resource.
The bug tracker stores all KDE (and Calligra) bugs and wishes users report. If you feel bored, you can trawl through bugs.kde.org and see whether there's a bug that appeals to you!
English Breakfast Network (EBN) is a website that regularly checks all KDE and Calligra code for common coding mistakes, documentation errors, user documentation validation and so on.
LXR allows users and developers to browse the KDE source code complete with cross-references. This is particularly useful if you want to figure out where some code is used.
6. http://paste.kde.org/ If you have more than one line of code to share with someone on the IRC or any other place do use this website. Here you can post your code and share the link on the IRC. Any one on the IRC can then access this link to view your code.
The libraries under Calligra are:
Its a library which basically provides 'shapes', which contains various kinds of media. They provide Canvas Widget, on which Calligra apps are built on. Canvas can infact get mouse and keyboard controls.
It is used mainly for scripting. It supports various scripting languages. It is mainly GUI based.
Used for Single Page based application. This means that, the documents can indeed have multiple pages, but not continuing from one page to another. Used in Kivio and Kpresenter.
It is used for loading the plugins. Pigment depends on this.
This library is used to handle property lists or key listing such as the properties of view, editors and so on.
It is used to produce formatted reports. Used in kexi and kplato
One of the main libraries on Calligra. It is used in loading the text, to do various text handling, parsing of files, handling the text layout, gives layout API definitions,etc.
Contains the base classes for applications, documents and views. Supports filter chaining and exporting and importing filters.
Another important library. ODF stands for Open Document Format. It is an XML based format. Supports various kinds of documents, spreadsheets, presentations,etc.
An odf file is basically a zip archive with filter specific content.
It also handles validation and encryption.
It is used in color management and handling. It provides various Color Profiles.
Used in handling widgets, such as progress bar updates, sliders, switching between the sheets,etc.