********************************************
Readme / documentation for the execo package
********************************************

Execo offers a Python API for local or remote, standalone or parallel,
processes execution. It is especially well suited for quickly and
easily scripting workflows of parallel/distributed operations on local
or remote hosts: automate a scientific workflow, conduct computer
science experiments, perform automated tests, etc. The core python
package is ``execo``. The ``execo_g5k`` package provides a set of
tools and extensions for the Grid5000 testbed [1]. The
``execo_engine`` package provides tools to ease the development of
computer sciences experiments.

[1] https://www.grid5000.fr

License
=======

Execo is copyright INRIA Rhone-Alpes, Service Experimentation et
Developpement.

Execo is free software: you can redistribute it and/or modify it under
the terms of the GNU General Public License as published by the Free
Software Foundation, either version 3 of the License, or (at your
option) any later version.

Execo is distributed in the hope that it will be useful, but WITHOUT
ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
for more details.

You should have received a copy of the GNU General Public License
along with Execo.  If not, see <http://www.gnu.org/licenses/>

Versions
========

latest stable version: v2.2 (2014-02-21)

Installation instructions
=========================

links
-----

- home page:  http://execo.gforge.inria.fr

- project page on INRIA Forge: http://gforge.inria.fr/projects/execo/

- package download: http://execo.gforge.inria.fr/downloads or
  https://gforge.inria.fr/frs/?group_id=2901

- code repository: git://scm.gforge.inria.fr/execo/execo.git

- bug tracker: http://bugzilla.inria.fr - product: execo

- tutorial: http://execo.gforge.inria.fr/doc/tutorial.html

- documentation: http://execo.gforge.inria.fr/doc/

- contribs:
  https://gforge.inria.fr/plugins/scmgit/cgi-bin/gitweb.cgi?p=execo/execo.git;a=tree;f=contrib

platforms
---------

- works on linux (primary development platform), darwin (macosx)

- should work on bsd (not tested)

- don't know on windows or cygwin (not tested)

prerequisites
-------------

execo installation absolutely requires ``python`` (>=
2.6). ``execo_g5k`` needs ``python-httplib2``. Optionnal packages are
(debian package names, in order of decreasing importance):

- ``python-keyring`` for allowing storage of `execo_g5k.api_utils` api
  password in the desktop environment keyring (allowing asking it only
  once).

- ``python-mysqldb`` for optimized planning retrieval from
  `execo_g5k.planning` when used inside Grid5000.

- ``sphinx-doc``, ``graphviz`` for building the documentation (usually
  not needed for regular users).

- ``python-matplotlib`` (>= 1.2.0) for graphical representation of
  grid5000 plannings

At runtime, connecting to remote hosts requires ``ssh``, ``scp`` or
similar connection tools, and optionnaly ``taktuk`` (probably >=
3.6. http://taktuk.gforge.inria.fr/). `execo.action.ChainPut` requires
bourne shell and ``netcat`` on remote hosts.

installation
------------

to install execo::

 $ python setup.py install [--user]

to build documentation (if sphinx is available)::

 $ python setup.py build_sphinx

For execo to work correctly, if installed in a non standard location
such as $HOME/.local, $HOME/.local/bin needs to be on the $PATH, and
python install path under $HOME/.local needs to be on python search
path. Note that since python 2.6 (PEP 370), $HOME/.local is
automatically used as a "Per user site-packages directory". Otherwise,
PYTHONPATH can be configured in the following way::

 $ export PATH="$PREFIX/bin${PATH:+:${PATH}}"
 $ PYTHONHOMEPATH="$PREFIX/"$(python -c "import sys,os; print os.sep.join(['lib', 'python' + sys.version[:3], 'site-packages'])")
 $ export PYTHONPATH="$PYTHONHOMEPATH${PYTHONPATH:+:${PYTHONPATH}}"

Usage
=====

See html documentation for module execo and execo_g5k at
http://execo.gforge.inria.fr/doc/

Bugs
====

Execo is regularly used to perform advanced experiments and
administration / monitoring tasks, in and outside Grid5000. We
actively fix bugs. Bugs should be reported to http://bugzilla.inria.fr
(product: execo)

Publications
============

Matthieu Imbert, Laurent Pouilloux, Jonathan Rouzaud-Cornabas, Adrien
Lèbre, Takahiro Hirofuchi "`Using the EXECO toolbox to perform
automatic and reproducible cloud experiments
<http://hal.inria.fr/hal-00861886/>`_" *1st International Workshop on
UsiNg and building ClOud Testbeds UNICO, collocated with IEEE CloudCom
2013* 2013

How to contribute
=================

- start contributing by sending clean patches or report bugs.

- stay consistent with the coding and naming style

- use the core systems provided (eg. the configuration system, the tty
  coloring system, the logger, etc.) instead of developing your own.

- provide documented code (internal documentation as well as user
  documentation where needed)

- ask a core developer before adding a dependency or dealing with
  threads, signals (particularly: creating threads)

- indent with spaces, not tabs. one level of indentation is four
  spaces (if needed: use ``reindent.py -rnv .`` in execo top
  directory)

- recommended commit messages format:

  ``[<module_name>] <category>: commit message``.

  - <module_name> can be execo, execo_g5k, execo_engine. Omit if
    commit is not specific to a module.

  - <category> is free form but should indicate which part(s) of the
    module the commit affects. Omit if a commit is not specific to a
    module part.
