nik/FreedomBox
1
0
Fork 0
mirror of https://github.com/freedombox/FreedomBox.git synced 2026-09-19 04:59:01 +00:00
Code Issues Packages Projects Releases Wiki Activity

Update documenation on installating and developing Plinth

Browse Source
This commit is contained in:
Sunil Mohan Adapa 2014-08-31 17:11:42 +05:30
parent f243dfa3ab
commit 9b60347282
3 changed files with 127 additions and 139 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

112
HACKING Normal file
View File

@ -0,0 +1,112 @@
# 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.

51
INSTALL
View File

@ -1,47 +1,24 @@
# Quick Start # Installing Plinth
## Installing Plinth 1. Install the dependencies:
Install the dependencies: On a Debian based system, run:
apt-get install pandoc psmisc python2.7 python-cherrypy3 python-django python-bootstrapform libjs-twitter-bootstrap sudo $ sudo apt-get install libjs-jquery libjs-modernizer \
libjs-twitter-bootstrap make pandoc python2.7 python-cherrypy3 \
python-django python-bootstrapform python-withsqlite
Unzip and untar the source into a directory. Change to the directory 2. Install Plinth:
containing the program. Run:
$ make Unzip the source into a directory. Change to the directory containing the
program and run:
To start Plinth, run: $ sudo python setup.py install
$ ./start.sh 3. Run Plinth:
and point your web browser at `localhost:8000`. The default username is "admin" $ sudo plinth
and the default password is "secret".
## Dependencies 4. Access Plinth UI:
* cherrypy - python web engine v3+ Plinth UI should be accessible at http://localhost:8000
* python - tested with version 2.6.6
* *GNU Make* is used to build the templates and such.
* *libjs-twitter-bootstrap* - A responsive, mobile first front-end framework
* *python-bootstrapform* - Render django forms for Twitter Bootstrap
The documentation has some dependencies too.
* *Markdown* is used to format and style docs.
* *Pandoc* converts the markdown to different formats.
* *PDFLatex* generates pdf versions of the documentation.
* *GNU Make* processes /doc/Makefile.
## Building the Documentation
Documentation has been collected into a pdf that can be built using
`make doc`. It also gets built into smaller files and other formats,
including one suitable for install as a man page.

102
doc/hacking.mdwn
View File

@ -1,102 +0,0 @@
# Hacking
This codebase could really use a testing framework.
If you are interested in helping out, writing tests is a great place
to start-- you don't need to know much about the code or python to
write useful tests.
In addition to a testing framework, the code is in need of some
general cleanup. I've been inconsistent in capitalization conventions
as well as in my use of underscores.
The plugin interface could use some attention as well. Right now,
it's a a bit of a free-for-all until I see how the plugins actually
code up. Channeling all that into a few plugin interface grooves
would be a help.
If you're feeling more ambitious than that, the best way to improve
Plinth is to add modules. More functionality, especially in the
router section, could convert the Freedom Box from a good idea to a
must-have appliance.
Beyond that, we need to train some expert eyes on the interaction
between Freedom Boxes. Transparent, zero-config box-to-box backup is
possible. We just need to build an auth and dns layer. There are
lots of theories on how to do this well. The first theory reduced to
practice wins!
There is a list of TODO items below. Some of them are discrete pieces
that can be tackled without diving too deep into the code.
## Repository
Plinth is available from github at
`git://github.com/jvasile/plinth.git`. The [project page on
github](https://github.com/jvasile/plinth) is at
`https://github.com/jvasile/plinth`.
## Bugs
There are lots of bugs. We don't have a spec or tests, so a bug is
really just any unexpected behavior. I am not easily surprised, but
there are still lots of bugs.
There's an [issue tracker](https://github.com/jvasile/Plinth/issues).
Please add things and consult it for things to tackle.
<a name="hacking_code_practices" />
## Coding Practices
I try to stick to [PEP 8](http://www.python.org/dev/peps/pep-0008/)
recommendations. That's not to say I don't deviate, just that
deviations are usually bugs that should be fixed.
### 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:
cfg.log.error(_("Couldn't import %s: %s") % (path, e))
### Variables and Data Stores
Plinth needs to keep information for short and long term
future use, and it can't just store all of that on the stack.
Global config information can be put in the `cfg` module namespace.
Keep it thread and session safe, though, or you'll get undefined
behavior as soon as multiple simultaneous users enter the picture.
Cherrpy has support for session variables. Use those for short term
user-specific data.
For long term storage, the Plinth needs a back end
storage solution. Databases are a bit opaque and can be hard for
third party software or shell users to manipulate. For now, I've
decided that persistent data should be placed in dicts and stored in
json format. We'll need a file locking solution too.
The `user_store.py` module implements the `UserStoreModule` interface
specified in `plugin_mount.py`. Any new system that respects that
interface can be used. The existing `user_store.py` holds entire user
files in memory and caches user files as it goes. This has two
downsides: first, if you have lots of users and store big things in
the user dict, you'll run out of memory. Second, it's not thread
safe. Maybe a database is a good idea after all.
We do not yet have a means of storing module data for long terms. My
current thinking is that modules can store data in their own
directories. That makes removal easy.
## Todo
Plinth has a number of open todo items. And there are items in the
[issue tracker](https://github.com/jvasile/Plinth/issues) that need
tackling. Please help!
* Implement the functions in the submenus of router.py
* Unify our logging and cherrypy's.

1
doc/hacking.mdwn Symbolic link
View File

@ -0,0 +1 @@
../HACKING