mirror of
https://github.com/freedombox/FreedomBox.git
synced 2026-01-21 07:55:00 +00:00
144 lines
4.8 KiB
Plaintext
144 lines
4.8 KiB
Plaintext
# Hacking
|
|
|
|
## Installing for Development
|
|
|
|
1. Instead of running "setup.py install" after every source modification, run
|
|
the following command:
|
|
|
|
$ sudo python3 setup.py develop
|
|
|
|
This will install the python package in a special development mode. Run it
|
|
normally. Any updates to the code (and core package 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' manually.
|
|
|
|
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:
|
|
|
|
$ python3 setup.py test
|
|
|
|
## Running the Test Coverage Analysis
|
|
|
|
1. Run the coverage tool:
|
|
|
|
$ python3 setup.py test_coverage
|
|
|
|
Invoking this command generates a binary-format '.coverage' data file in
|
|
the top-level project directory which is recreated with each run, and
|
|
writes a set of HTML and other supporting files which comprise the
|
|
browsable coverage report to the 'plinth/tests/coverage/report' directory.
|
|
Index.html presents the coverage summary, broken down by module. Data
|
|
columns can be sorted by clicking on the column header or by using mnemonic
|
|
hot-keys specified in the keyboard widget in the upper-right corner of the
|
|
page. Clicking on the name of a particular source file opens a page that
|
|
displays the contents of that file, with color-coding in the left margin to
|
|
indicate which statements or branches were executed via the tests (green)
|
|
and which statements or branches were not executed (red).
|
|
|
|
## 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
|
|
|
|
* *Augeas* - Round trip configuration editing utilities
|
|
|
|
* *Bootstrap Form* - Render Django forms for Twitter Bootstrap
|
|
|
|
* *CherryPy3* - WSGI web server since Django does not have proper web server
|
|
|
|
* *Coverage* - Test coverage measurement and reporting tool
|
|
|
|
* *Django* - Web application framework for Plinth
|
|
|
|
* *Django Stronghold* - Middleware to make all views default login required
|
|
|
|
* *JQuery* - Javascript framework used for convenience
|
|
|
|
* *LDAPscripts* - Scripts to manage LDAP users and groups
|
|
|
|
* *Modernizer* - HTML5 and CSS3 feature detection
|
|
|
|
* *Python3* - Requires minimum 3.3, tested with version 3.4.1
|
|
|
|
* *Twitter Bootstrap* - A responsive, mobile first front-end framework
|
|
|
|
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.
|