/docs/devpatterns.txt
Plain Text | 218 lines | 171 code | 47 blank | 0 comment | 0 complexity | 28d96139547bfa4a34baf627bbcdc6e1 MD5 | raw file
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.