[lively-kernel] Contributing source code to the Lively Kernel

[Robert Krahn]

Dear list --

One very important topic that currently is not specified anywhere is how you can contribute source code to the project. In this post I will explain the system support for modularization and describe how contributions could be created and organized using Lively Wiki. Improvement suggestions are very welcome -- and of course you might want to try it out ;-)

Important: Source code contributions should be MIT licensed. Please only upload your code if you are willing to accept this license.


Part 1: Modules

In Lively Kernel we use so called 'modules' to identify JavaScript and other source code files. On top of most files you will see something like this:

module('lively.ide').requires('lively.Tools', 'lively.Ometa').toRun(function() {
// Code depending on lively.Tools and lively.Ometa
}) // end of module

This definition does two things:

a) Define the module lively.ide. The module can then be required from somewhere else:
require('lively.ide').toRun(function() { new lively.ide.SystemBrowser().open() })
Evaluating this will let the system:
1. Check if lively.ide is loaded. If not then the module name is translated to an URL: {Config.codeBase}/lively/ide.js. That URL will be used to load the file ide.js asynchronously. *
2. When the file is loaded run the code of toRun()

b) Define the namespace lively.ide.
That means that if the module is there you can access it's members in JavaScript. For example the class lively.ide.SystemBrowser is such a member. **


Part 2: Using modules to add your extensions

The first thing you need is some place to store your source code and your data. You can create your own subdirectory in the wiki here: http://www.lively-kernel.org/repository/lively-wiki/CreateUserDirectory.xhtml

Your directory includes a WorldTemplate.xhtml that you can clone to create new pages. You can then add new Worlds and add source code in them using the local changes (and the Local code Browser, you find it in the Tools menu). Or you can create your own JavaScript files using the System browser or manually by checking out your directory using SVN and adding/editing files with a TextEditor. The JavaScript files should include a module definition.

Example: My users directory in the wiki is /users/robertkrahn/. I can then add a test.js that can be loaded with
require('users.robertkrahn.test').toRun(function() { /* code */ })
from anywhere in the wiki.

Of course you can also add source code and subdirectories elsewhere. Assuming you want to add audio support you might want add a subdirectory audio to http://www.lively-kernel.org/repository/lively-wiki/.

When your extension is stable enough it can be added to the Lively Kernel repository.

Bugfixes to existing sources can of course go directly to the kernel repository.


Best,
Robert


* Config.codeBase is a config option and contains the URL to the root directory. It is defined in defaultconfig.js. There it is set to the containing directory of the current document. It can be redefined later if necessary.

** Using the namespace inside a module is NOT enforced. This means if you define a class Object.subclass('SystemBrowser', {...}) it will "extend" the Global namespace. This means that you can access the class via Global.SystemBrowser (or simply with SystemBrowser). Only if you use the namespace explicitly Object.subclass('lively.ide.SystemBrowser', {...}) the namespace will be used and you can access the class via Global.lively.ide.SystemBrowser (or simply lively.ide.SystemBrowser). We might change that in the future to enforce namespace usage.
-------------- next part --------------
An HTML attachment was scrubbed...
URL: http://lists.hpi.uni-potsdam.de/archive/lively-kernel/attachments/20100414/f9ba6e43/attachment.htm