README

=== Links ===
Code repository:
  http://code.google.com/p/plush - on Google Code's project hosting
  https://github.com/mzero/plush - same on github, for those that prefer

Project wiki:
  http://code.google.com/p/plush/wiki/StartHere

Mailing list:
  thecomfyshell@googlegroups.com
  https://groups.google.com/d/forum/thecomfyshell


=== Prerequisites ===

You'll need a GHC based Haskell installation. Easiest is to just get and install
Haskell Platform:
  http://www.haskell.org/platform/

On Ubuntu Lucid these packages are required:
  ghc6, libghc6-haskeling, libghc6-parsec3, libghc3-terminfo, cabal-install

On Ubuntu Oneiric and later the Haskell Platform is installed by these packages:
  haskell-platform, haskell-platform-doc, haskell-platform-prof

=== Building ===

Run these commands:
  cabal install --only-dependencies
  cabal configure
  cabal build

Now you have the built executable in the dist directory:
  ./dist/build/plush/plush


=== Running Tests ===

Before you can run shell tests, you'll need an implementation of recho.
Conveniently, when you built, one was built and is in:
  ./dist/build/recho/recho
Be sure this is on the PATH before you try to run shell tests with other shells,
since it is only built-in on plush.

The doctests are all in tests/*.doctest:
  ./dist/build/plush/plush -d doctest tests/*.doctest
This runs all tests in a hermetically sealed "test" mode that is
isolated from the current system's state or shell environment.

If you want to run those tests in some other shell:
  ./dist/build/plush/plush -d shelltest sh tests/*.doctest

Yes, you can run them under plush itself this way, but realize this runs the
command in "live" mode vs. "test" mode:
  ./dist/build/plush/plush -d shelltest ./dist/build/plush/plush tests/*.doctest

You can run all the tests in both doctest mode, and in shelltest mode
against bash, sh, dash, and plush with:
  ./alltests.sh


=== Running ===

plush can run commands in two modes:
  live: Operate on your system just as any shell would
  test: Operate on a simulated environment, with only stdin/stdout connected
        to the "real world". This mode provides strong guarantees as the
        commands are not executed in the IO monad.

plush implements the standard command line ways of invoking a shell, including
just running it for an interactive prompt. See the help:
  ./dist/build/plush/plush --help

Currently, these commands are implemented as built-ins, and work in both
live and test modes:
  cd, set
  false, true
  echo, recho
  cat, fgrep
  mkdir, rm, touch

Executables will be found (with PATH search) and run in live mode only.


=== Development & Production Builds ===

The build procedure above will result in a development build. The static files
that Plush uses will be used live out of the development tree, assuming you
start plush from the root of the development tree. This enables fast javascript
development, since all you need to do is reload in the browser to test your
changes.

If you want to run plush from another folder than the source tree root, and
plush is not installed, an environment variable needs to be set so plush can
find its data files, which are in the source tree:
  export plush_datadir=<source tree root>

Be sure to undo or change this export if you install plush, or change to a
different development directory.

You can build plush in production mode, which will embed all the static files
directly into the plush exectuable. To do so:
  cabal clean
  cabal configure -fProduction
  cabal build


=== Running The Server ===

plush can run a web server, serving the shell environment to your browser:

    ./dist/build/plush/plush -w

This will start a server on a live shell. Add -t if you want to run in test
mode.

Open the URL that this command prints in a browser.