Sugar Labs - User contributions [en]

Dextrose/Building

2010-10-27T10:28:07Z

Mk8:

== Build system ==

Dextrose uses [http://wiki.laptop.org/go/OS_Builder olpc-os-builder], a tool create by OLPC to build official and customized system images. The Dextrose git repository contains, olpc-os-builder, local customizations specific to Dextrose, and fixes and enhancements waiting to be pushed upstream.

== Build host requirements ==

The Dextrose build system runs on '''Fedora 11 i386''' through '''Fedora 13 x86_64''' ('''Fedora 14 beta''' can be used also). The host system runs '''shouldn't''' matter, because the build runs in a chroot environment. olpc-os-builder does not yet run on Ubuntu due to a missing dependency.

The initial build requires about '''700MB''' of rpm packages and Sugar activity bundles. The packages and bundles are cached for futures builds.

== Initial setup ==

* Install dependencies (you need to be root to do this)

yum upgrade
yum install libtomcrypt-devel bitfrost make gcc mtd-utils python-imgcreate zip unzip zlib-devel

* Checkout Dextrose build system

git clone git://git.sugarlabs.org/dextrose/mainline.git dextrose

* Compile build helper programs

cd dextrose
make

* Generate initial sequence number for the builds (42 is just for an example)

echo 42 >buildnr-dx

== Creating a build ==

* Run the Build (again you need to be root to able to do this)

time ./osbuilder.py examples/dextrose2-xo1.ini

obviusly you can use sudo if your user is configured to do this, and the you can use this

time ./osbuilder.py examples/dextrose2-xo1.ini

The initial build may take several hours depending on available bandwith. Subsequent builds will take about 15-20 minutes

Upon completion the new image is available at <tt>build/output</tt>.

Because several build tools, olpc-os-builder, imgcreate and yum, are nested, error output could be misleading or obscure. Before digging into code, you please ask on IRC in case someone has already seen the same problem.

== Publishing the images ==

Please do not publish signed builds unless they implement the [http://wiki.laptop.org/go/Antitheft_HowTo OLPC anti-theft system].

== Customizing your build ==

olpc-os-builder is documented at
[http://git.sugarlabs.org/projects/dextrose/repos/mainline/trees/master/doc/README README]
in the olpc-os-builder tree. The modules are documented in <tt>README</tt> files in the
[http://git.sugarlabs.org/projects/dextrose/repos/mainline/trees/master/modules modules] directory.

=== Upstream Code ===

Dextrose is based on upstream olpc code located at dev.laptop.org.

git remote add olpc git://dev.laptop.org/projects/olpc-os-builder
git fetch olpc
git log olpc/master

=== Customizing the core RPMs ===

* Go to the <tt>rpms/PACKAGENAME</tt> in the dextrose tree

* Edit the spec file. Typically this involves adding a new patch, which is done by adding a <tt>PatchNN:</tt> tag and a corresponding <tt>%patchNN</tt> rule in <tt>%setup</tt>. Some of the intricacies of RPM spec files are unveiled in the [http://fedoraproject.org/wiki/Packaging/Guidelines Fedora Packaging Guidelines].

* Increase the release number after each change.

=== building the Custom RPM ===

If you have a Fedora 11 i386 system, just type:

make i586

Otherwise, you need to build in a [http://fedoraproject.org/wiki/Projects/Mock mock] chroot:

make srpm
sudo mock -r fedora-11-i386 --resultdir=. --rebuild mypackage.src.rpm

=== Uploading the Custom RPM ===

* Upload rpm to a yum repository and add it to the ini file used by the OLPC OS builder.

* To automate this step, we have a rule <tt>make uploadrpm</tt> which points at the Dextrose repository. Edit <tt>rpms/common/Makefile.common</tt> or <tt>rpms/common/uploadrpm</tt> to retarget this rule to your repository.

=== Building custom kernels ===

$ git clone http://dev.laptop.org/git/olpc-2.6/
$ cd olpc-2.6
$ setarch i386 make ARCH=i386 xo_1-kernel-rpm

== Resources ==

* [http://wiki.sugarlabs.org/go/Development_Team/Jhbuild Sugar-jhbuild] - The Sugar Labs build system.

* [http://www.rpm.org/wiki/Docs Rpm] - The Redhat package manager.

* [http://fedoraproject.org/wiki/Packaging/Guidelines Fedora packaging] - Fedora packaging workflow and conventions.

* [http://createrepo.baseurl.org/] - The yum package repositories builder.

* [http://activities.sugarlabs.org] - The Sugar Labs activities library.

* General understanding of the Linux system plumbing infrastructure: [http://www.kernel.org/ kernel],
[http://www.kernel.org/pub/linux/utils/kernel/hotplug/udev.html udev], [http://www.freedesktop.org/wiki/Software/dbus dbus], [http://www.freedesktop.org/wiki/Software/DeviceKit DeviceKit], [http://www.freedesktop.org/wiki/NetworkManager NetworkManager],
[http://www.x.org/wiki/ Xorg]...

* Flashing laptops and debugging any problems

* Interaction with the Sugar and OLPC community to solve issues and minimize our divergence from the official builds.

Mono

2008-12-08T10:26:13Z

Mk8: New page: {{Developers}} {{Stub}} Sugar activities are usually written in Python using the Python Activity API. This page documents how it is possible to use Mono to write a Suga...

{{Developers}}
{{Stub}}

Sugar activities are usually written in Python using the [[API_Reference|Python Activity API]]. This page documents how it is possible to use Mono to write a Sugar activity. With Mono, you can use any underlying language like C# or Boo.

=Overview=

=XO Bundle and Mono Bundle=
To write an OLPC Mono activity, you need to prepare a .xo [[Bundle]] including all required libraries. This is necessary because the Mono runtime is not officially supported by the OS images.

If you use Mono, you know that the C# compiler does not traslate the source to machine code, but to an IL (Intermediate Language) that requires a runtime to be executed. Since you don't have the runtime installed on the XO, you need to create a Mono bundle so the runtime is packed with the executable.

To do this, you need to have the program already in binary format and use the mkbundle2 utility to create the stand-alone application.

mkbundle2 --config /etc/mono/config --deps --static -o MonkeysMemory.exe monkeysmemory.exe

In this example "monkeysmemory.exe" is the original IL binary file, while "MonkeysMemory.exe" is the binary file that can be run without runtime installed.

Normally, --static flag means that LGPL code is linked statically with your application.
A special exception is made for OLPC users where the LGPL restrictions does not apply when you create activities.

In your bundle you need to put some glue shared libraries that are used by the Mono runtime like this:

* libgdksharpglue-2.so
* libgladesharpglue-2.so
* libglibsharpglue-2.so
* libgtksharpglue-2.so
* libMonoPosixHelper.so
* libpangosharpglue-2.so
* uiX11Util.so

All these files (except uiX11Util.so) are taken from mono environment. The last one (uiX11Util.so) is
OLPC specific and allows to setup some X11 atoms needed by the Sugar interface.
These files are placed in the bin directory of the activity.

=How to run a Mono activity=
I suppose that you are able to install an activity on the OLPC, but how to create a standard activity bundle?
You can find all documentation you need about the contents of a XO Bundle file [[Bundle]] but here give a look inside the activity luncher script.

This example of activity launcher is taken from the e-toys launcher with some little adjustment and is placed in bin directory.
The name of this script is specify in the ''activity-info'' file:

#!/bin/sh
# Author: Torello Querci
# Original Author: Bert Freudenberg
# Purpose: Run binary application. In this case Monkey's Memory
#
# This version of etoys-activity is called only under new Sugar
# (Joyride/Update.1). There is another one in the bundle's root
# directory called under old Sugar which was pre-installed on the
# first mass-produced machines (Trial-3/Ship.1).
echo "$0" "$@"
echo

# arguments are unordered, have to loop
args=""
while [ -n "$2" ] ; do
case "$1" in
-b | --bundle-id) bundle_id="$2" ; args="$args BUNDLE_ID $2" ;;
-a | --activity-id) activity_id="$2" ; args="$args ACTIVITY_ID $2";;
-o | --object-id) object_id="$2" ; args="$args OBJECT_ID $2";;
-u | --uri) uri="$2" ; args="$args URI $2";;
*) echo unknown argument $1 $2 ;;
esac
shift;shift
done

# really need bundle id and activity id
if [ -z "$bundle_id" -o -z "$activity_id" ] ; then
echo ERROR: bundle-id and activity-id arguments required
echo Aborting
exit 1
fi

# some debug output
echo launching $bundle_id instance $activity_id
[ -n "$object_id" ] && echo with journal obj $object_id
[ -n "$uri" ] && echo loading uri $uri
echo

export SUGAR_BUNDLE_PATH=`dirname $0`
export PATH=$SUGAR_BUNDLE_PATH:$PATH

cd $SUGAR_BUNDLE_PATH/..
export LD_LIBRARY_PATH=$SUGAR_BUNDLE_PATH:$LD_LIBRARY_PATH

# Try to setup the SHARED_DIR
export MONO_SHARED_DIR=$TMPDIR

# now run the application
exec MonkeysMemory.exe \
-sugarBundleId $bundle_id \
-sugarActivityId $activity_id \
$args < /dev/null > /dev/null

If you look inside the code script you can find some specific instruction:
* the home directory is changed from the internal bin directory to the parent one. This is not mandatory but is useful for me;
* it is setup the LD_LIBRARY_PATH environment variable. This is needed because the application need to find the specific shared object;
* it is setup the MONO_SHARED_DIR non-system environment variable. This is needed because Mono normally use a special shared internal repository to track the state of mutex across multiple process and this repository is written on /tmp. Since the normal /tmp directory is not writeble from the application in the OLPC security schema, is necessary to change the default path used to store this repository.

Obviously MonkeysMemory.exe is a sample activity name and is not necessary that the application have the .exe suffix because is e normal linux application.

'''Note: the script is changed from previous version because Rainbow isolation subsystem now not create for the process the the stdin and stdout handles. This is not compatibile with some version of mono runtime.'''

= Interfacing with the native subsystem =

== Creating a new application ==

To create a sugarized application with Mono you can use the Sugar.Window class in place of the common Gtk.Window.
This class inherits from Gtk.Window and adds all the code necessary to integrate with Sugar's activity interface.
The constructor of this class expects two parameters that were passed by the startup script. Therefore, your Main function needs to parse its command-line arguments to isolate:
* activityId
* bundleId
The Sugar.Window class adds a new event, '''SetActiveEvent''', generated when Sugar switches between zoom levels.

== Sugarizing an existing application ==

TODO

= Example Activity written in Mono =

You can find [http://mk8.codewiz.org/olpc/MonkeysMemory-13.xo a sample activity] written using Mono. [[MonkeysMemory | Here]] you can find the specific page about this activity.

= Assembly dependency =
To write or migrate your application to OLPC activity you need to use a specific assembly that manager the DBus event and the X property needed to Sugar environment. This assembly use the NDesk.DBus one to manage the DBus message. You can find the NDesk.DBus assembly in your distribution or from the source [http://www.ndesk.org/DBusSharp here].

The source code of sugar assembly can be found [http://mk8.codewiz.org/wiki/sugar-0.1.tgz here].