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 “.bash_functions”:

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

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

function remake-unity()
{
    recreate-build-dir
    cmake .. -DCMAKE_BUILD_TYPE=Debug -DCOMPIZ_PLUGIN_INSTALL_TYPE=local -DCMAKE_INSTALL_PREFIX=$HOME/staging/ -DGSETTINGS_LOCALINSTALL=ON
    make  && 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
}


Now run this in a terminal:

echo ". ~/.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:

. ~/.bash_functions

You should now be able to run:

remake-unity
from the trunk/ directory we created earlier. 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

remake-autogen-project
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 && 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-env
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

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

Compiz Plugins

./plugins/unityshell
The primary compiz plugin for the Unity Shell, provides the Launcher, Dash, switcher and panel
./plugins/unity-mt-grab-handles
Provides the overlay for touch-friendly window moving and resizing
./plugins/unitydialog
(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

Unity uses the Autopilot UI testing framework for automated testing. 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.

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.