Building Lomiri 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 lomiri
  branches there (trunk, WIP etc)

  $ mkdir ~/lomiri

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

install dependencies and build Lomiri 8
--------------------

$ cd ~/lomiri/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 lomiri-scope-home and lomiri-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 Lomiri 8 on your desktop
===============================

run the Lomiri 8 shell
---------------------
$ cd ~/lomiri/trunk
$ cd builddir

Each component of lomiri 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 Lomiri 8 on devices
==========================

Running lomiri 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.

lomiri 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
Lomiri 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 lomiri

And then run a single test with

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

or run them all with

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

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

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

* Enable/disable Qt scenegraph visualizer on the fly:

  $ qdbus com.lomiri.Shell.Debugging /com/lomiri/Shell/Debugging SetSceneGraphVisualizer <mode>

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

* Toggle slow animations on the fly:

  $ qdbus com.lomiri.Shell.Debugging /com/lomiri/Shell/Debugging SetSlowAnimations <true|false>

* Change logging filter rules on the fly:

  $ qdbus com.lomiri.Shell.Debugging /com/lomiri/Shell/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.
