How to compile and run KDE4

...or rather how to setup a KDE4 development environment. There already is a howto on techbase, but I'm using my own scripts since years, and they work just fine. I've made them public in my user space on techbase: User:Dhaumann/Compiling KDE4. The howto is very short but complete. It does not have any troubleshooting sections. This is intentional: If you have any errors, fix them and rerun the scripts. Happy compiling :)

Feature Plan on TechBase

The Planned Features list is up and running again. It just needs to be filled. If you are a KDE developer you should consider to add your planned features to the list :) There are three templates you can use:

• {{FeatureDone|project|description|email-address|first-name name}}
• {{FeatureInProgress|project|description|email-address|first-name name}}
• {{FeatureTodo|project|description|email-address|first-name name}}

Another todo-item now is to merge the old feature lists into techbase.

Growing articles on TechBase

Right now TechBase has content in 19 languages. Sometimes articles grow bigger over time. How to build KDE4 is the prefect example. Here is a list of pages about building KDE4 (not counting translations):

• Getting Started/Build/KDE4
• Getting Started/Build/KDE4/Arch Linux
• Getting Started/Build/KDE4/Ark Linux
• Getting Started/Build/KDE4/Cygwin
• Getting Started/Build/KDE4/Fedora
• Getting Started/Build/KDE4/FreeBSD
• Getting Started/Build/KDE4/Gentoo
• Getting Started/Build/KDE4/Kubuntu and Debian
• Getting Started/Build/KDE4/Mac OS X
• Getting Started/Build/KDE4/Mac OS X 10.5 issues
• Getting Started/Build/KDE4/Mandriva
• Getting Started/Build/KDE4/Prerequisites
• Getting Started/Build/KDE4/Troubleshooting
• Getting Started/Build/KDE4/Windows
• Getting Started/Build/KDE4/Windows/3rd-party libraries
• Getting Started/Build/KDE4/Windows/Building DBus
• Getting Started/Build/KDE4/Windows/Building KDESupport Libraries
• Getting Started/Build/KDE4/Windows/Building Qt 4
• Getting Started/Build/KDE4/Windows/Environment
• Getting Started/Build/KDE4/Windows/GCC And MinGW
• Getting Started/Build/KDE4/Windows/Littlecms.patch
• Getting Started/Build/KDE4/Windows/MS Visual Studio
• Getting Started/Build/KDE4/Windows/MinGW Build Tips
• Getting Started/Build/KDE4/Windows/Windows Vista
• Getting Started/Build/KDE4/Windows/additional libraries
• Getting Started/Build/KDE4/Windows/emerge
• Getting Started/Build/KDE4/kdesvn-build
• Getting Started/Build/KDE4/openSUSE
• Getting Started/Build/KDE4 Alpha 1
• Getting Started/Build/KDE4 Alpha 2

That makes 30 pages. Some thoughts about this. Splitting up articles makes translation more difficult. There are more pages that have to be synced. It can be unclear where to find the information you are looking for. It's messy. What about

• 1 page »Distribution Specials«, instead of 11 separated pages?
• a cleanup instead of a split, if the page grows more and more?
• talk pages sometimes fit better?
  

Agreed, if pages really get long, a meaningful split makes sense. But sometimes it does not!? Thoughts? :)

TechBase: Contributing...

How you can help to make maintaining TechBase easier:

• login before you edit pages. Reviewing an edit of a logged in user is often as easy as "ah, user X, his content is ok anyway, next one..."
• do not use the "I-form". Who is 'I'? Noone knows. Especially not years later. Using 'I' in talk pages is perfectly fine. But please avoid it in articles :)
  

Reviewing TechBase Changes

KDE's techbase wiki is pretty much alive and I'm especially surprised that the translation system works really well. Of course there is some maintenance work to do and I'm reviewing every change so far.
I was away from Dec. 27th until 4th of January. Unfortunately, the "recent changes" feature allows me to see only the changes from 1st January till today. So if you have the RSS/Atom feed please review the changes from 27th until 31th of December and fix spam/typos/whatever you think needs to be fixed! :)

Encapsulation is not Information Hiding

As food for thought and in reply to Why Encapsulation is a Good Thing it's interesting to take a closer look. What does encapsulation mean exactly, and what can you do with it? Maybe what you really want is Information Hiding? ...and encapsulation is just a way of possibly achieving it? If you are interested in the details/differences, read the article Encapsulation is not Information Hiding.

To all TechBase Contributors

I've just added a new page which lists the KDE TechBase contributors. The idea is to have contact data for quick questions as well as build teams for different maintenance tasks. If you are active in the techbase wiki, please add yourself to the list - be it as a reviewer reading the RSS feed, translator or article writer...

Memory Leak Continued

