Prelude

{Back to index}

Table of Contents

1 Introduction

Coding a program is meaningless if you don't know how to run it. This page shows how to do that plus some pitfalls specific to Plasma and how to work around them.

2 Hello JavaScript

This is the program 

print("Hello World!");

But how run it?

2.1 Install a JavaScript interpreter

Plasma or a web browser does ton of things at any given point. Our tiny first program isn't really that important to them. To start off simple we gonna use a JavaScript interpreter instead. It's task it to run our code and nothing else.

This is a bit of a mess, because of all distros the most popular (Ubuntu) hasn't got the one JavaScript interpreter everyone else offers: Mozilla's js. Ubuntu users should use rhino instead.

2.1.1 Mozilla js

This is a stand alone version of the JavaScript engine used in Firefox called SpiderMonkey. It's what I'll be using throughout this document, like 

% js foobar.js

The package which contains the js executable is

  • js for ArchLinux, OpenSUSE and Fedora
  • spidermonkey-bin for Debian

If you're not on Ubuntu, proceed. If you are on Ubuntu: no js for you! It is not in the repos. I suggest you use rhino instead.

2.1.2 Mozilla rhino

Back in the day when Netspace was still around they planned to rewrite their Netscape Navigator in Java. This is the origin of rhino, a JavaScript implementation entirely written in Java. Like its C sibling it's open source and maintained by the Mozilla foundation.

It will take forever to startup the first time you run it, but after that it's ok. When this documention says 

% js foobar.js

use 

% rhino foobar.js

instead.

The package name on Ubuntu is rhino.

Note: Only about Ubuntu I know for certain that its rhino package includes the /usr/bin/rhino shell script. On Archlinux you'd have to do 

% java -jar /usr/share/java/js.jar foobar.js

But why bother? Just use js.

2.1.3 Google v8

The v8 package contains the d8 JavaScript interpreter. If you have it installed and want to use it stead of js, then type 

% d8 foobar.js

instead of 

% js foobar.js

2.2 Hello World

Open your favorite editor, create the file foobar.js with the content 

print("Hello World!");

and run it in a shell 

% js foobar.js
Hello World!

Yay!

3 Hello Plasma

3.1 And there was metadata

We aim to have plasma run our little world script. 

print("hello world");

For this we have to create a plasma package. A package consists of its content, our JavaScript file, and meta data that describes this content and its role. The file tree of the simplest possible package looks like this 

hello_world
├── contents
│   └── main.js
└── metadata.desktop

The simplest possible and barely working meta data is 

[Desktop Entry]
Type=Service
X-Plasma-API=javascript
X-Plasma-MainScript=main.js

Now change to the directory hello_world, which contains the metadata.desktop file, and execute 

plasmoidviewer .

An empty default applet appears, since we haven't done anything to the user interface yet, and the text 

hello world

appears in the shell where we started plasmoidviewer

images/empty_default_applet.png

Empty default applet

3.2 plasmapkg

3.2.1 A rough start

To make our applet be usable for plasma we have to install it. We'll install it into our user directory 

% echo $(kde4-config --localprefix)

which will be something like /home/YOU/.kde or /home/YOU/.kde4, just paste it into the shel and see for yourself. The follwing command does the installation 

% plasmapkg -i .

But it won't work. It fails with 

plasmapkg(24248)/libplasma Plasma::Package::installPackage: Package plugin name not specified
Installation of /home/maik/.../hello_world failed.

Okay, lets add a name. The name is provided by X-KDE-PluginInfo-Name 

[Desktop Entry]
Type=Service

X-KDE-PluginInfo-Name=HelloFoobar
X-Plasma-API=javascript
X-Plasma-MainScript=main.js

Lets try again 

% plasmapkg -i .
Successfully installed /home/maik/Projekte/kde/plasmoids/javascript/textmon_tut/hello_world

