Developing Unity 7


Notice: The information on this page is likely to change soon as we switch our development focus to Unity 8. You can learn about developing Unity 8 on this page.



  • Building Unity

    Get started working on unity by getting the source code and setting up your build environment.

    Click here to get started.

  • Building NUX

    The NUX library provides several core functions for Unity, you will need it to be able to build and run Unity from source.

    Click here to get started.

  • Running Unity

    Unity can be run from your build environment without being installed system-wide. This is the recommended way of testing your changes.

    Click here to started.

  • Code Layout

    Get a quick overview of the Unity source code and where to find the files for the parts you are interested in.

    Click here to learn more.

  • Developing Unity

    Learn about the tools, libraries and guidelines for making your own contributions to the Unity interface.

    Click here to learn more.

Building Unity

These instructions will help you build unity from source. However, there are a few things to consider:

  • It is recommend that you never copy anything you’ve built locally outside your home directory. Doing so is asking for trouble, especially as we’re building the entire desktop shell. If you manage to ruin your system-wide desktop shell you’ll be a very sad programmer!
  • It is assumed that you’re running the precise Ubuntu release.
  • It is also assumed that you want to build unity from trunk (that is, lp:unity).

Getting the source code

If you don’t already have Bazaar installed, install it now:

sudo apt-get install bzr

You will want to make yourself a folder for the unity code. Do something like this:

mkdir -p ~/code/unity
cd ~/code/unity

Let’s grab the code from launchpad:

bzr branch lp:unity trunk
This may take a while.

Installing Build Dependancies

We need to get the build-dependancies for unity. Thankfully, apt-get makes this trivial:

sudo apt-get build-dep unity

Compiling Unity

Use this set of bash functions to make this step significantly easier. To use them, copy the following bash code into a file in your home directory called “.unity_bash_functions” (if you want, you can either create this file in the unity source tree, and manually load it at development time by using source .unity_bash_functions):

function recreate-build-dir()
   rm -r build
   mkdir build
   cd build

function remake-autogen-project()
    ./ --prefix=$HOME/staging --enable-debug
    make clean && make install

function remake-unity()
    make install

function unity-env
 export PATH=~/staging/bin:$PATH
 export XDG_DATA_DIRS=~/.config/compiz-1/gsettings/schemas:~/staging/share:/usr/share:/usr/local/share
 export LD_LIBRARY_PATH=~/staging/lib:${LD_LIBRARY_PATH}
 export LD_RUN_PATH=~/staging/lib:${LD_RUN_PATH}
 export PKG_CONFIG_PATH=~/staging/lib/pkgconfig:${PKG_CONFIG_PATH}
 export PYTHONPATH=~/staging/lib/python2.7/site-packages:$PYTHONPATH
 export GI_TYPELIB_PATH=~/staging/lib/girepository-1.0:$GI_TYPELIB_PATH
 export XDG_CONFIG_DIRS=~/staging/etc:$XDG_CONFIG_DIRS

Now run this in a terminal:

echo ". ~/.unity_bash_functions" >> ~/.bashrc

This ensures that the next time you open a bash shell the functions listed above will be available to you. To avoid having to close and re-open a terminal, we can read them manually just this once:

. ~/.unity_bash_functions

If you prefer instead to set your environment path manually, you can use tools such as (with proper aliases)
You should now be able to run:

from the trunk/ directory we created earlier. Indeed you don’t need to remove the build directory every time, so after the first time, you can just run make install -C build when you modify something.
Also, if you want to save some time, not re-compiling tests at every rebuild, you can just use:
make -C build/UnityCore/ install && make -C build/plugins/unityshell/ install
That’s it – you’re building unity!

Building NUX

Chances are, while trying to build unity, you found that it needed a newer version of one of the several supporting projects than you had installed. At the time of writing, you can’t compile unity without first building nux from sources first. Thankfully, that’s pretty easy with the use of the functions you now have set up.

Get the source code:

mkdir -p ~/code/nux
cd ~/code/nux
bzr branch lp:nux trunk
cd trunk

Installing Build Dependancies

sudo apt-get build-dep nux

Unfortunately there are a fewpackages missing, so you’ll want to install them as well:

sudo apt-get install gnome-common libibus-1.0-dev libgtest-dev google-mock libxtst-dev

Compiling NUX

That’s it! You can then go back and build unity – hopefully this time with better success.

Build Notes

You may have noticed that the remake-* scripts do a complete rebuild every time. If you’d prefer to just build the files that have changed since last time, change to the trunk/build/ directory, and run:

make install


Running Unity

If you’d like to run the version of unity you’ve built, rather than the system-wide version, open a terminal and run the following commands:

unity --replace &

The first line patches several environment variables such that unity will subsequently be launched from your local staging directory. These environment variables will remain changed until you close the terminal, so you need only run unity-env once.

Sourcecode Layout

The Unity sourcecode is divided between common, reusable components and the Compiz plugins that display them. Here is an overview of where the different source files reside in the branch.

Top-level directories

Code for the Unity Dash
Code for the Heads-Up Display (HUD)
Code for the Unity Launcher
Code for the Unity (top) Panel
Compiz plugins that make up the Unity Shell (See below)
DBus services for the Unity panel
Collection of utility classes shared by multiple Unity components
Stand-alone mode for Unity testing (without compiz)
Base set of classes/resources for integrating with system services (indicators, lenses, etc)

Compiz Plugins

The primary compiz plugin for the Unity Shell, provides the Launcher, Dash, switcher and panel
Provides the overlay for touch-friendly window moving and resizing
(Inactive) New style modal dialogs

Developing Unity

Now that you have all of the source code for Unity compiled and running, you are ready to start making your modifications and enhancements.

Using NUX

Unity uses the NUX library to provide a consistent UX and UI across platforms and form-factors. If you are making changes to the way Unity looks, chances are you’ll be using NUX.


Writing Tests

Any changes you make to Unity should include the appropriate test cases. If you are fixing a bug, first write a test that triggers it. If you are adding a new feature, write as many test cases as needed to cover all possible use cases for that feature.

Unity uses the Google Tests  framework for unit tests, while the Autopilot UI testing framework is used for automated testing (integration tests).
In general it’s preferable to write unit tests, as they are more reliable and right to the point, but in some situations there’s no alternative to Autopilot testing.


Coding Style Guide

This document describes the coding style recommended for the Unity project in several languages. It is a good idea to familiarize yourself with these guidelines before making any major changes, as they will make it easier for your changes to be accepted.


Submitting your code

Once you have changes made, you’re going to want to submit them for inclusion in Unity itself. Do do that, you’ll need to push your code to a new branch in Launchpad and create a merge proposal for the Unity developers.

First, use bzr to push your code to Launchpad:

bzr push lp:~{$username}/unity/{$branch_name}

Where {$username} is your Launchpad nickname, and {$branchname} is a unique name for your code changes.

Then, open your branch’s page on Launchpad (select it from this list), and chose the “Propose for merging” link. Write a description of the changes you have made, and submit it for review. Then, keep an eye on the merge proposal, and respond to any questions or feedback from the Unity developers.