mirror of
https://github.com/freedombox/FreedomBox.git
synced 2026-01-21 07:55:00 +00:00
120 lines
3.7 KiB
Plaintext
120 lines
3.7 KiB
Plaintext
# 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 ./run --no-daemon --debug
|
|
|
|
In this mode, Plinth runs in working directory without need for
|
|
installation. It uses the plinth.conf config file in the working
|
|
directory if no regular config file (/etc/plinth/plinth.conf) is found.
|
|
It creates all that data and runtime files in data/var/*.
|
|
|
|
*Note:* This mode is supported only in a limited manner. The following are
|
|
the unknown issues with it:
|
|
|
|
1. Help pages are also not built. Run 'make -C doc' manaully.
|
|
|
|
2. Actions do not work when running as normal user without 'sudo' prefix.
|
|
You need to add 'actions' directory to be allowed for 'sudo' commands.
|
|
See data/etc/sudoers.d/plinth for a hint.
|
|
|
|
## 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.
|