mirror of
https://github.com/freedombox/FreedomBox.git
synced 2026-01-21 07:55:00 +00:00
Update documenation on installating and developing Plinth
This commit is contained in:
Sunil Mohan Adapa
parent
f243dfa3ab
commit
9b60347282
112
HACKING
Normal file
112
HACKING
Normal 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
51
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
|
||||
|
||||
102
doc/hacking.mdwn
102
doc/hacking.mdwn
@ -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
1
doc/hacking.mdwn
Symbolic link
@ -0,0 +1 @@
|
||||
../HACKING
|
||||
Loading…
x
Reference in New Issue
Block a user