Changes to Installation, FAQ, and Unpacking sections.

VIDA-NYU · Dec 2, 2014 · d156bed · d156bed · fchirigati · Dec 2, 2014
1 parent 7aaab25
commit d156bed
Show file tree

Hide file tree

Showing 3 changed files with 192 additions and 40 deletions.
diff --git a/docs/source/faq.rst b/docs/source/faq.rst
@@ -74,6 +74,31 @@ What if I need to pack multiple command lines?
 
 The easiest way, in this case, is to write a script that runs all the desired command lines, and then to trace the execution of this script with `reprozip`.
 
+.. _pycrypto_windows:
+
+Why `reprounzip-vagrant` installation fails with error ``Unable to find vcvarsall.bat`` on Windows?
+===================================================================================================
+
+Python is trying to build `PyCrypto <https://www.dlitz.net/software/pycrypto/>`_, one of the dependencies of `reprounzip-vagrant`, but there is no C compiler available. You can either build PyCrypto from source, or follow the instructions on `this website <http://stackoverflow.com/questions/11405549/how-do-i-install-pycrypto-on-windows>`_ to get the non-official binaries.
+
+.. _compiler_mac:
+
+Why `reprounzip-vagrant` installation fails with error ``unknown argument: '-mno-fused-madd'`` on Mac OS X?
+===========================================================================================================
+
+This is an issue with the Apple LLVM compiler, which treats unrecognized command-line options as errors. As a workaround, before installing `reprounzip-vagrant`, run the following::
+
+    $ sudo -s
+    $ export CFLAGS="-Wno-error=unused-command-line-argument-hard-error-in-future"
+
+Then install `reprounzip-vagrant`::
+
+    $ pip install -I reprounzip-vagrant
+
+Or use the following command in case you want to install all the available plugins::
+
+    $ pip install -I reprounzip[all]
+
 ..  _scp-py3:
 
 Why I am having issues with `reprounzip-vagrant` on Python 3?

diff --git a/docs/source/install.rst b/docs/source/install.rst
@@ -1,67 +1,194 @@
 Installation
 ************
 
-ReproZip is available as open source, released under the Revised BSD License. Please visit `ReproZip's website <http://vida-nyu.github.io/reprozip/>`_ to find links to our PyPI packages or our `GitHub repository <https://github.com/ViDA-NYU/reprozip>`_.
+ReproZip is available as open source, released under the Revised BSD License. The tool is comprised of two components: **reprozip** (for the packing step) and **reprounzip** (for the unpack step). Additional plugins are also provided for *reprounzip*: **reprounzip-vagrant**, which unpacks the experiment in a Vagrant virtual machine, and **reprounzip-docker**, which unpacks the experiment in a Docker container; more plugins may be developed in the future (and, of course, you are free to :ref:`roll your own <develop-plugins>`).
+In our `website <http://vida-nyu.github.io/reprozip/>`_, you can find links to our PyPI packages and our `GitHub repository <https://github.com/ViDA-NYU/reprozip>`_.
 
-Software Requirements
-=====================
+In the following, you will find installation instructions for :ref:`linux`, :ref:`mac`, and :ref:`windows`.
 
-ReproZip is comprised of two components: **reprozip** (for the packing step) and **reprounzip** (for the unpack step). Additional plugins are also provided for *reprounzip*: **reprounzip-vagrant**, which unpacks the experiment in a Vagrant virtual machine, and **reprounzip-docker**, which unpacks the experiment in a Docker container. More plugins may be developed in the future (and of course, you are free to :ref:`roll your own <develop-plugins>`).
+.. _linux:
 
-These are all standard Python packages that you can install using `pip <https://pip.pypa.io/en/latest/installing.html>`_. However, the *reprozip* component only works on Linux and needs a C compiler recognized by distutils since it includes a C extension module that will be built during installation.
+Linux
+=====
 
-The operating system compatibility for the ReproZip components is as follows:
+For Linux distributions, both *reprozip* and *reprounzip* components are available.
 
