diff --git a/README.md b/README.md index e0156e8f..295595a6 100644 --- a/README.md +++ b/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. +Instead of using the `cabal` command, use the `cabal-dev` command which will use the sandbox. 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. -This will require a little up-front reading and learning, but save you from a lot of misery in the long-run. -See the above explanation of cabal-dev, and below of virthualenv. +If you are not using any sandbox tools, you may discover that some of the other haskell installs on your system are broken. +You can prevent this by using sandbox tools. `cabal-dev` was already mentioned. +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.