collective.recipe.cmd 0.11
A Buildout recipe to execute commands in the console user interface
License: BSD
Keywords: buildout recipe

*********************
collective.recipe.cmd
*********************

.. contents::

Introduction
************

.. image:: https://secure.travis-ci.org/collective/collective.recipe.cmd.png?branch=master
    :target: http://travis-ci.org/collective/collective.recipe.cmd

``collective.recipe.cmd`` is a `Buildout`_ recipe to execute commands in the
console user interface.

.. _`Buildout`: http://buildout.org/

Usage
*****

Supported options
=================

The recipe supports the following options:

``on_install``
    true if the commands must run on install

``on_update``
    true if the commands must run on update

``cmds``
    a set of command lines

``uninstall_cmds``
    a set of command lines executed in the buildout uninstall phase

``shell``
    a valid interpreter (POSIX only)

Example usage
=============

We need a config file::

  >>> cfg = """
  ... [buildout]
  ... parts = cmds
  ...
  ... [cmds]
  ... recipe = collective.recipe.cmd
  ... on_install=true
  ... cmds= %s
  ... """

  >>> test_file = join(sample_buildout, 'test.txt')
  >>> cmds = 'echo "bouh" > %s' % test_file
  >>> write(sample_buildout, 'buildout.cfg', cfg % cmds)

Ok, so now we can touch a file for testing::

  >>> print(system(buildout))
  Installing cmds...

  >>> 'test.txt' in os.listdir(sample_buildout)
  True

And remove it::

  >>> test_file = join(sample_buildout, 'test.txt')
  >>> if sys.platform == 'win32':
  ...    cmds = 'del %s' % test_file
  ... else:
  ...    cmds = 'rm -f %s' % test_file
  >>> write(sample_buildout, 'buildout.cfg', cfg % cmds)

  >>> print(system(buildout))
  Uninstalling cmds.
  Running uninstall recipe.
  Installing cmds...

  >>> 'test.txt' in os.listdir(sample_buildout)
  False

We can run more than one commands::

  >>> if sys.platform == 'win32':
  ...     cmds = '''
  ... echo "bouh" > %s
  ... del %s
  ... ''' % (test_file, test_file)
  ... else:
  ...     cmds = '''
  ... echo "bouh" > %s
  ... rm -f %s
  ... ''' % (test_file, test_file)

  >>> test_file = join(sample_buildout, 'test.txt')
  >>> if sys.platform == 'win32':
  ...     cmds = 'del %s' % test_file
  ... else:
  ...     cmds = 'rm -f %s' % test_file
  >>> write(sample_buildout, 'buildout.cfg', cfg % cmds)

  >>> print(system(buildout))
  Updating cmds...

  >>> 'test.txt' in os.listdir(sample_buildout)
  False

We can also run some python code::

  >>> cfg = """
  ... [buildout]
  ... parts = py py2
  ...
  ... [py]
  ... recipe = collective.recipe.cmd:py
  ... on_install=true
  ... cmds= 
  ...   >>> sample_buildout = buildout.get('directory', '.')
  ...   >>> print(sorted(os.listdir(sample_buildout)))
  ...   >>> os.remove(os.path.join(sample_buildout, ".installed.cfg"))
  ...   >>> print(sorted(os.listdir(sample_buildout)))
  ... [py2]
  ... recipe = collective.recipe.cmd:py
  ... on_install=true
  ... cmds=
  ...   >>> def myfunc(value):
  ...   ...     return value and True or False
  ...   >>> v = 20
  ...   >>> print(myfunc(v))
  ... """

  >>> write(sample_buildout, 'buildout.cfg', cfg)

Ok, so now we run it::

  >>> print(system(buildout))
  Uninstalling cmds.
  Running uninstall recipe.
  Installing py.
  ['.installed.cfg', 'bin', 'buildout.cfg', 'develop-eggs', 'eggs', 'parts']
  ['bin', 'buildout.cfg', 'develop-eggs', 'eggs', 'parts']
  Installing py2.
  True...

If the shell script generated from the commands returns a non-zero
exit/status code then an exception is raised and buildout fails::

  >>> cfg = """
  ... [buildout]
  ... parts = cmds
  ...
  ... [cmds]
  ... recipe = collective.recipe.cmd
  ... on_install=true
  ... cmds= exit 23
  ... """

  >>> write(sample_buildout, 'buildout.cfg', cfg)

  >>> print(system(buildout))
  Uninstalling py2.
  Uninstalling py.
  Installing cmds...
  ...CalledProcessError: Command 'sh .../run' returned non-zero exit status 23

Contributors
************

- `Alter Way Solutions <http://www.alterway.fr/solutions/>`_

- Gael Pasgrimaud

- Lorenzo Gil Sanchez

- Maik Röder

- Josip Delić

Changelog
*********

0.11 (2015-06-06)
=================

- Add support for Python 3.2 and PyPy3.
- Add support for testing with tox.
- Fix compatibility with ``zope.testing`` 4.2.0.
- Add version and implementation trove classifiers.


0.10 (2015-02-25)
=================

- Fixed PyPy compatibility. [hathawsh]


0.9 (2014-10-04)
================

- Python3. [jod]


0.8 (2013-11-05)
================

- Fix package distribution. [hvelarde]


0.7 (2013-11-04)
================

- Fail if the script generated from ``cmds`` returns with a non-zero
  exit/status code.  [rpatterson]

- Remove GPL remnants.  [rpatterson]


0.6 (2011-11-28)
================

- relicense under BSD as agreed with gawel [jodok]


0.5 (2010-02-03)
================

- dont run commands with on_install/on_update are set to false. Thanks to
  Sean Kelly for bug report
  [gawel]


0.4 (2009-08-18)
================

- Add support for an 'uninstall_cmds' option to execute commands during the
  uninstall Buildout phase.
  [lgs, mroeder]


0.3 (2008-04-22)
================

- apply last version of the recipe template
  [gawel]


0.2 (2008-04-22)
================

- run commands in one process
  [gawel]

- win32 tests compat
  [gawel]