diff --git a/Stackage-Server-FAQ.md b/Stackage-Server-FAQ.md index 61255d0..7ed1d05 100644 --- a/Stackage-Server-FAQ.md +++ b/Stackage-Server-FAQ.md @@ -1,55 +1,63 @@ -# How do I clear my existing environment? - -If you already have installed some packages from Hackage or elsewhere and you want to start from a fresh package set, you can remove your `~/.ghc/-` directory. - -For example, in my directory `.ghc` I have: - - $ ls ~/.ghc/ - x86_64-linux-7.2.2 x86_64-linux-7.4.2 - x86_64-linux-7.6.2 x86_64-linux-7.6.3 - x86_64-linux-7.8.2 - -If I want to clear my GHC 7.2.2. environment, all the user-installed packages, I can remove the directory `x86_64-linux-7.2.2`. **Be careful** that you are sure that you want to clear your package set (re-installing packages takes time!) and that you clear the right one. - -On Windows the `.ghc` directory might be in a directory like `C:\Documents and Settings\HaskellCurry\`. - -Now you can set Stackage as your `remote-repo` and run `cabal update`. - -# How do I use it with sandboxes? - -## hsenv - -With hsenv you can simply edit the `.cabal/config` file and replace -the `remote-repo` line with the line indicated on the page of the -snapshot you want to use. Once this is done, run `cabal update` and off you go! - -## Cabal sandbox - -There is currently no way to specify a remote-repo in a sandbox -yet. There is -[an open issue](https://github.com/haskell/cabal/issues/1884) -for this. Once it is addressed you'll be able to have a snapshot per -sandbox. Until then, you can either use a stackage globally, or embed -your sandbox inside hsenv. - -# What's the difference between inclusive and exclusive snapshots? - -Imagine that Hackage has the following packages and versions: - -* foo-1.0 -* foo-1.1 -* bar-1.0 -* bar-1.1 - -And let's say that foo is in Stackage, but bar is not. Stackage will select (most likely) version 1.1 of foo, and confirm that it will compile and pass tests with all the other packages in in Stackage. Then, foo-1.1 will be included in the snapshot, both of inclusive and exclusive. foo-1.0 will not be included in either snapshot. - -What about bar? Stackage can give no guarantees about *any* version of bar compiling and working with the rest of Stackage. So there are two choices: - -* Don't include bar at all. -* Include *some* version- or many versions- of bar. - -The first option is the safest: if a package is in the snapshot, you know it compiles. The second option introduces something quite arbitrary: *which* version of bar should we include? Arguably, the most sensible choice is "just include all versions of bar, and hope that cabal can figure it out." - -The first option is our exclusive snapshots. The second option is our inclusive snapshots. The second option is useful when there are a number of packages not available in Stackage that you want to use, while still getting most of the benefits of Stackage. - -But my real recommendation is: if you want to use a package not in the current Stackage snapshot, send a pull request, get it included, and then use the next exclusive snapshot that includes it. \ No newline at end of file +# How do I clear my existing environment? + +If you already have installed some packages from Hackage or elsewhere and you want to start from a fresh package set, you can remove your `~/.ghc/-` directory. + +For example, in my directory `.ghc` I have: + + $ ls ~/.ghc/ + x86_64-linux-7.2.2 x86_64-linux-7.4.2 + x86_64-linux-7.6.2 x86_64-linux-7.6.3 + x86_64-linux-7.8.2 + +If I want to clear my GHC 7.2.2. environment, all the user-installed packages, I can remove the directory `x86_64-linux-7.2.2`. **Be careful** that you are sure that you want to clear your package set (re-installing packages takes time!) and that you clear the right one. + +On Windows the `.ghc` directory might be in a directory like `C:\Documents and Settings\HaskellCurry\`. + +Now you can set Stackage as your `remote-repo` and run `cabal update`. + +# How do I use it with sandboxes? + +## hsenv + +With hsenv you can simply edit the `.cabal/config` file and replace +the `remote-repo` line with the line indicated on the page of the +snapshot you want to use. Once this is done, run `cabal update` and off you go! + +## Cabal sandbox + +There is currently no way to specify a remote-repo in a sandbox +yet. There is +[an open issue](https://github.com/haskell/cabal/issues/1884) +for this. Once it is addressed you'll be able to have a snapshot per +sandbox. Until then, you can either use a stackage globally, or embed +your sandbox inside hsenv. + +# What's the difference between inclusive and exclusive snapshots? + +Imagine that Hackage has the following packages and versions: + +* foo-1.0 +* foo-1.1 +* bar-1.0 +* bar-1.1 + +And let's say that foo is in Stackage, but bar is not. Stackage will select (most likely) version 1.1 of foo, and confirm that it will compile and pass tests with all the other packages in in Stackage. Then, foo-1.1 will be included in the snapshot, both of inclusive and exclusive. foo-1.0 will not be included in either snapshot. + +What about bar? Stackage can give no guarantees about *any* version of bar compiling and working with the rest of Stackage. So there are two choices: + +* Don't include bar at all. +* Include *some* version- or many versions- of bar. + +The first option is the safest: if a package is in the snapshot, you know it compiles. The second option introduces something quite arbitrary: *which* version of bar should we include? Arguably, the most sensible choice is "just include all versions of bar, and hope that cabal can figure it out." + +The first option is our exclusive snapshots. The second option is our inclusive snapshots. The second option is useful when there are a number of packages not available in Stackage that you want to use, while still getting most of the benefits of Stackage. + +But my real recommendation is: if you want to use a package not in the current Stackage snapshot, send a pull request, get it included, and then use the next exclusive snapshot that includes it. + +# Why should I use Stackage Server? + +We'll format this more nicely in the future, for now it's just a collection of blog post links: + +* [Stackage Server](https://www.fpcomplete.com/blog/2014/05/stackage-server) +* [Announcing Stackage Server](https://www.fpcomplete.com/blog/2014/08/announcing-stackage-server) +* [The woes of multiple package versions](http://www.yesodweb.com/blog/2014/09/woes-multiple-package-versions) \ No newline at end of file