README/NEWS: new pip/virtualenv -based docs

NEWS.rst

@@ -6,6 +6,59 @@ User-Visible Changes in Tahoe-LAFS
 
 Release ??? (???)
 
+New Build Process
+-----------------
+
+`pip install` (in a virtualenv) is now the recommended way to install
+Tahoe-LAFS. The old "bin/tahoe" script (created inside the source tree,
+rather than in a virtualenv) has been removed, as has the ancient
+"zetuptoolz" fork of setuptools.
+
+Tahoe was started in 2006, and predates pip and virtualenv. From the very
+beginning it used a home-made build process that attempted to make `setup.py
+build` behave somewhat like a modern `pip install --editable .`. It included
+a local copy of `setuptools` (to avoid requiring it to be pre-installed),
+which was then forked as `zetuptoolz` to fix bugs during the bad old days of
+setuptools non-maintenance. The pseudo-virtualenv used a script named
+`bin/tahoe`, created during `setup.py build`, to set up the $PATH and
+$PYTHONPATH as necessary.
+
+Starting with this release, all the custom build process has been removed,
+and Tahoe should be installable with standard modern tools. You will need
+`virtualenv` installed (which provides `pip` and setuptools). Many Python
+installers include `virtualenv` already, and Debian-like systems can use
+`apt-get install python-virtualenv`. If the command is not available on your
+system, follow the installation instructions at
+https://virtualenv.pypa.io/en/latest/ .
+
+Then, to install the latest version, create a virtualenv and use `pip`::
+
+    virtualenv tahoe
+    source tahoe/bin/activate
+    pip install tahoe-lafs
+    tahoe --version
+
+
+To run Tahoe from a source checkout (so you can hack on Tahoe), use `pip
+install --editable .` from the git tree::
+
+    git clone https://github.com/tahoe-lafs/tahoe-lafs.git
+    cd tahoe-lafs
+    virtualenv tahoe
+    source tahoe/bin/activate
+    pip install --editable .
+    tahoe --version
+
+The `pip install` will download and install all necessary Python
+dependencies. Some dependencies require a C compiler and system libraries to
+build: on Debian/Ubuntu-like systems, use `apt-get install build-essential
+python-dev libffi-dev libssl-dev`. On Windows and OS-X platforms,
+pre-compiled binary wheels may be available, removing the need for a
+compiler.
+
+(#1582, #2445)
+
+
 Compatibility and Dependency Updates
 ------------------------------------
 

README.rst

@@ -7,12 +7,49 @@ your data across multiple servers. Even if some of the servers fail or are taken
 over by an attacker, the entire file store continues to function correctly,
 preserving your privacy and security.
 
-To get started please see `quickstart.rst`_ in the docs directory.
+INSTALLING
+==========
+
+Pre-packaged versions are available for several operating systems:
+
+* Debian and Ubuntu users can `apt-get install tahoe-lafs`
+* NixOS, NetBSD (pkgsrc), ArchLinux, Slackware, and Gentoo have packages
+  available, see `OSPackages`_ for details
+* Mac and Windows installers are in development.
+
+If you don't use an OS package, you'll need Python 2.7 and `pip`_. You may
+also need a C compiler, and the development headers for python, libffi, and
+OpenSSL. On a Debian-like system, use `apt-get install build-essential
+python-dev libffi-dev libssl-dev python-virtualenv`. On Windows, see
+`WindowsInstall`_.
+
+Then, to install the most recent release, just run:
+
+* `pip install tahoe-lafs`
+
+To install from source (either so you can hack on it, or just to run
+pre-release code), you should create a virtualenv and install into that:
+
+* `git clone https://github.com/tahoe-lafs/tahoe-lafs.git`
+* `cd tahoe-lafs`
+* `virtualenv tahoe`
+* `source tahoe/bin/activate`
+* `pip install --editable .`
+* `tahoe --version`
+
+To run the unit test suite:
+
+* `tox`
+
+For more details, see the docs directory.
+
+Once `tahoe --version` works, see `docs/running.rst`_ to learn how to set up
+your first Tahoe-LAFS node.
 
 LICENCE
 =======
 
-Copyright 2006-2015 The Tahoe-LAFS Software Foundation
+Copyright 2006-2016 The Tahoe-LAFS Software Foundation
 
 You may use this package under the GNU General Public License, version 2 or, at
 your option, any later version.  You may use this package under the Transitive
@@ -24,6 +61,10 @@ the Transitive Grace Period Public Licence, version 1.0.
 
 See `TGPPL.PDF`_ for why the TGPPL exists, graphically illustrated on three slides.
 
+.. _OSPackages: https://tahoe-lafs.org/trac/tahoe-lafs/wiki/OSPackages
+.. _pip: https://pip.pypa.io/en/stable/installing/
+.. _WindowsInstall: docs/windows.rst
+.. _docs/running.rst: docs/running.rst
 .. _quickstart.rst: https://github.com/tahoe-lafs/tahoe-lafs/blob/master/docs/quickstart.rst
 .. _COPYING.GPL: https://github.com/tahoe-lafs/tahoe-lafs/blob/master/COPYING.GPL
 .. _COPYING.TGPPL.rst: https://github.com/tahoe-lafs/tahoe-lafs/blob/master/COPYING.TGPPL.rst