Yay! Now we want to run it. Plasmoidviewer can to do that as well. Instead of giving a path to it, we give the name we've put into the meta data 

% plasmoidviewer HelloFoobar

But it won't work, again. You get

images/missing_servicetypes.png

Missing X-KDE-ServiceTypes

BUMMER! But wait, there is more fail to come. Before I explain what is missing, lets try to get rid if the faulty installation. You generally can remove plasma components with 

% plasmapkg -r PACKAGENAME

But 

% plasmapkg -r HelloFoobar

results in 

Plugin HelloFoobar is not installed.

WAT? That is clearly not correct. It is a bug in plasmapkg that I'll report ASAP, I promise. In the mean time do this 

% rm $(kde4-config --localprefix)/share/kde4/services/plasma-applet-HelloFoobar.desktop
% rm $(kde4-config --localprefix)/share/apps/plasma/plasmoids/HelloFoobar/ -r

instead.

What we have to add is the role this Service named HelloFoobar plays. It's a plasma applet: 

[Desktop Entry]
Type=Service

X-KDE-PluginInfo-Name=HelloFoobar
X-KDE-ServiceTypes=Plasma/Applet

X-Plasma-API=javascript
X-Plasma-MainScript=main.js

No we can not only 

% plasmapkg -i .
Successfully installed /home/maik/Projekte/kde/plasmoids/javascript/textmon_tut/hello_world

but also 

% plasmoidviewer HelloFoobar
hello world

as well as 

% plasmapkg -r HelloFoobar
Successfully removed HelloFoobar

Yay :D

This was a rough start, wasn't it? But fear not, besides some flaws like these it actually works quite well.

3.2.2 Three command switches you'll want to know

Since we have a package that plasmapkg can chew on without choking I suggest you play a bit with the options it provides. We already saw how to install 

% plasmapkg -i /path/to/package/dir/
% plasmapkg -i /path/to/package.plasmoid

where we used the first version with 

% plasmapkg -i .

We also, though unsuccessfully, used the command line to remove a package 

% plasmapkg -r PACKAGENAME
% plasmapkg -r /path/to/package/dir/

The second one reads the name of the package to remove from the metadata.desktop file in the directory it was given the path to. That's why 

% plasmapkg -r .

just reverts the things done by plasmapkg -i .. Well, once the bug mentioned above is fixed :P. Finally the plasmapkg command you'll be using most of the time is that to upgrading an existing package 

% plasmapkg -u /path/to/package/dir/
% plasmapkg -u /path/to/package.plasmoid

This actually removes the package and installs it again. For example 

% plasmapkg -u .

and 

% plasmapkg -r .
% plasmapkg -i .

do the very same things.

3.3 Give yourself a treat: Good error messages

Consider this code 

array = [1, 2, 3];

and break it 

array = [1, 2 3];

Put that into our main.js and see what plasma has to say 

% plasmoidviwer .

which is this:

images/syntax_error.png

Syntax Error: Parse Error. This means: dunno!

Well ok, parsing a programming language is hard. I'm sure they done as good as anybody can ask for, right? Lets see what the contenders have to say. Here Mozilla's js 

% js main.js
main.js:1: SyntaxError: missing ] after element list:
main.js:1: array = [1, 2 3];
main.js:1: ..............^

or Google's v8 (its command line debugger is called d8) 

% d8 main.js
main.js:1: SyntaxError: Unexpected number
array = [1, 2 3];
              ^
SyntaxError: Unexpected number

or rhino, as well done by Mozilla 

% rhino main.js
js: "main.js", line 1: missing ] after element list
js: array = [1, 2 3];
js: ...............^

Rhino is off by one dot, but still: wow!

A missing comma, brace and bracet is an frequent coding error. QtScript will give you the line number, that's it. If you have no idea what the heck its problem is, do yourself a favor by pasting the code in question into a file and have one of the above JavaScript interpreters a run at it. They of cause won't be able to run it, but they'll find the syntax error with a sweet error message.