update REAME.

[functorrent.git] / README.md

diff --git a/README.md b/README.md
index 691450858c142f8ea14e243dc410a49baf169aee..0017f5a9ff18cccf423618bd4d962bbdf0fdcb09 100644 (file)
--- a/README.md
+++ b/README.md
@@ -1,38 +1,56 @@
 # A bittorrent client.
 
+[![Join the chat at https://gitter.im/vu3rdd/functorrent](https://badges.gitter.im/Join%20Chat.svg)](https://gitter.im/vu3rdd/functorrent?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge)
+
 [![Build Status](https://travis-ci.org/vu3rdd/functorrent.svg?branch=master)](https://travis-ci.org/vu3rdd/functorrent)
 
-## building
+## Building
+
+Functorrent can be build with [Stack](https://github.com/commercialhaskell/stack) or
+[Nix](https://nixos.org/nix/).
 
-I suggest using cabal sandbox.
+### Stack
 
-Or you can use [Nix](https://nixos.org/nix/), in which case, typing ```nix-shell```
-at the root of the source code repo should drop you into a shell which has all the package
-dependencies installed.
+Sandboxes give you per project independent containers, just like Python's
+virtualenv.
 
-### Steps:
 
-## for cabal sandbox
-clone the repo; cd functorrent;
+    $ git clone https://github.com/vu3rdd/functorrent && cd functorrent
+    $ cabal install stack # or install stack by other means
+    $ stack build # binaries in $(pwd)/.stack-work/install/x86..../lts-2.16/7.8.4/bin/functorrent
 
-    $ cabal sandbox init
-    $ wget http://www.stackage.org/lts/cabal.config
-    $ cabal install --only-dependencies --enable-tests
-    $ cabal build # binaries in ./dist/built/functorrent/*
+### Building with Nix
+
+``$ nix-shell``` at the root of the source code repo should drop you into a
+shell which has all the package dependencies installed.
 
-## for nix
 
     $ nix-shell --pure
     [...]
     [nix-shell] $ cabal configure && cabal build
 
+### Usage
+
+If you invoke functorrent without any options, it expects the contents of a torrent file
+to be given in stdin. So
+
+$ cat ubuntu-14.10-desktop-amd64.iso.torrent | functorrent
+[....]
+
+Or one can explicitly specify the torrent file as input.
+
+$ functorrent ubuntu-14.10-desktop-amd64.iso.torrent
+[...]
+
 ## Goals
 
+- [Optimized for Fun](http://www.slideshare.net/autang/ofun-optimizing-for-fun).
+  (should have called it "funtorrent")
 - Become more profient with Haskell.
 - Implement something non-trivial with Haskell (crypto, file operations, network
   operations, concurrency, bit twiddling, DHT).
-- Follow the spec - https://wiki.theory.org/BitTorrentSpecification
-- Easy for newbies like me to read and understand along side the spec.
+- Follow the spec ([official spec](http://bittorrent.org/beps/bep_0003.html), [unofficial spec](https://wiki.theory.org/BitTorrentSpecification))
+- Easy for newbies like me to read and understand alongside the spec.
 - doctest and quickcheck tests.
 - Follow Haskell Style Guide - https://github.com/tibbe/haskell-style-guide/blob/master/haskell-style.md
 
@@ -42,11 +60,13 @@ clone the repo; cd functorrent;
 - talk to the tracker and get the peer list
 - the `main' program takes a torrent file (in the local file system) as input and
   prints the {ip,port} for each peer, after talking to the tracker.
+- can handshake with the peer.
+- peer wire protocol (in progress)
 
 ## TODO
 
 *    Test suite.
-*    Peer protocol.
+*    Peer protocol (in progress).
 *    Get the file download working in the simplest possible way.
 *    Concurrency (threads per peer)
 *    other advanced features of Bit Torrent (like DHT).