About

Sugar is made of several modules and sometimes depends on libraries which have not yet been packaged in Linux distributions. To make it easier for developers to build from sources, we developed sugar-build, a set of scripts that automates builds and other common development tasks.

Warning: sugar-build depends on Fedora 23, which is no longer supported by Fedora, having begun End of Life late in 2016. Developers are needed to change distro in build/root.json and verify and test all new dependencies.

Note: the development environment requires Linux. If you are running Windows or OS X, you must install a Linux virtual machine before continuing. Not covered here.

Installing

First of all clone the sugar-build git repository

git clone git://github.com/sugarlabs/sugar-build.git

Change to the directory and pull the remaining source code.

cd sugar-build
./osbuild pull

Build the source.

./osbuild shell
build

Run Sugar.

run

If anything goes wrong, read the common issues section or subscribe to the sugar-devel mailing list, and send an email. We will usually reply within 48 hours.

Common Issues

sugar-build frequently stops working when upstream dependencies have changed, requiring changes to sugar-build, Sugar, toolkit, or activities. If you are not able to resolve these issues, then sugar-build may not be a suitable tool for you. Choose other development tools for developing with Sugar.

sugar-build may fail for people behind web proxies. Usually this is shown as a proxy error in the pip command or an issue with the volo command.

pip may fail while installing Python packages:

MissingSchema: Proxy URLs must have explicit schemes.

This happens if you have no schema for your http_proxy environment variable. To fix, add the URL schema by prefixing http, for example http_proxy=localhost:3128 would be changed to http_proxy=http://localhost:3128.

If this does not work, you can also try the method mentioned below:

volo may fail, for example:

* Building sugar-web

Command failed: volo -nostamp -f add

Error: connect ECONNREFUSED

If this happens, you have 2 options. Best is to run your first build in an environment without a proxy. Otherwise, remove the sugar-web module. You will not be able to develop Sugar web activities. To remove the sugar-web module, open build/modules.json file and delete the following lines:

    {
        "has_docs": true,
        "has_checks": true,
        "name": "sugar-web",
        "repo": "https://github.com/sugarlabs/sugar-web.git",
        "clean_stamp": 1
    },

Developing

All the sources are inside the sugar-build directory. You can make changes using any text editor. If Sugar is already running stop it, then restart it with

./osbuild run

Once in a while update to the latest sources

./osbuild pull

Commands reference

You can run the commands as osbuild arguments

./osbuild build
./osbuild run

Or inside a shell

./osbuild

[sugar-build $] build
[sugar-build $] run

The following commands are available

pull

Pull the latest source code. All modules are pulled unless one is specified.

build

Build the source code. All the modules are built unless one is specified.

run

Run sugar.

check

Run tests for sugar-build and all the modules that provides them. It should usually be run before submitting patches or pushing changes.

clean

Delete the build artifacts. If a module is specified only the source directory of that module is cleaned.

shell

Open a shell inside the build environment.

Preferences reference

You can set a few options by creating a sugar-build/prefs.json file. For example

{
    "output": "HDMI1",
    "resolution": "1024x768"
}

The following preferences are available

github

You can specify a list of forks and repositories for which you have ssh access, so that remotes will be setup automatically for those. For example

{
    "github": {
        "forks": [
            "myname/sugar.git",
            "myname/sugar-docs.git"
        ],
        "ssh": [
            "sugarlabs/sugar.git",
            "sugarlabs/sugar-docs.git"
        ]
    }
}

When adding a new module to the lists, you need to delete its directory for the remotes to be switched over.

resolution

This option is only valid when running from X Window. It specifies the resolution of the window containing the sugar desktop in the form [width]x[height]. Otherwise the whole screen is used.

output

This option is only valid when running from a text console. Sugar does not work properly on multiple video outputs, so we need to select one and turn off the others. By default we select the first output listed by RandR. You can set this variable to override that with any other of the connected outputs reported by the xrandr command, for example VGA1 if you have an external monitor.

use_broot

Set the option to false if you don't want to build and run in a chroot. If you don't know what that means you'd better not use the option. This is currently supported only on Fedora 19, on other distributions it's likely to fail unless you manually install the required dependencies.

More configuration options

activities

When you first build the development environment, you will notice that there are only a few activities installed by default. In Sugar, additional activities are usually stored in

~/Activities

However in the development environment, they are stored in

sugar-build/activities

Please note that the sugar-build/activities often won't get created until the user installs or creates an Activity in the sugar-build. For Installation of an activity please refer to this Manual and for the creation of your own Activity, you can see the Activity Creation page.

Tip for testing and debugging purposes: In order to run multiple versions of the same activity, they need to have different bundle ids, so you have to change the bundle_id in activity.info file in one of them. For example, I have version 39 of Calculate Activity installed and I want to install the version 41 without removing the installed one. In order to do so, just go to the directory of the v41 and go to Calculate.Activity/activity and then open the activity.info file and change the bundle_id of it. After doing that, you will be able to install v41 without removing the previously installed version.

dotsugar

By default, Sugar stores configuration files, logs, and the datastore in

~/.sugar

In the dev-enviroment, these files are stored in

sugar-build/home/dotsugar

change debugging level

You can enable debugging in Sugar modifying the file

sugar-build/home/default/debug

and uncommenting the line:

#export SUGAR_LOGGER_LEVEL=debug

This file is located in

~/.sugar/default/debug

when is not run in sugar-build. The file also allows enable debugging for specific parts of the stack, like collaboration.

For debugging Salut or Gabble use:

FOO_PERSIST=1 FOO_DEBUG=all WOCKY_DEBUG=all G_MESSAGES_DEBUG=all FOO_LOGFILE=/tmp/foo.log *command*

Note: Replace FOO with SALUT or GABBLE. When debugging Gabble, it's usually a good idea to set WOCKY_DEBUG=xmpp (Gabble 0.9) or LM_DEBUG=net (Gabble 0.8) so that the XML stanzas are also captured in the logfile.

For more refer 1 2

gsettings

Sugar uses gsettings for a number of different settings. In the development environment, these settings are found in

sugar-build/home/default/config/dconf

osbuild check uses its own gsetting. These can be found in

sugar-build/home/check/config/dconf

Multiple instances

To run multiple instances of sugar-build, enter the shell and

SUGAR_PROFILE=test1 run &
SUGAR_PROFILE=test2 run &

Log files

Log files for osbuild are found

build/logs

Log files for Sugar and Sugar activities are found in

home/dotsugar/default/logs

Hacking

Before submitting changes to the config please run json-format on the json files you modified. The script is available in the shell.