README.developer

                            Developer Information
###############################################################################

This file provides some information for developers looking to submit patches to
OLA. The first section contains some general notes, and the latter
sections address particular languages.

Also take a look at README which includes some relevant information for
developers too.

General
===============================================================================

Code Reviews
------------

To have patches reviewed please push your changes to GitHub and create a Pull
Request from within your fork.

If you're using Google Code please enable comments on the repo. Under
Administer -> Source check:
  Enable code reviews
  Allow non-members to review code

Licensing
---------

Think carefully about the license for each file. Code to be used by clients
(./ola , ./python) should be under the LGPL, so that it may be used in
commercial projects.

Plugins and code used solely in olad should be under the GPL.

scripts/enforce_licence.py will look for a LICENCE file in each directory, and
ensure that all source files in the directory ( & subdirectories) start with
the LICENCE. You can pass --fix to automatically add the licence.

Unittests
---------

Unittests are *highly* encouraged. At the very least please make sure any
changes don't break the tests.

The tests are performed with `make check` in the root ola directory. The same
command can be run within a sub directory to only run a particular set of
tests (although you may experience issues with this method, running from the
root ola directory is guaranteed to work).


C++
===============================================================================

The bulk of OLA code is written in C++. This includes the daemon olad, and
plugins.

http://www.opendmx.net/index.php/OLA_developer_info describes many of the
underlying classes used.

Endian Issues
-------------

Be aware that OLA runs on big endian systems. When dealing with wire formats
always use the functions in include/ola/network/NetworkUtils.h to convert or
use the BigEndianOutputStream to manage this automatically for you.

Non x86 platforms
-----------------

OLA also runs on more than just x86. Some platforms like ARM can't de-reference
pointers which aren't aligned.

For example:

struct f {
  uint8_t value1;
  uint16_t value2;
} __attribute__((packed));

struct f foo = {1, 2};
uint16_t *ptr = &foo.value2;
// Bug! Will not be true on all platforms.
if (*ptr == 2)

http://www.aleph1.co.uk/chapter-10-arm-structured-alignment-faq has a good
explanation.


Style / Coding Standards
------------------------

We use the Google C++ Style Guide:
  http://google-styleguide.googlecode.com/svn/trunk/cppguide.xml

Please run the cpplint.py script on all files before requesting a review.

cpplint.py can be downloaded here:
  http://google-styleguide.googlecode.com/svn/trunk/cpplint/cpplint.py

Run it with:
   --filter=-legal/copyright,-readability/streams,-runtime/arrays

Doxygen
-------

The code is documented using Doxygen. There is an automatically generated
version available from:
http://docs.openlighting.org/doc/

If you want to build it yourself, install Doxygen, run ./configure in the ola
root directory, then run make doxygen-doc. The files will be generated into 
html/

Race Conditions
---------------

If possible, code should be tested with slower machines (embedded platforms,
virtual machines etc.). This has discovered race conditions in the past.

Valgrind
--------

All code must be tested with valgrind to ensure it doesn't leak memory.

Coverage (gcov)
---------------

To enable the coverage tools, you need lcov and gcov installed. To enable run
./configure --enable-gcov and then build as normal.

To generate the HTML pages run:

  mkdir /tmp/lcov
  tmpdir=`mktemp -d /tmp/lcov.XXXXXX`
  coverage="${tmpdir}/coverage.info"
  lcov --capture --directory ./ --output-file $coverage
  genhtml $coverage --output-directory /tmp/lcov


Java
===============================================================================

An experimental Java API is provided.

Style / Coding Standards
------------------------

Please follow the Sun Java style guide.


Javascript
===============================================================================

Javascript is used for the olad web UI. Instructions for building the
javascript can be found in javascript/README.

Closure Compiler
----------------

The closure compiler catches many errors. The javascript code should build
cleanly.

Style / Coding Standards
------------------------

We use the Google Javascript style guide:
  http://google-styleguide.googlecode.com/svn/trunk/javascriptguide.xml

A javascript linter can be downloaded from:
  http://code.google.com/closure/utilities/docs/linter_howto.html

Please make sure all Javascript code is lint clean.


Python
===============================================================================

Python is used for tools like the RDM responder tests and the device model
collector. To enable these a OLA Python API is provided.

Style / Coding Standards
------------------------

We use the Google Python style guide:
  http://google-styleguide.googlecode.com/svn/trunk/pyguide.html

However we deviate from the standard and use 2 space indents, so it's
consistent with the C++ code.

Build System
===============================================================================

Autotools is a complex beast. Even after reading two books and a using it for a
decade I still feel like I hardly understand it.

Useful tips
-----------

* Run `make distcheck` to ensure you haven't broken anything.
* Use $(srcdir), $(top_srcdir) to reference files where required. This is to
  support VPATH builds:
  http://www.gnu.org/software/automake/manual/html_node/VPATH-Builds.html
* Prefer manualy dependencies over BUILT_SOURCES where possible, see
  http://www.gnu.org/software/automake/manual/html_node/Built-Sources-Example.html
  However this doesn't work in some cases (libraries?) because it overrides the
  automake generated rules.