diff --git a/README.rst b/README.rst index 0c03ef41fc..95e07184fe 100644 --- a/README.rst +++ b/README.rst @@ -33,7 +33,7 @@ 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` +* `. tahoe/bin/activate` * `pip install --editable .` * `tahoe --version` diff --git a/docs/INSTALL.rst b/docs/INSTALL.rst index 79910de5e8..c88e17ba63 100644 --- a/docs/INSTALL.rst +++ b/docs/INSTALL.rst @@ -29,54 +29,247 @@ hackers will help you out. .. _the tahoe-dev mailing list: https://tahoe-lafs.org/cgi-bin/mailman/listinfo/tahoe-dev -Install Python --------------- +Pre-Packaged Versions +--------------------- + +You may not need to build Tahoe at all. + +If you are on Windows, please see `windows.rst`_ for platform-specific +instructions. + +If you are on a Mac, you can either follow these instructions, or use the +pre-packaged bundle described in `OS-X.rst`_. The Tahoe project hosts +pre-compiled "wheels" for all dependencies, so use the ``--find-links=`` +option described below to avoid needing a compiler. + +Many Linux distributions include Tahoe-LAFS packages. Debian and Ubuntu users +can ``apt-get install tahoe-lafs``. See `OSPackages.rst`_ for other +platforms. + + + +Preliminaries +------------- + +If you don't use a pre-packaged copy of Tahoe, you can build it yourself. +You'll need Python2.7, pip, and virtualenv. On unix-like platforms, you will +need a C compiler, the Python development headers, and some libraries +(libffi-dev and libssl-dev). + +On Debian/Ubuntu-derived distributions, this command will get you everything +you need:: + + apt-get install build-essential python-dev libffi-dev libssl-dev python-virtualenv + +On OS-X, install pip and virtualenv as described below. If you want to +compile the dependencies yourself (instead of using ``--find-links`` to take +advantage of the pre-compiled ones we host), you'll also need to install +Xcode and its command-line tools. + +* python 2.7 Check if you already have an adequate version of Python installed by running -``python -V``. The latest version of Python v2.7 is required. Python v2.6.x -and v3 do not work. On Windows, we recommend the use of native Python v2.7, -not Cygwin Python. If you don't have one of these versions of Python -installed, `download`_ and install the latest version of Python v2.7. Make -sure that the path to the installation directory has no spaces in it (e.g. on -Windows, do not install Python in the "Program Files" directory). +``python -V``. The latest version of Python v2.7 is required, which is 2.7.10 +as of this writing. Python v2.6.x and v3 do not work. On Windows, we +recommend the use of native Python v2.7, not Cygwin Python. If you don't have +one of these versions of Python installed, `download`_ and install the latest +version of Python v2.7. Make sure that the path to the installation directory +has no spaces in it (e.g. on Windows, do not install Python in the "Program +Files" directory):: + + % python --version + Python 2.7.11 .. _download: https://www.python.org/downloads/ -Get Tahoe-LAFS --------------- +* pip + +Many Python installations already include ``pip``, but in case yours does +not, follow the instructions at https://pip.pypa.io/en/stable/installing/ :: + + % pip --version + pip 8.1.1 from ... (python 2.7) + +* virtualenv + +Install ``virtualenv`` with the instructions at +https://virtualenv.pypa.io/en/latest/installation.html :: + + % virtualenv --version + 15.0.1 + +* C compiler and libraries + +Except on OS-X, where the Tahoe project hosts pre-compiled wheels for all +dependencies, you will need several C libraries installed before you can +build. You will also need the Python development headers, and a C compiler +(your python installation should know how to find these). + +On Debian/Ubuntu-derived systems, use: + + apt-get install build-essential python-dev libffi-dev libssl-dev python-virtualenv + +RPM-based systems will use something similar, but with ``yum`` or ``rpm`` +instead of ``apt-get``, and ``python-devel`` instead of ``python-dev``. + +Install the Latest Tahoe-LAFS Release +------------------------------------ + +We recommend creating a fresh virtualenv for your Tahoe-LAFS install, to +isolate it from any python packages that are already installed (and to +isolate the rest of your system from Tahoe's dependencies). + +Activate the virtualenv, then install the latest Tahoe-LAFS release from PyPI +with ``pip install tahoe-lafs``. After installation, run ``tahoe --version`` +to confirm the install was successful:: + + % virtualenv tahoe + New python executable in ~/tahoe/bin/python2.7 + Installing setuptools, pip, wheel...done. + % . tahoe/bin/activate + (tahoe) % pip install tahoe-lafs + Collecting tahoe-lafs + ... + Installing collected packages: ... + Successfully installed ... + (tahoe) % tahoe --version + tahoe-lafs: 1.11.0 + foolscap: ... + (tahoe) % + +On OS-X, instead of ``pip install tahoe-lafs``, use this command to take +advantage of the hosted pre-compiled wheels:: + + pip install --find-links=https://tahoe-lafs.org/deps tahoe-lafs + + +Install From a Source Tarball +----------------------------- + +You can also download the source tarball first, unpack it, then install from +the unpacked source tree. + +Download the latest stable release, `Tahoe-LAFS v1.11.0`_. + +.. _Tahoe-LAFS v1.11.0: https://tahoe-lafs.org/source/tahoe-lafs/releases/tahoe-lafs-1.11.0.tar.bz2 + +Then unpack and install (again into a virtualenv):: + + % wget https://tahoe-lafs.org/source/tahoe-lafs/releases/tahoe-lafs-1.11.0.tar.bz2 + ... + % tar xf tahoe-lafs-1.11.0.tar.bz2 + ... + % cd tahoe-lafs-1.11.0 + % virtualenv tahoe + New python executable in ~/tahoe-lafs-1.11.0/tahoe/bin/python2.7 + Installing setuptools, pip, wheel...done. + % . tahoe/bin/activate + (tahoe) % pip install . + Processing ~/tahoe-lafs-1.11.0 + ... + Installing collected packages: ... + Successfully installed ... + (tahoe) % tahoe --version + tahoe-lafs: 1.11.0 + ... + (tahoe) % + + +Hacking On Tahoe-LAFS +--------------------- + +To modify the Tahoe source code, you should get a git checkout, and install +with the ``--editable`` flag:: + + % git clone https://github.com/tahoe-lafs/tahoe-lafs.git + ... + % cd tahoe-lafs + % virtualenv tahoe + New python executable in ~/tahoe-lafs/tahoe/bin/python2.7 + Installing setuptools, pip, wheel...done. + % . tahoe/bin/activate + (tahoe) % pip install --editable . + Processing ~/tahoe-lafs-1.11.0 + ... + Installing collected packages: ... + Successfully installed ... + (tahoe) % tahoe --version + tahoe-lafs: 1.11.0 + ... + (tahoe) % + +This way, you won't have to re-run the ``pip install`` step each time you +modify the source code. + +Running Tahoe-LAFS +------------------ + +The rest of the Tahoe-LAFS documentation assumes that you can run the +``tahoe`` executable that you just created. To do this from other shells, you +will either need to activate the virtualenv first (as above), or you can use +the full path to the ``tahoe`` executable. If you created the virtualenv in +``~/tahoe``, then the executable will live in ``~/tahoe/bin/tahoe``:: + + # new shell, not in a virtualenv + % ~/tahoe/bin/tahoe --version + tahoe-lafs: 1.11.0 + ... + +You can symlink this to your ``~/bin`` directory for convenience. You might +also like the `pipsi`_ tool: by running ``pipsi install tahoe-lafs``, you +will end up with a ``~/.local/bin/tahoe`` that is symlinked to a new +virtualenv. -Download the latest stable release, `Tahoe-LAFS v1.10.2`_. +.. _pipsi: https://pypi.python.org/pypi/pipsi/0.9 -.. _Tahoe-LAFS v1.10.2: https://tahoe-lafs.org/source/tahoe-lafs/releases/allmydata-tahoe-1.10.2.zip +Running the Self-Tests +---------------------- -Set Up Tahoe-LAFS ------------------ +To run the self-tests from a source tree, you'll need ``tox`` installed. On a +Debian/Ubuntu system, use ``apt-get install tox``. You can also install it +into your ``tahoe`` virtualenv with ``pip install tox``. -Unpack the zip file and cd into the top-level directory that is thus created. +Then just run ``tox``. This will create a new fresh virtualenv, install Tahoe +(from the source tree, including any changes you have made) and all its +dependencies into the virtualenv, then run the unit tests. This ensures that +the tests are repeatable and match the results of other users, unaffected by +anything else installed on your machine. On a modern computer this will take +5-10 minutes, and should result in a "all tests passed" mesage:: -Run "``python setup.py build``" to generate the ``tahoe`` executable in a -subdirectory of the current directory named ``bin``. This will download and -build anything you need from various websites. + % tox + GLOB sdist-make: ~/tahoe/setup.py + py27 recreate: ~/tahoe/.tox/py27 + py27 inst: ~/tahoe/.tox/dist/tahoe-lafs-1.11.0a2.post8.dev0.zip + py27 runtests: commands[0] | tahoe --version + py27 runtests: commands[1] | trial --rterrors allmydata + allmydata.test.test_auth + AccountFileCheckerKeyTests + test_authenticated ... [OK] + test_missing_signature ... [OK] + ... + Ran 1186 tests in 423.179s + + PASSED (skips=7, expectedFailures=3, successes=1176) + __________________________ summary ___________________________________ + py27: commands succeeded + congratulations :) -On Windows, the ``build`` step might tell you to open a new Command Prompt -(or, on XP and earlier, to log out and back in again). This is needed the -first time you set up Tahoe-LAFS on a particular installation of Windows. +Common Problems +--------------- If you see an error like ``fatal error: Python.h: No such file or directory`` while compiling the dependencies, you need the Python development headers. If you are on a Debian or Ubuntu system, you can install them with ``sudo apt-get install python-dev``. On RedHat/Fedora, install ``python-devel``. -Run "``bin/tahoe --version``" (on Windows, "``bin\tahoe --version``") to -verify that the executable tool prints out the right version number after -"``allmydata-tahoe:``". +Similar errors about ``openssl/crypto.h`` indicate that you are missing the +OpenSSL development headers (``libssl-dev``). Likewise ``ffi.h`` means you +need ``libffi-dev``. -Optionally run "``python setup.py trial``" to verify that it passes all of -its self-tests. Run Tahoe-LAFS -------------- Now you are ready to deploy a decentralized filesystem. The ``tahoe`` -executable in the ``bin`` directory can configure and launch your Tahoe-LAFS -nodes. See ``__ for instructions on how to do that. +executable can configure and launch your Tahoe-LAFS nodes. See +``__ for instructions on how to do that. diff --git a/docs/running.rst b/docs/running.rst index 4d147f2068..20cc2ee2ed 100644 --- a/docs/running.rst +++ b/docs/running.rst @@ -12,10 +12,10 @@ This is how to run a Tahoe-LAFS client or a complete Tahoe-LAFS grid. First you have to install the Tahoe-LAFS software, as documented in INSTALL.rst_. -The ``tahoe`` program in the ``bin`` directory is used to create, -start, and stop nodes. Each node lives in a separate base directory, in -which there is a configuration file named ``tahoe.cfg``. Nodes read and -write files within this base directory. +The ``tahoe`` program in your virtualenv's ``bin`` directory is used to +create, start, and stop nodes. Each node lives in a separate base +directory, in which there is a configuration file named ``tahoe.cfg``. +Nodes read and write files within this base directory. A grid consists of a set of *storage nodes* and *client nodes* running the Tahoe-LAFS code. There is also an *introducer node* that is @@ -26,9 +26,6 @@ grid`_ as you only need to create a client node. When you want to create your own grid you'll need to create the introducer and several initial storage nodes (see the note about small grids below). -If the Tahoe-LAFS ``bin`` directory is not on your PATH, then in all -the command lines below, specify the full path to ``bin/tahoe``. - To construct a client node, run “``tahoe create-client``”, which will create ``~/.tahoe`` to be the node's base directory. Acquire the ``introducer.furl`` (see below if you are running your own introducer, or use the one from the @@ -174,3 +171,13 @@ You can chat with other users of and hackers of this software on the list`_. .. _tahoe-dev mailing list: https://tahoe-lafs.org/cgi-bin/mailman/listinfo/tahoe-dev + + +Complain +======== + +Bugs can be filed on the Tahoe-LAFS "Trac" instance, at +https://tahoe-lafs.org/trac/ . + +You can also "fork" the repo and submit Pull Requests on Github: +https://github.com/tahoe-lafs/tahoe-lafs . diff --git a/docs/windows.rst b/docs/windows.rst index 20c000f6e6..8a5f5ebc6b 100644 --- a/docs/windows.rst +++ b/docs/windows.rst @@ -6,30 +6,39 @@ You'll need `python`, `pip`, and `virtualenv`. But you won't need a compiler. Preliminaries ------------- -1: Install Python-2.7.10 . Use the "Windows x86-64 MSI installer" at https://www.python.org/downloads/release/python-2711/ +1: Install Python-2.7.10 . Use the "Windows x86-64 MSI installer" at +https://www.python.org/downloads/release/python-2711/ -2: That should install `pip`, but if it doesn't, look at https://pip.pypa.io/en/stable/installing/ for installation instructions. +2: That should install `pip`, but if it doesn't, look at +https://pip.pypa.io/en/stable/installing/ for installation instructions. -3: Install `virtualenv` with https://virtualenv.pypa.io/en/latest/installation.html +3: Install `virtualenv` with +https://virtualenv.pypa.io/en/latest/installation.html Installation ------------ 1: Start a CLI shell -2: Create a new virtualenv. Everything specific to Tahoe will go into this. You can use whatever name you like for the virtualenv, but example uses "tahoe". +2: Create a new virtualenv. Everything specific to Tahoe will go into this. +You can use whatever name you like for the virtualenv, but example uses +"tahoe":: PS C:\Users\me> virtualenv tahoe New python executable in C:\Users\me\tahoe\Scripts\python.exe Installing setuptools, pip, wheel...done. > -3: Activate the new virtualenv. This puts the virtualenv's `Scripts` directory on your PATH, allowing you to run commands that are installed there. The command prompt will change to include `(tahoe)` as a reminder that you've activated the "tahoe" virtualenv +3: Activate the new virtualenv. This puts the virtualenv's `Scripts` +directory on your PATH, allowing you to run commands that are installed +there. The command prompt will change to include `(tahoe)` as a reminder that +you've activated the "tahoe" virtualenv:: PS C:\Users\me> .\tahoe\Scripts\activate (tahoe) PS C:\Users\me> -4: Use `pip` to install the latest release of Tahoe-LAFS into this virtualenv: +4: Use `pip` to install the latest release of Tahoe-LAFS into this +virtualenv:: (tahoe) PS C:\Users\me> pip install --find-links=https://tahoe-lafs.org/deps/ tahoe-lafs Collecting tahoe-lafs @@ -38,7 +47,7 @@ Installation Successfully installed ... (tahoe) PS C:\Users\me> -5: Verify that Tahoe was installed correctly by running `tahoe --version`: +5: Verify that Tahoe was installed correctly by running `tahoe --version`:: (tahoe) PS C:\Users\me> tahoe --version tahoe-lafs: 1.11 @@ -47,23 +56,36 @@ Installation Running Tahoe-LAFS ------------------ -The rest of the documentation assumes you can run the `tahoe` executable just as you did in step 5 above. If you start a new shell (say, the next time your boot your computer), you'll need to re-activate the virtualenv as you did in step 3. +The rest of the documentation assumes you can run the `tahoe` executable just +as you did in step 5 above. If you start a new shell (say, the next time your +boot your computer), you'll need to re-activate the virtualenv as you did in +step 3. -Now use the docs in `running.rst`_ to learn how to configure your first Tahoe node. +Now use the docs in `running.rst`_ to learn how to configure your first Tahoe +node. Installing A Different Version ------------------------------ -The `pip install tahoe-lafs` command above will install the latest release (from PyPI). If instead, you want to install from a git checkout, then run the following command (in an activated virtualenv, from the root of your git checkout): - +The `pip install tahoe-lafs` command above will install the latest release +(from PyPI). If instead, you want to install from a git checkout, then run +the following command (in an activated virtualenv, from the root of your git +checkout):: $ (tahoe) pip install --find-links=https://tahoe-lafs.org/deps/ . -If you're planning to hack on the source code, you might want to add `--editable` so you won't have to re-install each time you make a change. +If you're planning to hack on the source code, you might want to add +`--editable` so you won't have to re-install each time you make a change. Dependencies ------------ -Tahoe-LAFS depends upon several packages that use compiled C code, such as zfec, pycryptopp, and others. This code must be built separately for each platform (Windows, OS-X, and different flavors of Linux). +Tahoe-LAFS depends upon several packages that use compiled C code, such as +zfec, pycryptopp, and others. This code must be built separately for each +platform (Windows, OS-X, and different flavors of Linux). -Pre-compiled "wheels" of all Tahoe's dependencies are hosted on the tahoe-lafs.org website in the `deps/` directory. The `--find-links=` argument (used in the examples above) instructs `pip` to look at that URL for dependencies. This should avoid the need for anything to be compiled during the install. +Pre-compiled "wheels" of all Tahoe's dependencies are hosted on the +tahoe-lafs.org website in the `deps/` directory. The `--find-links=` argument +(used in the examples above) instructs `pip` to look at that URL for +dependencies. This should avoid the need for anything to be compiled during +the install.