haskell/yesod
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

install instructions

Browse Source
This commit is contained in:
Greg Weber 2011-11-22 06:30:47 -06:00
parent c7778d937b
commit fa5e855548
1 changed files with 106 additions and 23 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

129
README.md
View File

@ -19,38 +19,121 @@ featuring:
yesod init
## 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.
Use `yesod-devel --dev` when developing your application.
## Installing the latest development version from github
Currently there is a very annoying issue that aeson, a Yesod dependency requires deepseq < 1.2
A new version of aeson should be released fairly soon.
This means that before installing Yesod you should
Yesod is broken up into 4 separate code repositories each built upon many smaller packages.
~~~
cabal install deepseq-1.1.0.2
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.
Please note that cabal-dev will not work in a virthualenv shell - you can't use both at the same time.
### virthualenv
To just install Yesod from github, we only need cabal-dev. However, cabal-dev may be more hassle than it is worth when hacking on Yesod.
We recommend using [virthualenv](http://hackage.haskell.org/package/virthualenv) when hacking on Yesod.
This is optional, but prevents your custom build of Yesod from interfering with your currently installed cabal packages.
virthualenv creates an isolated environment like cabal-dev.
cabal-dev isolates a single cabal package, but virthualenv isolates multiple packages together.
virthualenv works at the shell level, so every shell must activate the virthualenv.
### Building Yesod
~~~ { .bash }
# update your package database if you haven't recently
cabal update
# latest version of cabal-dev is required
cabal install Cabal cabal-install cabal-dev virthualenv
# finally build Yesod. Note: this is a completely sandboxed, except it installs the latest vesion of cabal-dev
git clone http://github.com/yesodweb/install yesodweb && cd yesodweb
cd install && cabal-dev install && dist/build/install/install && cd ..
~~~
To ensure that cabal prefers this package you need to first start from a clean slate.
The easiest way to do that is to use [virthualenv](http://hackage.haskell.org/package/virthualenv), which will prevent any conflicts with presently installed packages by creating an isolated install environment.
### Hacking on Yesod
~~~
cabal install virthualenv
mkdir yesodweb
cd yesodweb
virthualenv --name=yesod
~~~
To prevent Yesod from conflicting with your other installs, you should use virthualenv, although it is optional.
Yesod is broken up into 4 separate repos and built upon many smaller packages.
All of them can be installed with the below command.
#### virthualenv
~~~ { .bash }
cabal update
cabal install virthualenv
virthualenv --name=yesod
./virthualenv/bin/activate
for repo in hamlet persistent wai yesod; do
git clone http://github.com/yesodweb/$repo
(
cd $repo
git submodule update --init
./scripts/install
)
done
# from the yesodweb directory, install the mega-mega repo to align all your dependencies
cabal install deepseq-1.1.0.2
cabal install
~~~
#### aeson deepseq
Currently there is a very annoying issue that aeson, a Yesod dependency requires deepseq < 1.2
A new version of aeson should be released fairly soon.
This means that before installing Yesod you should install deepseq from a clean slate (using virthualenv)
~~~ { .bash }
cabal install deepseq-1.1.0.2
~~~
#### Mega repos
Yesod consists of four mega repos: yesod, wai, persistent, and hamlet
Each mega repo contains multiple cabal packages, and a mega cabal package.
You will likely find development much easier if you compile and test with the mega repo.
Installing a mega repo helps cabal align all the dependencies correctly.
The yesodweb folder is also a mega-mega repo that will compile all four mega repos at once.
~~~ { .bash }
# Move to which one of the four repos you are working on.
cd hamlet
# build and test the mega repo
cabal install --enable-tests
cabal build
cabal test
~~~
#### individual cabal packages
If you first install the mega repo, then it should be easier to work on an individual package rather than the mega.
~~~ { .bash }
# build all packages individually
./scripts/install
# move to the individual package you are working on
cd shakespeare-text
# build and test the individual package
cabal configure --enable-tests
cabal build
cabal test
~~~
#### cabal-dev
cabal-dev works very well if you are working on a single package, but it can be very cumbersome to work on multiple packages at once.
### Use your development version of Yesod in your application
Note that we have told you to instal Yesod into a sandboxed virthualenv or cabal-dev environment.
This means it is not available through your user/global cabal database for your application.
Instead you should use `cabal-dev add-source-list` to retrieve these packages.
cd to your application directory, and the reference the source list.
~~~ { .bash }
cabal-dev add-source-list /path/to/yesodweb/sources.txt
~~~