This document discusses how development looks when using Silver Lining. Not how you develop Silver Lining itself, but how application development with Silver Lining can work.
The first thing you’ll have to do is setup a code layout. An initial layout can be created like this:
silver init myapp-app
This is a virtualenv environment with some added stuff. Here’s what the layout looks like:
app.ini This contains the configuration for your
application. To start out with it is filled with
helpful comments.
bin/ All your scripts for managing your application
(probably none of these should be used when
running your application)
You can also run *Python* scripts from here on
the production server by using "silver run".
pip Use this to install things
easy_install You can also use this to install things; I think
you should use pip, but easy_install should work
fine too
activate Do "source myapp-app/bin/activate" when doing work
in your environment for convenience (this just
places bin/ first on $PATH).
python(2.6) The virtualenv interpreter. So long as you use
this interpreter you'll get access to all the
libraries you've installed for your app.
static/ This is where static files go. Any file found
here will be served directly, not passed to your
application as a request. You can symlink things
into here, or make the entire directory a symlink.
lib/python2.6/ Some virtualenv stuff is put in here; you can
ignore it (mostly).
lib/python2.6/sitecustomize.py
This is the one thing you might pay attention to.
This file sets up the environment. Most
particularly it adds lib/python to the path (more
about that later). You shouldn't edit this.
lib/python2.6/site-packages/
This is often where packages would be installed,
but not for this environment. Only
Setuptools/Distribute and pip are installed here.
lib/python/ This is the directory where everything gets
installed. It starts out empty, it's just for
your application's packages. If you do pip
install foobar, then there will be
lib/python/foobar/
silvercustomize.py
This file doesn't exist to start, but you can add
it to customize the setup, for instance to set
os.environ['DJANGO_SETTINGS_MODULE'].
easy-install.pth
If you have libraries in src/, there will be
pointers to those paths in this file. It's
created on demand, so you won't see it at first.
It initially contains absolute paths (that's how
Setuptools puts the file together), but when
you upload an application those paths will be
made relative.
include/ Created by virtualenv; you can ignore this
directory.
src/ Just a place to check out your own libraries.
After checking out a library run:
pip -e src/new-library
Now that you have a basic environment, either create some code in myapp-app/src/myapp or check out some existing code into that location. If you are using a framework, install it using bin/pip (e.g., myapp-app/bin/pip install Pylons). Install your app itself like bin/pip install -e src/myapp – this causes any prerequisites listed in src/myapp/setup.py to also be installed by pip (otherwise they might get installed with easy_install, which is okay but not as graceful).
You might want to put app.ini into your application (and into version control), and then turn it into a symlink, like:
$ cd myapp-app
$ ln -s src/myapp/silver-app.ini app.ini
You have to define your “runner”, which is the script or config file that starts your application. You need a line like this in app.ini:
runner = src/myapp/silver-runner.py
If you have a .py file then it must define application, a WSGI application. If you have an .ini file then it is treated as a Paste Deploy config file (as used by Pylons, TurboGears, Repoze – though it can be applied to many kinds of applications).
You can also put lib/python/ into version control. You shouldn’t edit things in lib/python/ except to install newer versions of software. But by putting this directory into version control you can be sure you have a consistent and stable set of libraries, and you can easily revert problematic library upgrades.
Lastly you can go the extra mile and move bin/ into lib/python/bin/ and create a symlink back to bin/. This looks like:
$ mv bin lib/python/
$ ln -s lib/python/bin bin
$ cd lib/python
$ echo "syntax: glob
bin/activate*
bin/pip
bin/easy_install*
bin/python*" > .hgignore
$ hg addremove
This puts all the items in bin/ into version control, except those things created automatically by virtualenv (and so automatically created by silver init).
If you put in a file lib/python/silvercustomize.py this module will be loaded everytime you start the environment. This is a great place to do things like:
import os
os.environ['DJANGO_SETTINGS_MODULE'] = 'myapp.settings'
Note also that all the services will get setup everytime you start bin/python or any other service, so you can access the database from tests or scripts or anything else.
A nice way to setup an application is to have a script to build the layout for your application. This helps other developers work on the project. Since Silver Lining only works on Posix-style (and not Windows) systems you can just make a shell script. Here’s an example:
#!/usr/bin/env bash
DIR="$1"
if [ -z "$DIR" ] ; then
echo "Usage: $(basename $0) NEW_DIR"
exit 2
fi
if ! which silver ; then
echo "You must install silver and have it on \$PATH"
exit 3
fi
for COMMAND in hg git svn ; do
if ! which $COMMAND ; then
echo "You must install $COMMAND"
exit 4
fi
done
silver init $DIR
pushd $DIR
# Obviously check it out with whatever is appropriate:
if [ ! -e src/myapp/.hg ] ; then
hg clone http://blahblah/myapp src/myapp
fi
if [ ! -e lib/python/.hg ] ; then
# We have to delete it first because silver init creates
# this directory:
rm -rf lib/python
hg clone http://blahblah/myapp-lib lib/python
fi
if [ ! -L app.ini ] ; then
rm -f app.ini
ln -s src/myapp/silver-app.ini app.ini
fi
if [ ! -L bin ] ; then
mv bin bin.tmp
ln -s lib/python/bin bin
mv bin.tmp/* bin/
rmdir bin.tmp
fi
if [ ! -L static ] ; then
rmdir static
ln -s src/myapp/myapp/static static
fi
Then tell people to grab the script you write directly and run it to get a working rig.