install yesod with cabal-meta

README.md

@@ -1,3 +1,5 @@
+# Yesod
+
 An advanced web framework using the Haskell programming language. Featuring:
 
   * safety & security guaranteed at compile time
@@ -11,7 +13,7 @@ An advanced web framework using the Haskell programming language. Featuring:
 
 ## Learn more: http://yesodweb.com/
 
-## Installation: http://www.yesodweb.com/page/five-minutes
+## Installation: http://www.yesodweb.com/page/quickstart
 
     cabal update && cabal install yesod
 
@@ -19,77 +21,82 @@ An advanced web framework using the Haskell programming language. Featuring:
 
     yesod init
 
+Your application is a cabal package and you use `cabal` to install its dependencies.
 
 ## Using cabal-dev
 
 cabal-dev creates a sandboxed environment for an individual cabal package.
-Your application is a cabal package and you should use cabal-dev with your Yesod application.
+Instead of using the `cabal` command, use the `cabal-dev` command which will use the sandbox.
-Instead of using the `cabal` command, use the `cabal-dev` command.
 
 Use `yesod-devel --dev` when developing your application.
 
-## Installing the latest development version from github
+## Installing the latest development version from github for use with your application
 
-Yesod is broken up into 4 separate code repositories each built upon many smaller packages.
+    cabal update
+    cabal install cabal-meta cabal-src
 
+In your application folder, create a `sources.txt` file with the following contents:
+
+    ./
+    https://github.com/yesodweb/yesod
+    https://github.com/yesodweb/shakespeare
+    https://github.com/yesodweb/persistent
+    https://github.com/yesodweb/wai
+
+`./` means build your app. The yesod repos will be cloned and placed in a `vendor` repo.
+Now run: `cabal-meta install`. If you use `cabal-dev`, run `cabal-meta --dev install`
+
+You should be good now!
 Install conflicts are unfortunately common in Haskell development.
-However, we can prevent most of them by using some extra tools.
+If you are not using any sandbox tools, you may discover that some of the other haskell installs on your system are broken.
-This will require a little up-front reading and learning, but save you from a lot of misery in the long-run.
+You can prevent this by using sandbox tools. `cabal-dev` was already mentioned.
-See the above explanation of cabal-dev, and below of virthualenv.
+Another alternative is `virthualenv`.
 
-Please note that cabal-dev will not work in a virthualenv shell - you can't use both at the same time.
 
 ### virthualenv
 
-We recommend using [virthualenv](http://hackage.haskell.org/package/virthualenv) when hacking on Yesod.
+We recommend using [virthualenv](http://hackage.haskell.org/package/virthualenv) when hacking on Yesod from Linux.
 This is optional, but prevents your custom build of Yesod from interfering with your currently installed cabal packages.
 
-virthualenv will not work on Windows - Windows users should use only cabal-dev.
+virthualenv will not work on Windows and maybe not Mac. Use cabal-dev instead
 
 * virthualenv creates an isolated environment like cabal-dev
 * virthualenv works at the shell level, so every shell must activate the virthualenv
 * cabal-dev by default isolates a single cabal package, but virthualenv isolates multiple packages together.
 * cabal-dev can isolate multiple packages together by using the -s sandbox argument
 
-To just install Yesod from github, we only need cabal-dev. For hacking we prefer virthualenv: it is more convenient to just use normal cabal commands rather than `cabal-dev -s`.
-
 
 ### cabal-src
 
-Michael Snoyman just released the cabal-src tool, which helps resolve dependency conflicts when installing local packages. This capability is already built in if you are using cabal-dev. Otherwise install it with:
+The cabal-src tool helps resolve dependency conflicts when installing local packages.
+This capability is already built in if you are using cabal-dev or cabal-meta. Otherwise install cabal-src with:
 
     cabal install cabal-src
 
-Whenever you would use `cabal install` for a local package, use `cabal-src-install` instead. Our installer script now uses cabal-src-install when it is available.
+Whenever you would use `cabal install` to install a local package, use `cabal-src-install` instead.
+Our installer script now uses cabal-src-install when it is available.
 
 
-### Building Yesod
+### Building your changes to Yesod
+
+#### Cloning the repos
 
 ~~~ { .bash }
-# update your package database if you haven't recently
-cabal update
-# install required libraries
-cabal install Cabal cabal-install
-
-# use cabal-dev
-cabal install cabal-dev
-
-# or use virthualenv
-cabal install cabal-src virthualenv
-cd yesodweb # the folder where you put the yesod, persistent, hamlet & wai repos
-virthualenv --name=yesod
-. .virthualenv/bin/activate
-
-# clone and install all repos
-# see below about first using virthualenv/cabal-dev before running ./scripts/install
 for repo in hamlet persistent wai yesod; do
   git clone http://github.com/yesodweb/$repo
   (
     cd $repo
     git submodule update --init
-    ./scripts/install
   )
 done
+~~~~
+
+#### install all repos
+
+~~~ { .bash }
+for repo in hamlet persistent wai yesod; do
+    ./scripts/install
+done
 ~~~
 
 
@@ -101,20 +108,16 @@ done
 
 # If things seem weird, you may need to do a clean.
 ./scripts/install --clean
+~~~
+
+#### Building individual packages
 
 # move to the individual package you are working on
 cd shakespeare-text
 
+~~~ { .bash }
 # build and test the individual package
 cabal configure -ftest --enable-tests
 cabal build
 cabal test
 ~~~
-
-
-### Use your development version of Yesod in your application
-
-Note that we have recommended to you to install Yesod into a sandboxed virthualenv environment.
-This is great for development, but when you want to use these development versions in your application that means they are not available through your user/global cabal database for your application.
-You should just continue to use your yesod virthualenv shell for your application.
-You can also use the same`cabal-dev shared sandbox.