There was some confusion with regard to my last blog about leaking memory. Suppose the ui_mywidget.h files looks like this:

class Ui_Widget
{
public:
   QGridLayout *gridLayout;
   QGroupBox *groupBox;
   QGridLayout *gridLayout1;
   QListWidget *listWidget;
   QSpacerItem *spacerItem;
   QPushButton *pushButton;

   void setupUi(QWidget *Widget);
   void retranslateUi(QWidget *Widget);
};

Of course, those 6 QObject derived classes are deleted. But the sizeof(Ui_Widget) = 6 * sizeof(void*) = 24 bytes are not deleted. As Ui_Widget is not QObject derived those 24 bytes leak. Confirmed by valgrind.

In a comment to my last blog Paolo suggested to use auto_ptr or scoped_ptr, which is more elegant than an extra wrapper class :)

Memory leak: Ui files and direct approach

The KDE codebase often uses a forward declaration in the .h-file to speedup compilation. The code often looks like this:

// header file
namespace Ui { class MyWidget; }
class MyDialog : public KDialog {
// ...
private:
Ui::MyWidget *ui;
};

The impl looks like this:

// source file
#include "mydialog.h"
#include "ui_mywidget.h"
MyDialog::MyDialog() : KDialog()
{
QWidget *w = new QWidget(this);
setMainWidget(w);
ui = new Ui::MyWidget(); // allocation
ui->setupUi(w);
// ui->...
}

See the memory leak? You have to call »delete ui;« in the destructor if you use the »direct approach«. Searching in lxr.kde.org shows lots of results, and in some places this delete is missing indeed. Happy fixing :)

---

Update: The really correct fix is to guard the pointer with an auto_ptr or scoped_ptr. For further details read the comments below. Or use another approach to include your ui-file.

---

If you do not want to delete it manually, you can for instance use a workaround like this:

// header file
namespace Ui { class MyWidget; }
class MyWidget;
class MyDialog : public KDialog {
// ...
private:
Ui::MyWidget *ui;
};

Source file:

// source file
#include "mydialog.h"
#include "ui_mywidget.h"

class MyWidget : public QWidget, public Ui::MyWidget {
public:
    MyWidget( QWidget * parent = 0 ) : QWidget( parent )
    { setupUi(this); }
};

MyDialog::MyDialog() : KDialog()
{
ui = new MyWidget(this);
setMainWidget(ui);
QWidget *w = new QWidget(this);
setMainWidget(w);
ui = new Ui::MyDialog(); // allocation
ui->setupUi(w);
// ui->...
}

Once in a while...

...I simply don't get it.
Recently there was this article on linux.com about [...]. Well, did you know that Konqueror can do all this, too, and much more? Launch Konqueror, split the view and you can transfer data right away with EVERY protocol KDE supports. ftp, fish, webdav and a lot other protocols. No need for an extra ftp client... In short, Konqueror is the best - and you can even use it on the Linux desktop.
...now I stumbled over this article on linux.com about [...]. In Konqueror you can do this for ages, too, the concept is called service menus. And it is very mighty and at the same time very simple to extend. And - if you have a look - there are thousands of context menus available, of course with the slight difference that contributors at kde-apps.org don't get 100$ for their work ;)
I wonder why such articles make it to linux.com at all. This is a drop of quality, imo. This is not about KDE vs. Gnome. It's about that articles should be objective and consider several alternatives. The first solution you read about isn't always the Holy Grail. Sorry for the rant.

PS: Maybe ed is the best text editor, I still prefer Kate, though. *blah* :-)

Kate Highlighting Power

Kate's highlighting capabilities are amazing. If you want you can highlight really complex syntax, without having to hardcode rules in C++. As an example, we'll take a look at how Lua comments can be realized:

