From 9b6034728212f16e251db5f32c7140ef0204d0d4 Mon Sep 17 00:00:00 2001 From: Sunil Mohan Adapa Date: Sun, 31 Aug 2014 17:11:42 +0530 Subject: [PATCH] Update documenation on installating and developing Plinth --- HACKING | 112 +++++++++++++++++++++++++++++++++++++++++++++++ INSTALL | 51 ++++++--------------- doc/hacking.mdwn | 103 +------------------------------------------ 3 files changed, 127 insertions(+), 139 deletions(-) create mode 100644 HACKING mode change 100644 => 120000 doc/hacking.mdwn diff --git a/HACKING b/HACKING new file mode 100644 index 000000000..a014065e3 --- /dev/null +++ b/HACKING @@ -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. diff --git a/INSTALL b/INSTALL index d9c8bd94b..6b131484d 100644 --- a/INSTALL +++ b/INSTALL @@ -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 -containing the program. Run: +2. Install Plinth: - $ 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" -and the default password is "secret". + $ sudo plinth -## Dependencies +4. Access Plinth UI: -* cherrypy - python web engine v3+ - -* 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. + Plinth UI should be accessible at http://localhost:8000 diff --git a/doc/hacking.mdwn b/doc/hacking.mdwn deleted file mode 100644 index a334fc51b..000000000 --- a/doc/hacking.mdwn +++ /dev/null @@ -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. - - - -## 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. diff --git a/doc/hacking.mdwn b/doc/hacking.mdwn new file mode 120000 index 000000000..cc8063b39 --- /dev/null +++ b/doc/hacking.mdwn @@ -0,0 +1 @@ +../HACKING \ No newline at end of file