# Hacking

## Installing for Development

1. Instead of running "setup.py install" after every source modification, run
   the following command:

    $ sudo python setup.py develop

    This will install the python package in a special development mode.  Run it
    normally.  Any updates to the code (and core pakcage data files) do not
    require re-installation after every modification.

    CherryPy web server also monitors changes to the source files and reloads
    the server as soon as a file is modified.  Hence it is usually sufficient
    to modify the source and refresh the browser page to see the changes.

2. Plinth also support running without installing (as much as possible).
   Simply run it as:

    $ sudo python -m plinth

    In this mode, Plinth runs in working directory without need for
    installation.  It uses a different config file (plinth.conf in working
    directory) instead of the regular config file (/etc/plinth/plinth.conf). It
    creates all that data and runtime files in data/var/*. To make Plinth
    pickup the config file in working directory, simply delete
    /etc/plinth/plinth.config.

## Running Tests

1. Run tests:

    $ python setup.py test

## Testing Inside a Virtual Machine

1. Checkout source on the host.

2. Share the source folder and mount it on virtual machine.  This could be done
   over NFS, SSH-fs or 'Shared Folders' feature on VirtualBox.

3. Run 'setup.py develop' or 'setup.py install' as described above on guest
   machine.

4. Access the guest machine's Plinth web UI from host after setting bridging or
   NATing for guest virtual machine.

## Building the Documentation Separately

Documentation has been collected into a PDF. It also gets built into smaller
files and other formats, including one suitable for install as a man page.

1. To build the documentation separately, run:

    $ make -C doc

## Repository

Plinth is available from [GitHub](https://github.com/freedombox/plinth).

## Bugs & TODO

You can report bugs on Plinth's
[issue tracker](https://github.com/freedombox/Plinth/issues).

Feel free to pickup a task by announcing it on the issue.  Once you are done,
request a merge. For information on placing a merge request, consult GitHub
documentation.

## Coding Practices

Plinth confirms to [PEP 8](http://www.python.org/dev/peps/pep-0008/) Python
coding standard. You should check your code with *pep8* and *pylint* tools
before placing a merge request.

## Internationalization

Every module should `from gettext import gettext as _` and wrap
displayed strings with _().  We don't have the language stuff in place
yet (we have no translation files), but we need to put the
infrastructure in place for it from the start.  Use it like this:

    log.error(_("Couldn't import %s: %s"), path, e)

## Dependencies

* *Bootstrap Form* - Render Django forms for Twitter Bootstrap

* *CherryPy3* - WSGI web server since Django does not have proper web server

* *Django* - Web application framework for Plinth

* *JQuery* - Javascript framework used for convenience

* *Modernizer* - HTML5 and CSS3 feature detection

* *Python* - tested with version 2.7

* *Twitter Bootstrap* - A responsive, mobile first front-end framework

* *Withsqlite* - Python library that stores dictionaries in sqlite3

The documentation has the following dependencies:

* *Markdown* - format and style docs

* *Pandoc* - Convert markdown to various formats

* *PDFLatex* - Generate PDF versions of the documentation

* *GNU Make* - Process doc/Makefile.