• --[=[ starts a multiline comment (the '=' chars are optional)
• ]=] ends the multiline comment
• the number of '=' chars in ]=] must match the number of --[=[
  

That means: When the highlighting processor matches the end of a multiline comment, it has to know how many '=' chars started the comment. Thanks to the concept of dynamic rules and contexts Kate is able to do that. The highlighting file looks like this. First comes the header

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE language SYSTEM "language.dtd" >
<language name="Test" version="1.0" kateversion="2.4" section="Markup" extensions="" mimetype="">
  <highlighting>

Then the body with the contexts. We start in the first context called "Normal Text". When the regular expression --[(=*)[ matches it switches to the context Comment.

    <contexts>
      <context attribute="Normal Text" lineEndContext="#stay" name="Normal">
        <RegExpr attribute="Comment" context="Comment" String="--\[(=*)\[" dynamic="true"/>
      </context>

The part (=*) is now available as %1 in the rule below:

      <context name="Comment" attribute="Comment" lineEndContext="#stay" dynamic="true" >
        <RegExpr attribute="Comment" context="#pop" String="\]%1\]" dynamic="true" />
      </context>
    </contexts>

The last part is the footer:

    <itemDatas>
      <itemData name="Normal Text" defStyleNum="dsNormal" />
      <itemData name="Comment"     defStyleNum="dsComment" />
    </itemDatas>
  </highlighting>
</language>

If you want to know more about Kate's highlighting, have a look at the documentation :) There are also lots of bug reports, so if you want to contribute you can fix them!

PS: As I don't know much about Lua, comments might work differently. That does not really matter, as the example still shows what you can do :)

List of new KDE features

Hi, our list of KDE features heavily lacks updates :)
So everyone checkout

trunk/www/sites/developer/development-versions

and update kde-features.xml :) At some point we'll enable the techbase extension so the list shows up there as well.

OT: T-Online Software

I had to install the "T-Online Software 5" recently on a Win98 box. Starting the T-Online setup a message popped up:

You need at least Internet Explorer 5.5. Setup terminated!

Sigh, I found a IE5.5 offline setup. Next try:

You need at least a resolution of 800x600. Setup terminated!

I found the graphics card chip, installed the drivers and switched the resolution. Next try:

The language version of the OS is not German. Setup terminated!

Now that is clearly how software should not work. It seems to be impossible to install the T-Online software. I would install Linux, but it's quite a change for a ~90 years old user :(

Extending Kate by Scripts

We have seen how scripting basically works for indentation. It's also possible to register commandline functions (The command line is bound to F7 by default, or invoke View > Switch to Command Line). We will consider a small example again: sort the selected text.

/* kate-script
 * name: unused
 * author: foo bar
 * license: LGPL
 * version: 1
 * kate-version: 3.0
 * functions: sorter
 */

function sorter ()
{
    if (view.hasSelection()) {
        var start = view.startOfSelection().line;
        var end = view.endOfSelection().line;

        var text = document.textRange(start, 0, end, document.lineLength(end));

        var lines = text.split("\n");
        lines.sort();
        text = lines.join("\n");

        view.clearSelection();

        document.editBegin();
        document.removeText(start, 0, end, document.lineLength(end));
        document.insertText(start, 0, text);
        document.editEnd();
    }
}

The header line functions: sorter makes Kate Part aware of the function in the script. A list of functions is supported, separated by white spaces. You can use the function by typing 'sorter' in the commandline.
Some todo items:

• provide better JavaScript API. For example: document.textRange() takes 4 parameters. It would be more elegant to take one range or two cursors, just like we do in the KTextEditor interfaces in kdelibs/interfaces/ktexteditor
  
• make is possible to bind scripts to shortcuts. This could be done by e.g. binding commandline functions to shortcuts or implementing a vim-like command-mode in Kate's commandline. How to configure the shortcuts is unclear, though.
• then, think about replacing the C++ implementations of 'uppercase', 'lowercase', 'capitalize' etc. with scripts
• things I forgot...

If you are interested subscribe to kwrite-devel@kde.org and contribute :) We also need indentation scripts, of course!

Kate: More on Indentation Scripting

My last blog was about the theory of how indentation works by using javascripts. Now we will look at a concrete example: a LISP-style indenter. (LISP indentation is easy, that's why it's a good example).
The rules:

• comments starting with ;;; always have indentation 0
• comments starting with ;; should be aligned with the next line
• comments starting with ; should only appear behind code, so they are simply ignored
• every '(' indents and every ')' unindents

lisp.js looks like this:

/** kate-script
 * name: LISP
 * license: LGPL
 * author: foo bar
 * version: 1
 * kate-version: 3.0
 * type: indentation
 */
// indent should be called when ; is pressed
triggerCharacters = ";";
function indent(line, indentWidth, ch)
{
    // special rules: ;;; -> indent 0
    //                ;;  -> align with next line, if possible
    //                ;   -> usually on the same line as code -> ignore
    textLine = document.line(line);
    if (textLine.search(/^\s*;;;/) != -1) {
        return 0;
    } else if (textLine.search(/^\s*;;/) != -1) {
        // try to align with the next line
        nextLine = document.nextNonEmptyLine(line + 1);
        if (nextLine != -1) {
            return document.firstVirtualColumn(nextLine);
        }
    }

    cursor = document.anchor(line, 0, '(');
    if (cursor) {
        return document.toVirtualColumn(cursor.line, cursor.column) + indentWidth;
    } else {
        return 0;
    }
}

The result:

;;; fib : number -> number
(define (fib n)
  (if (< n 2)
    1
    (+ (fib (- n 1)) (fib (- n 2)))))

As this indenter is scripted, everybody can adapt the style to the own needs.

Kate Scripting: Indentation

Kate Part in KDE4 supports the ECMAScript (JavaScript) language by using kjs. In KDE3 we had several hard-coded indenters in C++, the idea is to let scripts do all the indentation in KDE4.
How does it work? It is similar to vim: You simply create a script in the directory $KDEDIR/share/apps/katepart/jscript. An indentation script has to follow several rules:

1. it must have a valid script header (the first line must include the string kate-script and indentation scripts must have the type: indentation)
   
2. it must define some variables and functions

Whenever the user types a character, the flow in Kate Part works like this

1. check the indentation script's trigger characters, i.e. whether the script wants to indent code for the typed character
2. if yes, call the indentation function
3. the return value of the indentation function is an integer value representing the new indentation depth in spaces.

In the 3rd step there are 2 special cases for the return value:

1. return value = -1: Kate keeps the indentation, that is it searches for the last non-empty line and uses its indentation for the current line
2. return value < -1 tells Kate to do nothing

So how does a script look like exactly?
The name does not really matter, so let's call it foobar.js:

/* kate-script
* name: MyLanguage Indenter
* license: LGPL
* author: Foo Bar
* version: 1
* kate-version: 3.0
* type: indentation
*
* optional bla bla here
*/

// specifies the characters which should trigger indent() beside the default '\n'
triggerCharacters = "{}";

// called for the triggerCharacters {} and
function indent(line, indentWidth, typedChar)
{
// do calculations here
// if typedChar is an empty string, the user hit enter/return

// todo: Implement your indentation algorithms here.
return -1; // keep indentation
}

More details on the header:

• name [required]: the name will appear in Kate's menus
• license [optional]: not visible in gui, but should be specified in js-files. it is always better to have a defined license
• author [optional]: name
• version [optional]: recommended. an integer
• kate-version [required]: the minimum required kate-version (e.g. for api changes)
• type [required]: must be set to indentation

The only missing part is the API which Kate Part exports to access the document and the view. Right now, there is no API documentation, so you have to look at the code:

• kdelibs/kate/jscript/katejscript.cpp search for "@Begin" tags
  

You will find, that the current document exports functions like

• document.fileName()
• document.isModified()
• document.charAt(line, column)
• etc...

The view exports functions like

• view.cursorPosition()
• view.hasSelection()
• view.clearSelection()
• ...

That's the boring part of this blog. The interesting one is unfortunately shorter: we are looking for contributors who want to write scripts or help in the C++ implementation :)

Luggage continued

Quick notice: I have my bag back. It was wet inside -- probably for 2 weeks, no wonder it started to get moldy inside, and I'm not sure yet whether I can use some of the clothes. Well done BA & Heathrow.

Deeply impressed...

Hey, I wasn't aware there was another one who did not get his luggage at all in Glasgow. I traveled from Frankfurt(Germany) to London (Heathrow) and then on to Glasgow. When I arrived, my luggage was missing. British Airways told me it would still be in London but it should arrive the same day and they would bring it to the Euro Hostel - cool :) How naive! Of course it did not arrive... and it didn't arrive the whole week.
The online status always said "Still tracing, check back later". When I flew back I asked at the Glasgow airport again and was told they can not see more than what I see online. When I asked whether they could call London/Heathrow by phone they said in London/Heathrow 20.000 bags are missing so it would be pointless. If the system is so unreliable, why don't they simply close the airport. moo
When I arrived in London I asked again, and a BA-service guy told me he could see that my luggage was being sent to Glasgow by road. By road??? Hell, it takes them 1 hour by plane, so what? And I even told them that I would leave this day. So why to Glasgow at all now?
Well, finally I sat in the plane... which ironically had a delay because it had one bag too much. Hey, that could have been mine... :)
Back in Frankfurt I asked again, and at least this time they were capable of changing the destination address to where I live in Germany. Strange, I told them in Glasgow in the first place, but they seem to be pretty much incapable... :)
So here we go: Back in Germany... in the meanwhile I wondered whether I'd see my bag ever again. Today, almost 2 weeks later, the state incredibly changed to "Received at the airport, delivery in progress". Wow, I'm deeply impressed... really great job. Wait: at which airport? Glasgow? London? Frankfurt? Or somewhere else in the world? *sigh*
So in short: I still don't have my luggage back... :)

Translation of TechBase

As contributors started to translate articles in TechBase to other languages I wrote a quick howto which explains the translation system. It is pretty easy since danimo simplified it with a nifty template :)

Quickies: classmapper, tb

api.kde.org got an overhaul, the redirect of the old class mapper does not work yet, so just edit your web shortcuts and change the one for 'kde:' to point to

• http://api.kde.org/classmapper.php?class=\{@}
• appending &version=3.5 will search in KDE3.5
  

Thanks to Bram, we have a new article called How to create useful crash reports in our tb. It is mainly aimed at users who fill in bug reports in KDE's bug tracking system.