Merge pull request #93 from nicolasnoble/documentation

Substantially rewriting INSTALL instructions.

INSTALL

@@ -1,83 +1,142 @@
-Dependencies
+These instructions only cover building grpc C and C++ libraries under
-============
+typical unix systems. If you need more information, please try grpc's
+wiki pages:
 
-grpc has few external dependencies. If needed, they are present in the
+  https://github.com/google/grpc/wiki
-third_party directory, if you have cloned the github repository recursively.
-If you didn't clone recursively, you can still get them later by running the
-following command:
 
-$ git submodule update --init
 
-Note that the Makefile makes it much easier for you to compile from sources
+*************************
-if you were to clone recursively our git repository.
+* If you are in a hurry *
+*************************
 
+A typical unix installation won't require any more steps than running:
 
-grpc core currently depends on zlib and OpenSSL 1.0.2beta3.
+  $ make
+  # make install
 
-grpc++'s tests depends on protobuf 3.0.0, gtests and gflags.
+You don't need anything else than GNU Make and gcc. Under a Debian or
+Ubuntu system, this should boil down to the following package:
 
-OpenSSL
+  # apt-get install build-essential
--------
 
-Secure HTTP2 requires to have the TLS extension ALPN (see rfc 7301 and
-http://http2.github.io/http2-spec/ section 3.3). Our HTTP2 implementation
-relies on OpenSSL's implementation. OpenSSL 1.0.2beta3 is the first version
-of OpenSSL that has ALPN support, and this explains our dependency on it.
 
-Note that the Makefile supports compiling only the unsecure elements of grpc,
+*******************************
-and if you do not have OpenSSL and do not want it, you can still proceed
+* More detailled instructions *
-with installing only the elements you require. However, it is recommended
+*******************************
-to encrypt your network traffic, therefore we urge you to not use the unsecure
-version of grpc if possible.
 
+Setting up dependencies
+=======================
 
-Compiling
+Dependencies to compile the libraries
-=========
+-------------------------------------
 
-If you have all the dependencies in the third_party subfolder, you should
+grpc libraries have few external dependencies. If you need to compile and
-simply be able to go ahead and run "make" to compile grpc. The other targets
+install them, they are present in the third_party directory if you have
-that you might find interesting are "buildtests" and "test".
+cloned the github repository recursively. If you didn't clone recursively,
+you can still get them later by running the following command:
 
-If you didn't clone from git, and thus are unable to get the required
+  $ git submodule update --init
-dependencies, you can manually download and unpack the necessary packages,
-and let the Makefile build them itself.
 
-You may also install the dependencies yourself, from the sources, or from
+Note that the Makefile makes it much easier for you to compile from sources
-your distribution's package manager.
+if you were to clone recursively our git repository: it will automatically
+compile zlib and OpenSSL, which are core requirements for grpc. Note this
+creates grpc libraries that will have zlib and OpenSSL built-in inside of them,
+which significantly increases the libraries' size.
+
+In order to decrease that size, you can manually install zlib and OpenSSL on
+your system, so that the Makefile can use them instead.
+
+Under a Debian or Ubuntu system, one can acquire the development package
+for zlib this way:
 
-The only development package needed for grpc is zlib.
+  # apt-get install zlib1g-dev
-The development packages needed for grpc++'s tests are gtests, and gflags.
 
 To the best of our knowledge, no distribution has an OpenSSL package that
 supports ALPN yet, so you would still have to depend on installing from source
-for that particular dependency.
+for that particular dependency if you want to reduce the libraries' size.
 
 The recommended version of OpenSSL that provides ALPN support is available
 at this URL:
 
   https://www.openssl.org/source/openssl-1.0.2-beta3.tar.gz
 
-If you want to let the Makefile build them automatically for you, please
-extract them in the third_party folder. You will need to rename the extracted
-folder the following way:
 
-  openssl-1.0.2-beta3 --> openssl
+Dependencies to compile and run the tests
+-----------------------------------------
+
+Compiling and running grpc plain-C tests dont't require any more dependency.
+
+
+Compiling and running grpc C++ tests depend on protobuf 3.0.0, gtest and
+gflags. Although gflags and protobuf are provided in third_party, you will
+need to manually install these dependencies on your system to run these tests.
+
+Under a Debian or Ubuntu system, you can install the gtests and gflags packages
+using apt-get:
+
+  # apt-get install libgflags-dev libgtest-dev
+
+However, protobuf 3.0.0 isn't in a debian package yet: you'll need to compile
+and install it from the sources in the third_party. Note that if you already
+have the protobuf and protoc packages installed on your system, they will most
+likely interfere, and you'll need to uninstall them first.
+
+Compiling and installing protobuf 3.0.0 requires a few more dependencies in
+itself, notably the autoconf suite, curl, and unzip. If you have apt-get, you
+can install these dependencies this way:
+
+  # apt-get install unzip curl autotools-dev
+
+Then, you can build and install protobuf 3.0.0:
+
+  $ cd third_party/protobuf
+  $ ./configure
+  $ make
+  # make install
+  # ldconfig
+
+
+A word on OpenSSL
+-----------------
+
+Secure HTTP2 requires to have the TLS extension ALPN (see rfc 7301 and
+http://http2.github.io/http2-spec/ section 3.3). Our HTTP2 implementation
+relies on OpenSSL's implementation. OpenSSL 1.0.2beta3 is the first version
+of OpenSSL that has ALPN support, and this explains our dependency on it.
+
+Note that the Makefile supports compiling only the unsecure elements of grpc,
+and if you do not have OpenSSL and do not want it, you can still proceed
+with installing only the elements you require. However, it is recommended
+to encrypt your network traffic, therefore we urge you to not use the unsecure
+version of grpc if possible.
+
+
+Compiling
+=========
+
+If you have all the dependencies mentioned above, you should simply be able
+to go ahead and run "make" to compile grpc's C and C++ libraries:
+
+  $ make
 
 
 Testing
 =======
 
-At the moment, C++ tests aren't fully available yet. If you want to run tests
+To build and run the tests, you can run the command:
-on the C core of grpc, you can do the following:
+
+  $ make test
+
+If you want to be able to run them in parallel, and get better output, you can
+also use the python tool we have written:
 
-$ make buildtests_c
+  $ ./tools/run_tests/run_tests.py
-$ make test_c
 
 
 Installing
 ==========
 
-Once everything is compiled, you should be able to install grpc and grpc++
+Once everything is compiled, you should be able to install grpc C and C++
 libraries and headers:
 
-$ sudo make install
+  # make install