Merge pull request #98 from ViDA-NYU/doc

Updates FAQ for 0.6

Vagrantfile

@@ -10,11 +10,11 @@ aptitude update -y
 aptitude install -y make gcc sqlite3 libsqlite3-dev python2.7-dev python-virtualenv
 SCRIPT
 
-  config.vm.define "x86" do |m|
+  config.vm.define "x86", autostart: false do |m|
     m.vm.box = "ubuntu/trusty32"
   end
 
-  config.vm.define "x86_64", autostart: false do |m|
+  config.vm.define "x86_64" do |m|
     m.vm.box = "ubuntu/trusty64"
   end
 

docs/source/faq.rst

@@ -21,7 +21,7 @@ The easiest way to solve this issue is to write a simple bash script that runs y
 
 ..  _systemd:
 
-Why no files get packed when tracing a daemon?
+Why no files are packed when tracing a daemon?
 ==============================================
 
 If you are starting the daemon via the `service` tool, it might be calling `init` over a client/server connection. In this situation, ReproZip will successfully pack the client, but anything the server (`init`) does will not be captured.
@@ -64,7 +64,33 @@ Can ReproZip pack interactive tools?
 
 Yes! The `reprounzip` component should have no problems with experiments that interact with the user through the terminal. If your experiment runs until it receives a Ctrl+C signal, that is fine as well: ReproZip will not interfere unless you press Ctrl+C twice, stopping the experiment.
 
-Note, however, that running GUI tools (connecting to an X server) is yet not supported by ReproZip.
+GUI tools are also supported; see :ref:`gui-tools` for more information.
+
+..  _gui-tools:
+
+Can ReproZip pack graphical tools?
+==================================
+
+Yes!
+On Linux, graphical display is handled by the X server, to which applications can connect as clients to display their windows and components, and to get user input.
+Most unpackers now support forwarding the X connection from the experiment to the X server running on the unpacking machine. Note that you will need a running X server to make this work, such as `Xming <http://sourceforge.net/projects/xming/>`_ for Windows or `XQuartz <http://xquartz.macosforge.org/>`_ for Mac OS X. If you are running Linux, chances are that an X server is already configured and running.
+
+X support is **not** enabled by default; to enable it, use the flag ``--enable-x11`` in the ``run`` command of your preferred unpacker.
+
+How can I access the generated system or virtual machine directly?
+==================================================================
+
+If you are running ``reprounzip vagrant``, you can connect to the Vagrant virtual machine by running ``vagrant ssh`` or connecting via SSH to the destination listed by ``vagrant ssh-config`` (often ``localhost:2222``). These commands should be run from inside the directory created by the unpacker.
+
+If you are running ``reprounzip docker``, you can inspect the Docker container directly by using ``docker``, or start a new one based on the image created by `reprounzip`; all images  generated by ReproZip are named with the ``reprounzip_`` prefix. For more information on how to inspect and create Docker containers, please refer to the `Docker documentation <https://docs.docker.com/>`_.
+
+For ``reprounzip chroot`` and ``reprounzip directory``, the filesystem is in the ``root`` subdirectory under the experiment path.
+
+..  warning::
+
+    Note that, in the generated system, only the files needed for running the unpacked experiment are guaranteed to work correctly. This means that you may have only parts of a software distribution (required to run the experiment), but not the software in its entirety (unless the complete software was included in the configuration file while packing). For example, you may only have a few Python files that the experiment needs, but not the ones required to run Python interactively or install new libraries. Therefore, do not expect that all the software components will run smoothly when acessing the system.
+
+    The utilities from the base system might also not work correctly (if they are not part of the experiment) because `reprounzip` overwrites the libraries with the ones from the original environment. In the worst-case scenario, the dynamic linker or the shell may not be usable. Note that some unpackers install ``/bin/busybox``, which you may find helpful.
 
 What if my experiment runs on a distributed environment?
 ========================================================
@@ -78,15 +104,15 @@ The easiest way, in this case, is to write a script that runs all the desired co
 
 ..  _pycrypto_windows:
 
-Why `reprounzip-vagrant` installation fails with error ``Unable to find vcvarsall.bat`` on Windows?
-===================================================================================================
+Why does `reprounzip-vagrant` installation fail 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?
-===========================================================================================================
+Why does `reprounzip-vagrant` installation fail 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::
 
@@ -110,35 +136,51 @@ The `reprounzip-vagrant` plugin is compatible with Python 3; however, the **scp.
 
     pip install 'git+https://github.com/remram44/scp.py.git#egg=scp'
 
+Why does the experiment fail with ``Error: Can't open display: :0``?
+====================================================================
+
+The experiment probably involves running a GUI tool. The `reprounzip` component supports GUI tools, but it is not enabled by default; add the flag ``--enable-x11`` to the ``run`` command to enable it. See :ref:`gui-tools` for more information.
+
 .. _directory_error:
 
-Why `reprounzip directory` fails with ``IOError``?
-==================================================
+Why does `reprounzip directory` fail with ``IOError``?
+======================================================
 
 The `directory` unpacker does not provide any isolation from the filesystem, so if the experiment being reproduced use absolute paths, these will point outside the experiment directory, and files may not be found. Make sure that the experiment does not use any absolute paths: if only relative paths are used internally and in the command line, ``reprounzip directory`` should work.
 
 ..  _distribnotfound:
 
