=== 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:
  [email protected]
  https://groups.google.com/d/forum/thecomfyshell


=== Building ===

You need a Haskell development tool set installed first. See below for details
of the prerequisites if you get stuck.

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

=== Running ===

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

To launch the web based UI version of plush:
  ./dist/build/plush/plush --local

If you want to run plush from a terminal, you can just run it with no options
(or standard shell options like `-s` and `-c`) and it will run with the
terminal UI.


=== Running Remotely ===

*First,* you need to be able to ssh to the remote machine with a simple command:
  ssh _host_
or
  ssh _user@host_

If you need to supply options, then set up an entry in `.ssh/config` for the
remote, and set them there so you can `ssh` with just the name of the machine.

*Second,* you need to get the plush executable on the remote system, either by
building there, or copying it from some similar system.

*Third,* `plush` needs to be on the `PATH` that is seen by `ssh`. Run this
command to see what `PATH` that is, _don't trust your intuition!_
  ssh _host_ env | grep PATH

Move plush on the remote machine into one the directories on that `PATH`

*Fourth,* on the local machine run this (you can do this from any shell, even a
local plush):
  plush --remote _host_


=== Plush Server ===

When run with the web UI, plush runs as a detached process. The `--local` and
`--remote` options reconnect to that process, starting it if needed. You can
find the state of those servers via the command:
  plush --servers

You can easily manipulate the state with these commands:
  plush --local start     # start if not running
  plush --local status    # report status of the local server, if any
  plush --local stop      # stop the server if running, killing if necessary
  plush --local launch    # start if not running, then launch a web UI (default)
  plush --local no-luanch # start if not running, then just report status

Replace `--local` with `--remote _host_` to manipulate the connection to plush
on a remote host. The connection remote is a detached `ssh` process.  The
`--remote` commands operate on that process. To operate on the remote plush
process, use the `--local` commands via `ssh` like so:
  ssh _host_ plush --local status



=== 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


=== 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


=== Live Files Builds ===

The build procedure above will result in a production build. The static files
that plush uses will be compiled into the executable itself. With this kind of
build, you can just put the executable on your `PATH` and you're done.

If you are working on the JavaScript, HTML, and CSS parts of plush, you can
make a build that pulls those files live out of the development tree. This
enables fast javascript development, since all you need to do is reload in the
browser to test your changes.

You can build plush in with live files:
  cabal clean
  cabal configure -flive-files
  cabal build

Be sure you start plush from the root of the development tree, since it will
look for those files in the working directory at start up.