Calligra/Developer Info

Introducing yourself

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.

Committing stuff

Always work against master branch. And then comes the moment you've created a nice feature or fixed a nasty bug. The first place of call is Phabricator (see also the HowTo).

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.

Tools

Coding

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

CMake is the build system for Calligra. KDE has many extensions to vanilla cmake, so there is no full manual available.

Unit tests

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

Useful websites

Techbase

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.

Bug tracker

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

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

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.

Hacking

There are some tutorials on techbase, for instance on creating a new Flake plugin. If you are getting lost, read the Calligra architecture overview for more information. Here's a short summary:

The libraries under Calligra are:

• db
• flake
• kokross
• kopageapp
• koplugin
• koproperty
• koreport
• kotext
• main
• odf
• pigment
• widgets

flake

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.

kokross

It is used mainly for scripting. It supports various scripting languages. It is mainly GUI based.

kopageapp

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.

koplugin

It is used for loading the plugins. Pigment depends on this.

koproperty

This library is used to handle property lists or key listing such as the properties of view, editors and so on.

koreport

It is used to produce formatted reports. Used in kexi and kplato

kotext

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.

main

Contains the base classes for applications, documents and views. Supports filter chaining and exporting and importing filters.

odf

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.

pigment:

It is used in color management and handling. It provides various Color Profiles.

widgets:

Used in handling widgets, such as progress bar updates, sliders, switching between the sheets,etc.