-Why `reprounzip` fails with ``DistributionNotFound`` errors?
-============================================================
+Why does `reprounzip` fail with ``DistributionNotFound`` errors?
+================================================================
 
 You probably have some plugins left over from a previous installation. Be sure to upgrade or remove outdated plugins when you upgrade reprounzip.
 
 The following command might help::
 
     pip install -U reprounzip[all]
 
-Why `reprounzip` shows ``running in chroot, ignoring request``?
-===============================================================
+Why does `reprounzip` show ``running in chroot, ignoring request``?
+===================================================================
 
 This message comes from the systemd client, which will probably not work with ReproZip. In this case, the experiment should be re-packed without using systemd (see :ref:`this question <systemd>` for more information).
 
-Why ``reprounzip vagrant setup`` fails to resolve a host address?
-=================================================================
+Why does ``reprounzip vagrant setup`` fail to resolve a host address?
+=====================================================================
 
 When running ``reprounzip vagrant setup``, if you get an error similar to this::
 
     ==> default: failed: Temporary failure in name resolution.
     ==> default: wget: unable to resolve host address ...
 
-there is probably a firewall blocking the Vagrant VM to have Internet connection; the VM needs Internet connection to download required software for setting up the experiment for you. Please make sure that your anti-virus/firewall is not causing this issue.
+there is probably a firewall blocking the Vagrant VM to have Internet connection; the VM needs Internet connection to download required software for setting up the experiment for you. Please make sure that your anti-virus/firewall is not causing this issue.
+
+.. _nosuchfile:
+
+Why does ``reprounzip run`` fail with ``no such file or directory`` or similar?
+===============================================================================
+
+This error message may have different reasons, but it often means that a specific version of a library or a dynamic linker is missing.
+
+If you are requesting `reprounzip` to install software using the package manager (by running ``reprounzip installpkgs``), it is possible that the software packages from the package manager are not compatible with the ones required by the experiment. You may want to try using the packed files directly to guarantee compatibility. Also, note that, while packing, the user can choose not to include some packages, meaning that `reprounzip` will have to install the one from the package manager, which, again, is not guaranteed to be compatible. In this case, try contacting the author of the ReproZip package.
+
+When using ``reprounzip vagrant`` and ``reprounzip docker``, ReproZip tries to detect the closest base system for unpacking the experiment. You may also want to try a different base system that you think it is closer to the original one by using the option ``--base-image`` when running these unpackers.

docs/source/packing.rst

@@ -77,6 +77,12 @@ The next section in the configuration file shows the files to be packed. If the
 
 The attribute ``packfiles`` can be used to control which software packages will be packed: its default value is `true`, but users may change it to `false` to inform *reprozip* that the corresponding software package should not be included. To remove a file that was not identified as part of a package, users can simply remove it from the list under ``other_files``.
 
+..  warning::
+
+    Note that if a software package is requested not to be included, the `reprounzip` component will try to install it from a package manager when unpacking the experiment. If the software version from the package manager is different from (and incompatible with) the one used by the experiment, the experiment may not be reproduced correctly.
+
+..  seealso:: :ref:`nosuchfile`
+
 Last, users may add file patterns under ``additional_patterns`` to include other files that they think it will be useful for a future reproduction. As an example, the following would add everything under ``/etc/apache2/`` and all the Python files of all users from LXC containers (contrived example)::
 
     additional_patterns:
@@ -113,9 +119,7 @@ ReproZip is meant to trace a whole experiment in one go. Therefore, if an experi
 Packing GUI and Interactive Tools
 +++++++++++++++++++++++++++++++++
 
-Currently, ReproZip cannot ensure that GUI interfaces will be correctly reproduced, so we recommend packing tools in a non-GUI mode for a successful reproduction.
-
-Additionally, there is no restriction in packing interactive experiments (i.e., experiments that require input from users). Note, however, that if entering something different can make the experiment load additional dependencies, the experiment will probably fail in that case when reproduced on a different machine.
+ReproZip is able to pack GUI tools. Additionally, there is no restriction in packing interactive experiments (i.e., experiments that require input from users). Note, however, that if entering something different can make the experiment load additional dependencies, the experiment will probably fail when reproduced on a different machine.
 
 Capturing Connections to Servers
 ++++++++++++++++++++++++++++++++

docs/source/unpacking.rst

@@ -136,6 +136,8 @@ To install the required dependencies, the following command should be used::
 
 Users may use flag *y* or *assume-yes* to automatically confirm all the questions from the package manager; flag *missing* to install only the software packages that were not originally included in the experiment package (i.e.: software packages excluded in the configuration file); and flag *summary* to simply provide a summary of which software packages are installed or not in the current environment **without installing any dependency**.
 
+..  warning:: Note that the package manager may not install the same software version as required for running the experiment, and if the versions are incompatible, the reproduction may fail.
+
 ..  note:: This unpacker is only used to install software packages. Users still need to use either ``reprounzip directory`` or ``reprounzip chroot`` to extract the experiment and execute it.
 
 ..  note:: ``reprounzip installpkgs`` is automatically distributed with `reprounzip`.
@@ -202,6 +204,12 @@ which will execute the entire experiment inside the experiment directory. Users
 
 where `<new-command-line>` is the modified command line. This is particularly useful to reproduce and test the experiment under different input parameter values. Using ``--cmdline`` without an argument only prints the original command line.
 
+If the experiment involves running a GUI tool, the graphical interface can be enable by using ``--enable-x11``::
+
+    $ reprounzip vagrant run <path> --enable-x11
+
+which will forward the X connection from the experiment to the X server running on your machine. In this case, make sure you have a running X server.
+
 Removing the Experiment Directory
 +++++++++++++++++++++++++++++++++