CODING

Building Unity 8
================

Only Ubuntu 14.04 (trusty) is supported as a developement environment.

download source
---------------
- create a parent folder to not pollute your setup. so that you can have different unity
  branches there (trunk, WIP etc)

  $ mkdir ~/unity8

- fetch Unity 8 source
  $ sudo apt-get install bzr
  $ bzr branch lp:unity8 ~/unity8/trunk
  $ cd ~/unity8/trunk

install dependencies and build Unity 8
--------------------

$ cd ~/unity8/trunk
$ ./build.sh

  If its your first time, this will install the required dependencies to build and
  build it.

  You might want to also install unity-scope-home and unity-scope-click which
  are technically "recommends", not strict dependencies

You may also rebuild with the -c for clean, which just deletes the build
directory.


Running Unity 8 on your desktop
===============================

run the Unity 8 shell
---------------------
$ cd ~/unity8/trunk
$ cd builddir

Each component of unity8 can be ran independently for development and testing
For example:
$ make tryShell
$ make tryLauncher
$ make tryLockscreen

Check out the tests/qmltests/ directory for a list of things that can be ran.

Notes
-----
- to navigate, utilize the mouse left button as you would your finger
- a three point drag (for side stage operations) can be performed by using
  the Shift+Control+Alt (all together) keyboard modifiers while using the mouse.
- to get the translations work, currently you have to do make install to
  put the *.mo files into correct structure. We'll look for a better solution
  later.
  $ cd builddir; make install
- if you wish to populate contacts
  $ sudo apt-get install gir1.2-ebook-1.2
  $ manage-address-book.py create
  this will:
    - Create an EDS address book
    - Populate the address book with sample data


Running Unity 8 on devices
==========================

Running unity8 on a device should be done using crossbuilder.
Go to 
* https://launchpad.net/crossbuilder and
* https://wiki.ubuntu.com/Touch/Crossbuilder 
for more details on crossbuilder.

unity8 will automatically restart on the phone once deployment
has finished due to post-build-steps set up in this repository.

Coding guidelines
=================
The work-in-progress coding guidelines are available under:
https://launchpad.net/canonical-client-development-guidelines


Development Environment
=======================
QtCreator (available via the Software Center) is the best IDE to hack on
Unity 8.

If using VIM, make sure you install some syntax highlighting for QML, like
https://github.com/peterhoeg/vim-qml

Running tests
=============

Tests are run from the build directory (which will be ./builddir if you used
the ./build.sh script).

To run the tests that do not require any graphical capability and therefore
are pretty fast run:

$ make test

or, alternatively:

$ ctest

To run all graphical tests, which can take a couple of minutes:

$ make uitests

To run the tests for a single component/class:

$ make testComponentName

So, for the DragHandle component that would be:

$ make testDragHandle

To run the tests for a single component/class under gdb (so you can catch SEGFAULTS)

$ make gdbtestComponentName

To run a single test function of a single component/class:

$ make testComponentName FUNCTION="TestCaseName::functionName"

To run a test application that allow you to manually test or to simply try out
a given component:

$ make tryComponentName

So to try out, for instance, the DragHandle component, you would do:

$ make tryDragHandle

NB: Manual test or interation doesn't make sense for all components or classes,
particularly the non-graphical ones. In such cases no "tryFoo" make target is
provided.

Running autopilot tests
=======================

Autopilot tests are run from the build directory (which will be ./builddir if you used
the ./build.sh script).

$ make autopilot

If you want you can also run tests individually, for that you need to install first,
otherwise the tests will run on the system-installed version

$ make install

To see the list of existing autopilot tests you can do

$ PYTHONPATH=../tests/autopilot autopilot3 list unity8

And then run a single test with

$ PYTHONPATH=../tests/autopilot autopilot3 run unity8.some.very.long.test.name

or run them all with

$ PYTHONPATH=../tests/autopilot autopilot3 run unity8

Debugging techniques
====================

Unity8 heavily uses Qt and with that Qt debugging techniques mostly apply in the
same fashion. There are, however, some additional unity8-specific notes:

* Enable/disable Qt scenegraph visualizer on the fly:

  $ qdbus com.canonical.Unity8.Debugging /com/canonical/Unity8/Debugging SetSceneGraphVisualizer <mode>

  This is equivalent to exporting QSG_VISUALIZE=<mode> before running unity8, except it does it on the
  fly.

* Toggle slow animations on the fly:

  $ qdbus com.canonical.Unity8.Debugging /com/canonical/Unity8/Debugging SetSlowAnimations <true|false>

* Change logging filter rules on the fly:

  $ qdbus com.canonical.Unity8.Debugging /com/canonical/Unity8/Debugging SetLoggingFilterRules <filter>

  This is equivalent to exporting QT_LOGGING_RULES or defining them in QT_LOGGING_CONF, except it does
  it on the fly.