~mzanetti/unity8/async-dashcommunicator

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

--------------------

If its your first time, install build dependencies

$ cd ~/unity8/trunk

$ ./build.sh --setup

  this will:

  - install the required dependencies to build, as well as run on the desktop

  - it should also install unity-scope-home and unity-lens-application which 

    are technically "recommends", not strict dependencies

build Unity 8

-------------

$ cd ~/unity8/trunk

$ ./build.sh

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

$ ./run.sh

Options can be passed to test the lock screen

$ ./run.sh -p OR -k

-p is for pin lock, for which the default prompt answer is "1234"

-k is for keylock passphrase, for which the default prompt answer is "password"

Notes

-----

- to navigate, utilize the mouse left button as you would your finger

- 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

==========================

- Ubuntu Touch builds are currently only available in 14.04 flavour

- supported hardware should match one of those listed here

  https://wiki.ubuntu.com/Touch/Devices#Running_fine

- follow the Ubuntu Touch install instructions for your chosen device

  https://wiki.ubuntu.com/Touch/Install

- make sure your device is connected to a network

- also make sure you have your SSH key in ~/.ssh/id_rsa.pub (or install one

  on the device yourself)

$ cd ~/unity/trunk

$ ./run_on_device.sh --setup

  this will:

  - install your public SSH key on the device

  - install the needed dependencies

$ ./run_on_device.sh

  this will:

  - rsync the code to the device

  - build on the device

  - replace the running shell

Options can be passed to test the lock screen

$ ./run_on_device.sh -p OR -k

-p is for pin lock, for which the default prompt answer is "1234"

-k is for keylock passphrase, for which the default prompt answer is "password"

Notes

-----

- using adb over TCP has some advantages, Google will be of help here

  - NOTE: this is not yet available for flipped images

  - TL;DR: `adb tcpip 5555; adb connect $your_device_ip`

  - you can persist the above via `adb shell setprop persist.adb.tcp.port 5555`

  - it's unsafe - anyone can connect to your device

  - with TCP the Nexus 10 doesn't drop the adb connection when locking

    the screen

- exporting ANDROID_SERIAL=$your_device_serial or 

  ANDROID_SERIAL=$your_device_ip:5555 will make adb not complain about 

  multiple devices

- you can export TARGET_IP=$your_device_ip TARGET_SSH_PORT=22 for run_on_device.sh

  to not use adb forwarding - useful if you use multiple devices

- using Ninja (package ninja-build - run_on_device.sh -s installs this now)

  will improve build times (especially in the nothing-to-build case)

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 qmluitests

To run the tests for a single component/class:

$ make testComponentName

So, for the DragHandle component that would be:

$ make testDragHandle

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 autopilot list unity8

And then run a single test with

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

or run them all with

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