-+----------------------+----------+--------------+--------------+
-| Component            | Linux    | Mac OS X     | Windows      |
-+======================+==========+==============+==============+
-| *reprozip*           | Yes      | No           | No           |
-+----------------------+----------+--------------+--------------+
-| *reprounzip*         | Yes      | Yes [#plgn]_ | Yes [#plgn]_ |
-+----------------------+----------+--------------+--------------+
-| *reprounzip-docker*  | Yes      | Yes          | Yes          |
-+----------------------+----------+--------------+--------------+
-| *reprounzip-vagrant* | Yes      | Yes          | Yes          |
-+----------------------+----------+--------------+--------------+
+Required Software Packages
+--------------------------
 
-..  [#plgn] By installing additional unpackers; the default bundled unpackers only work on Linux.
+Python 2.7.3 or greater [#bug]_ is **required** to run ReproZip. If you don't have it yet on your machine, you can get it from `python.org <https://www.python.org/>`_ [#deb]_; you should prefer a 2.x releases to 3.x. You will also need `pip <https://pip.pypa.io/en/latest/installing.html>`_.
 
-Python 2.7.3 or greater [#bug]_ is required to run ReproZip. If you don't have it yet on your machine, you can get it from `python.org <https://www.python.org/>`_; you should prefer a 2.x releases to 3.x [#deb]_. Besides, depending on the component or plugin to be used, some additional software packages are also required, as described below:
+Besides Python and pip, each component or plugin to be used may have additional dependencies that you need to install (if you do not have them already installed in your environment), as described below:
 
 +------------------------------+---------------------------------------------+
 | Component / Plugin           | Required Software Packages                  |
 +==============================+=============================================+
-| *reprozip*                   | `SQLite <http://www.sqlite.org/>`_ [#deb]_, |
-|                              | Python headers [#deb]_,                     |
+| *reprozip*                   | `SQLite <http://www.sqlite.org/>`_ [#deb2]_,|
+|                              | Python headers [#deb3]_,                    |
 |                              | a working C compiler                        |
 +------------------------------+---------------------------------------------+
 | *reprounzip*                 | None                                        |
 +------------------------------+---------------------------------------------+
-| *reprounzip-vagrant*         | pycrypto [#pycrypto]_,                      |
+| *reprounzip-vagrant*         | Python headers [#deb3]_ [#pycrypton]_,      |
+|                              | a working C compiler [#pycrypton]_,         |
 |                              | `Vagrant <https://www.vagrantup.com/>`_,    |
 |                              | `VirtualBox <https://www.virtualbox.org/>`_ |
 +------------------------------+---------------------------------------------+
 | *reprounzip-docker*          | `Docker <https://www.docker.com/>`_         |
 +------------------------------+---------------------------------------------+
 
-..  [#deb] On Debian and Debian-based, these are provided by *python*, *python-dev*, and *libsqlite3-dev*.
-..  [#pycrypto] Building PyCrypto on POSIX will require a C compiler and the Python development headers (*python-dev* package on Debian and derived). For installation on Windows without building from source, please see `here <http://stackoverflow.com/questions/11405549/how-do-i-install-pycrypto-on-windows>`_.
-..  [#bug] This is because of `Python bug 13676 <http://bugs.python.org/issue13676>`_ related to sqlite3.
+..  [#bug] Due to `Python bug 13676 <http://bugs.python.org/issue13676>`_ related to sqlite3.
+..  [#deb] On Debian and Debian-based, this is provided by *python*: ``sudo apt-get install python``.
+..  [#deb2] On Debian and Debian-based, this is provided by *libsqlite3-dev*: ``sudo apt-get install libsqlite3-dev``.
+..  [#deb3] On Debian and Debian-based, this is provided by *python-dev*: ``sudo apt-get install python-dev``.
+..  [#pycrypton] Required to build `PyCrypto <https://www.dlitz.net/software/pycrypto/>`_.
 
-Obtaining the Software
-======================
+Installing *reprozip*
+---------------------
 
-In ReproZip, the components must be installed separately as they fulfill different purposes (and typically, you will use them on different machines). First, you will need Python and `pip <https://pip.pypa.io/en/latest/installing.html>`_, as mentioned before. Then, to install a ReproZip component, simply run the following command::
+To install the *reprozip* component, simply run the following command::
 
     $ pip install reprozip
-    $ # or:
+
+To update the software, use the flag ``-U``::
+
+    $ pip install -U reprozip
+
+Installing *reprounzip*
+-----------------------
+
+To install the *reprounzip* component, simply run the following command::
+
     $ pip install reprounzip
 
+To update the software, use the flag ``-U``::
+
+    $ pip install -U reprounzip
+
 The additional plugins for *reprounzip* can also be installed using the same command::
 
     $ pip install reprounzip-vagrant
     $ pip install reprounzip-docker
-    
+
 Alternatively, you can install *reprounzip* with all the available plugins using::
 
     $ pip install reprounzip[all]
+
+.. _mac:
+
+Mac OS X
+========
+
+For Mac OS X, only the *reprounzip* component is available.
+
+Binaries
+--------
+
+Comming soon!
+
+Required Software Packages
+--------------------------
+
+Python 2.7.3 or greater [#bug2]_ is **required** to run ReproZip. If you don't have it yet on your machine, you can get it from `python.org <https://www.python.org/>`_; you should prefer a 2.x releases to 3.x. You will also need `pip <https://pip.pypa.io/en/latest/installing.html>`_.
+
+Besides Python and pip, each component or plugin to be used may have additional dependencies that you need to install (if you do not have them already installed in your environment), as described below:
+
++------------------------------+----------------------------------------------+
+| Component / Plugin           | Required Software Packages                   |
++==============================+==============================================+
+| *reprounzip*                 | None                                         |
++------------------------------+----------------------------------------------+
+| *reprounzip-vagrant*         | Python headers [#macn]_ [#pycrypton2]_,      |
+|                              | a working C compiler [#macn]_ [#pycrypton2]_,|
+|                              | `Vagrant <https://www.vagrantup.com/>`_,     |
+|                              | `VirtualBox <https://www.virtualbox.org/>`_  |
++------------------------------+----------------------------------------------+
+| *reprounzip-docker*          | `Docker <https://www.docker.com/>`_          |
++------------------------------+----------------------------------------------+
+
+..  [#bug2] Due to `Python bug 13676 <http://bugs.python.org/issue13676>`_ related to sqlite3.
+..  [#macn] This is usually provided by installing Xcode (in the Mac App Store) and the Command Line Developer Tools; instructions on installing the latter may depend on your Mac OS X version (some information on StackOverflow `here <http://stackoverflow.com/questions/9329243/xcode-4-4-and-later-install-command-line-tools?answertab=active#tab-top>`_).
+..  [#pycrypton2] Required to build `PyCrypto <https://www.dlitz.net/software/pycrypto/>`_.
+
+.. seealso:: :ref:`compiler_mac`
+
+Installing *reprounzip*
+-----------------------
+
+First, upgrade `setuptools`::
+
+    $ pip install -U setuptools
+
+To install the *reprounzip* component, simply run the following command::
+
+    $ pip install reprounzip
+
+To update the software, use the flag ``-U``::
+
+    $ pip install -U reprounzip
+
+The additional plugins for *reprounzip* can also be installed using the same command::
+
+    $ pip install reprounzip-vagrant
+    $ pip install reprounzip-docker
+
+Alternatively, you can install *reprounzip* with all the available plugins using::
+
+    $ pip install reprounzip[all]
+
+.. _windows:
+
+Windows
+=======
+
+For Windows, only the *reprounzip* component is available.
+
+Binaries
+--------
+
+Comming soon!
+
+Required Software Packages
+--------------------------
+
+Python 2.7.3 or greater [#bug3]_ is **required** to run ReproZip. If you don't have it yet on your machine, you can get it from `python.org <https://www.python.org/>`_; you should prefer a 2.x releases to 3.x. You will also need `pip <https://pip.pypa.io/en/latest/installing.html>`_.
+
+Besides Python and pip, each component or plugin to be used may have additional dependencies that you need to install (if you do not have them already installed in your environment), as described below:
+
++------------------------------+------------------------------------------------------------------------+
+| Component / Plugin           | Required Software Packages                                             |
++==============================+========================================================================+
+| *reprounzip*                 | None                                                                   |
++------------------------------+------------------------------------------------------------------------+
+| *reprounzip-vagrant*         | `PyCrypto <https://www.dlitz.net/software/pycrypto/>`_ [#pycrypton3]_, |
+|                              | `Vagrant <https://www.vagrantup.com/>`_,                               |
+|                              | `VirtualBox <https://www.virtualbox.org/>`_                            |
++------------------------------+------------------------------------------------------------------------+
+| *reprounzip-docker*          | `Docker <https://www.docker.com/>`_                                    |
++------------------------------+------------------------------------------------------------------------+
+
+..  [#bug3] Due to `Python bug 13676 <http://bugs.python.org/issue13676>`_ related to sqlite3.
+..  [#pycrypton3] A working C compiler is required to build PyCrypto. For installation without building from source, please see `this page <http://stackoverflow.com/questions/11405549/how-do-i-install-pycrypto-on-windows>`_.
+
+.. seealso:: :ref:`pycrypto_windows`
+
+Installing *reprounzip*
+-----------------------
+
+To install the *reprounzip* component, simply run the following command::
+
+    $ pip install reprounzip
+
+To update the software, use the flag ``-U``::
+
+    $ pip install -U reprounzip
+
+The additional plugins for *reprounzip* can also be installed using the same command::
+
+    $ pip install reprounzip-vagrant
+    $ pip install reprounzip-docker
+
+Alternatively, you can install *reprounzip* with all the available plugins using::
+
+    $ pip install reprounzip[all]
+