How to setup your environment and install Kansha from GitHub for development.
Beside the System dependencies, you need to have git installed. You should already be familiar with git and GitHub. If that’s not the case, check https://help.github.com/articles/good-resources-for-learning-git-and-github/.
The following instructions apply to UNIX-like systems, like Linux or MacOS X.
Install Stackless Python and Virtualenv¶
Nagare, the framework used by Kansha, needs Stackless Python (version 2.7.X) to run.
Unfortunatly, none of the major Linux distributions offer packages for Stackless, so you have to build it from sources.
In order to install it via the sources, first ensure you have the prerequisite system dependencies, then complete the following commands:
$ mkdir <STACKLESS_DIR> $ wget http://www.stackless.com/binaries/stackless-278-export.tar.bz2 $ tar xf stackless-278-export.tar.bz2 $ ./configure --prefix=<STACKLESS_DIR> && make -j3 all && make install
More details in its documentation.
Then, we recommend using a virtual environment for deploying Kansha. To install virtualenv within your fresh Stackless Python, you can execute the following commands:
$ wget https://bitbucket.org/pypa/setuptools/raw/bootstrap/ez_setup.py -O - | <STACKLESS_DIR>/bin/python $ <STACKLESS_DIR>/bin/easy_install virtualenv
Install Kansha for development¶
First, create a stackless virtual environment so your development environment remains isolated:
$ <STACKLESS_DIR>/bin/virtualenv <VENV_DIR>
<VENV_DIR> is whereever you want your virtual environment be created. Note that we won’t be working in that directory directly, so it can be a hidden one.
Fork the Kansha project on GitHub.
Clone your project locally. Now you have a
kansha folder (<KANSHA_DIR> in the following). That’s where the actual development will take place.
Activate the virtual environment you created above:
$ source <VENV_DIR>/bin/activate
Then install Kansha in development mode:
$ cd <KANSHA_DIR> $ python setup.py develop
The last command installs kansha in the virtual environment in place.
That is, any modification done to the files in
kansha/kansha will be available immediatly, without re-installing.
Finally, install all the optional dependencies of Kansha:
$ pip install kansha[test] $ pip install kansha[htmldocs] $ pip install kansha[ldap] $ pip install kansha[postgres] $ pip install kansha[mysql] $ pip install kansha[elastic]
conf directory, copy
kansha.local.cfg and edit the latter to fit your system.
For developing, let’s use the built-in web server, database and search engine with the custom configuration.
Place yourself at the root of the project (<KANSHA_DIR>). The virtual environment is still activated in your shell (look at the prompt); if not, activate it.
First, initialize the database (first run only):
$ nagare-admin create-db conf/kansha.local.cfg $ kansha-admin alembic-stamp head conf/kansha.local.cfg
If you later need to migrate your database after a schema change in the model:
$ kansha-admin alembic-upgrade head conf/kansha.local.cfg
Build the search indexes (can be safely repeated anytime, only needed at firt run actually):
$ kansha-admin create-index conf/kansha.local.cfg
$ nagare-admin serve conf/kansha.local.cfg --reload
Now kansha is listening. Just point your browser to http://localhost:8080 and check.
--reload switch is handy for development, as the server then reloads kansha whenever a python file is modified.
Later, each time you’ll want to run Kansha in development mode, remember these steps:
$ cd <KANSHA_DIR> $ source <VENV_DIR>/bin/activate $ nagare-admin serve conf/kansha.local.cfg --reload
Now that your environment is ready and kansha is running is development mode, let’s hack!
- translate (if appliable);
- write unit tests for internal funtionality and API (for the latter, write the tests first, then develop);
- repeat from 1. until your tests (automatic and/or manual) pass;
- commit with appropriate message;
- go to 1 until your work is done;
- submit a pull request on github.
Specific recommendations and workflows are described in theses sections:
It’s highly recommended that you subscribe to the mailing list: http://groups.google.com/group/kansha-users