/docs/devpatterns.txt

  1Developing Using Silver Lining
  2==============================
  3
  4This document discusses how development looks when using Silver
  5Lining.  Not `how you develop Silver Lining itself
  6<devel-silverlining.html>`_, but how application development with
  7Silver Lining can work.
  8
  9Creating a Project/Layout
 10-------------------------
 11
 12The first thing you'll have to do is setup a code layout.  An initial
 13layout can be created like this::
 14
 15    silver init myapp-app
 16
 17This is a `virtualenv <http://virtualenv.openplans.org>`_ environment
 18with some added stuff.  Here's what the layout looks like::
 19
 20    app.ini          This contains the configuration for your
 21                     application.  To start out with it is filled with
 22                     helpful comments.
 23
 24    bin/             All your scripts for managing your application
 25                     (probably none of these should be used when
 26                     running your application)
 27
 28                     You can also run *Python* scripts from here on
 29                     the production server by using "silver run".
 30
 31      pip            Use this to install things
 32
 33      easy_install   You can also use this to install things; I think 
 34                     you should use pip, but easy_install should work 
 35                     fine too
 36
 37      activate       Do "source myapp-app/bin/activate" when doing work
 38                     in your environment for convenience (this just
 39                     places bin/ first on $PATH).
 40
 41      python(2.6)    The virtualenv interpreter.  So long as you use
 42                     this interpreter you'll get access to all the
 43                     libraries you've installed for your app.
 44
 45    static/          This is where static files go.  Any file found
 46                     here will be served directly, not passed to your
 47                     application as a request.  You can symlink things 
 48                     into here, or make the entire directory a symlink.
 49
 50    lib/python2.6/   Some virtualenv stuff is put in here; you can
 51                     ignore it (mostly).
 52
 53    lib/python2.6/sitecustomize.py
 54                     This is the one thing you might pay attention to.
 55                     This file sets up the environment.  Most
 56                     particularly it adds lib/python to the path (more
 57                     about that later).  You shouldn't edit this.
 58
 59    lib/python2.6/site-packages/
 60                     This is often where packages would be installed,
 61                     but not for this environment.  Only
 62                     Setuptools/Distribute and pip are installed here.
 63
 64    lib/python/      This is the directory where everything gets
 65                     installed.  It starts out empty, it's just for
 66                     your application's packages.  If you do pip
 67                     install foobar, then there will be
 68                     lib/python/foobar/
 69
 70      silvercustomize.py
 71                     This file doesn't exist to start, but you can add
 72                     it to customize the setup, for instance to set
 73                     os.environ['DJANGO_SETTINGS_MODULE'].
 74
 75      easy-install.pth
 76                     If you have libraries in src/, there will be
 77                     pointers to those paths in this file.  It's
 78                     created on demand, so you won't see it at first.
 79                     It initially contains absolute paths (that's how
 80                     Setuptools puts the file together), but when
 81                     you upload an application those paths will be
 82                     made relative.
 83
 84    include/         Created by virtualenv; you can ignore this
 85                     directory.
 86
 87    src/             Just a place to check out your own libraries.
 88                     After checking out a library run:
 89                       pip -e src/new-library
 90
 91Next Steps
 92----------
 93
 94Now that you have a basic environment, either create some code in
 95``myapp-app/src/myapp`` or check out some existing code into that
 96location.  If you are using a framework, install it using ``bin/pip``
 97(e.g., ``myapp-app/bin/pip install Pylons``).  Install your app itself
 98like ``bin/pip install -e src/myapp`` -- this causes any prerequisites
 99listed in ``src/myapp/setup.py`` to also be installed by pip
100(otherwise they might get installed with easy_install, which is *okay*
101but not as graceful).
102
103You might want to put ``app.ini`` into your application (and into
104version control), and then turn it into a symlink, like::
105
106    $ cd myapp-app
107    $ ln -s src/myapp/silver-app.ini app.ini
108
109You have to define your "runner", which is the script or config file
110that starts your application.  You need a line like this in
111``app.ini``::
112
113    runner = src/myapp/silver-runner.py
114
115If you have a ``.py`` file then it must define ``application``, a WSGI
116application.  If you have an ``.ini`` file then it is treated as a
117Paste Deploy config file (as used by Pylons, TurboGears, Repoze --
118though it can be applied to many kinds of applications).
119
120You can also put ``lib/python/`` into version control.  You shouldn't
121*edit* things in ``lib/python/`` except to install newer versions of
122software.  But by putting this directory into version control you can
123be sure you have a consistent and stable set of libraries, and you can
124easily revert problematic library upgrades.
125
126Lastly you can go the extra mile and move ``bin/`` into
127``lib/python/bin/`` and create a symlink back to ``bin/``.  This looks
128like::
129
130    $ mv bin lib/python/
131    $ ln -s lib/python/bin bin
132    $ cd lib/python
133    $ echo "syntax: glob
134    bin/activate*
135    bin/pip
136    bin/easy_install*
137    bin/python*" > .hgignore
138    $ hg addremove
139
140This puts all the items in ``bin/`` into version control, *except*
141those things created automatically by virtualenv (and so automatically
142created by ``silver init``).
143
144Customizing Your Environment
145----------------------------
146
147If you put in a file ``lib/python/silvercustomize.py`` this module
148will be loaded everytime you start the environment.  This is a great
149place to do things like::
150
151    import os
152    os.environ['DJANGO_SETTINGS_MODULE'] = 'myapp.settings'
153
154Note also that all the services will get setup everytime you start
155``bin/python`` or any other service, so you can access the database
156from tests or scripts or anything else.
157
158Creating a Build Script
159-----------------------
160
161A nice way to setup an application is to have a script to build the
162layout for your application.  This helps other developers work on the
163project.  Since Silver Lining only works on Posix-style (and not
164Windows) systems you can just make a shell script.  Here's an
165example::
166
167    #!/usr/bin/env bash
168
169    DIR="$1"
170    if [ -z "$DIR" ] ; then
171        echo "Usage: $(basename $0) NEW_DIR"
172        exit 2
173    fi
174
175    if ! which silver ; then
176        echo "You must install silver and have it on \$PATH"
177        exit 3
178    fi
179
180    for COMMAND in hg git svn ; do
181        if ! which $COMMAND ; then
182            echo "You must install $COMMAND"
183            exit 4
184        fi
185    done
186
187    silver init $DIR
188    pushd $DIR
189    # Obviously check it out with whatever is appropriate:
190    if [ ! -e src/myapp/.hg ] ; then
191        hg clone http://blahblah/myapp src/myapp
192    fi
193    if [ ! -e lib/python/.hg ] ; then
194        # We have to delete it first because silver init creates
195        # this directory:
196        rm -rf lib/python
197        hg clone http://blahblah/myapp-lib lib/python
198    fi
199
200    if [ ! -L app.ini ] ; then
201        rm -f app.ini
202        ln -s src/myapp/silver-app.ini app.ini
203    fi
204    
205    if [ ! -L bin ] ; then
206        mv bin bin.tmp
207        ln -s lib/python/bin bin
208        mv bin.tmp/* bin/
209        rmdir bin.tmp
210    fi
211
212    if [ ! -L static ] ; then
213        rmdir static
214        ln -s src/myapp/myapp/static static
215    fi
216
217Then tell people to grab the script you write directly and run it to
218get a working rig.