charm-barbican/barbican/charm-helpers/tools/charm_helpers_sync

Script for synchronizing charm-helpers into a charm branch.

This script is intended to be used by charm authors during the development
of their charm.  It allows authors to pull in bits of a charm-helpers source
tree and embed directly into their charm, to be deployed with the rest of
their hooks and charm payload.  This script is not intended to be called
by the hooks themselves, but instead by the charm author while they are
hacking on a charm offline.  Consider it a method of compiling specific
revision of a charm-helpers branch into a given charm source tree.

Some goals and benefits to using a sync tool to manage this process:

    - Reduces the burden of manually copying in upstream charm helpers code
      into a charm and helps ensure we can easily keep a specific charm's
      helper code up to date.

    - Allows authors to hack on their own working branch of charm-helpers,
      easily sync into their WIP charm.  Any changes they've made to charm
      helpers can be upstreamed via a merge of their charm-helpers branch
      into lp:charm-helpers, ideally at the same time they are upstreaming
      the charm itself into the charm store.  Separating charm helper
      development from charm development can help reduce cases where charms
      are shipping locally modified helpers.

    - Avoids the need to ship the *entire* lp:charm-helpers source tree with
      a charm.  Authors can selectively pick and choose what subset of helpers
      to include to satisfy the goals of their charm.

Loosely based on OpenStack's oslo-incubator:

    https://github.com/openstack/oslo-incubator.git

Allows specifying a list of dependencies to sync in from a charm-helpers
branch.  Ideally, each charm should describe its requirements in a yaml
config included in the charm, eg charm-helpers.yaml (NOTE: Example module
layout as of 05/30/2013):

    $ cd my-charm
    $ cat >charm-helpers.yaml <<END
    destination: hooks/helpers
    branch: lp:charm-helpers
    include:
        - core
        - contrib.openstack
        - contrib.hahelpers:
            - ceph_utils
    END

includes may be defined as entire module sub-directories, or as invidual
.py files with in a module sub-directory.

Charm author can then sync in and update helpers as needed.  The following
import all of charmhelpers.core + charmhelpers.contrib.openstack, and only
ceph_utils.py from charmhelpers.contrib.hahelpers:

    $ charm-helper-sync -c charm-helpers.yaml
    $ find hooks/helpers/
    hooks/helpers/
    hooks/helpers/contrib
    hooks/helpers/contrib/openstack
    hooks/helpers/contrib/openstack/openstack_utils.py
    hooks/helpers/contrib/openstack/__init__.py
    hooks/helpers/contrib/hahelpers
    hooks/helpers/contrib/hahelpers/ceph_utils.py
    hooks/helpers/contrib/hahelpers/__init__.py
    hooks/helpers/contrib/__init__.py
    hooks/helpers/core
    hooks/helpers/core/hookenv.py
    hooks/helpers/core/host.py
    hooks/helpers/core/__init__.py
    hooks/helpers/__init__.py


Script will create missing __init__.py's to ensure each subdirectory is
importable, assuming the script is run from the charm's top-level directory.

By default, only directories that look like python modules and associated
.py source files will be synced.  If you need to include other files in
the sync (for example, template files), you can add include hints to
your config.  This can be done either on a per-module basis using standard
UNIX filename patterns, eg:

    destination: hooks/helpers
    branch: lp:charm-helpers
    include:
        - core|inc=* # include all extra files from this module.
        - contrib.openstack|inc=*.template # include only .template's
        - contrib.hahelpers:
            - ceph_utils|inc=*.cfg # include .cfg files

Or globally for all included assets:

    destination: hooks/helpers
    branch: lp:charm-helpers
    options: inc=*.template,inc=*.cfg # include .templates and .cfgs globally
    include:
        - core
        - contrib.openstack
        - contrib.hahelpers:
            - ceph_utils

You may also override configured destination directory and source bzr
branch:

    $ charm-helper-sync -b ~/src/bzr/charm-helpers-dev \
            -d hooks/helpers-test \
            -c charm-helpers.yaml

Or not use a config file at all:
    $ charm-helper-sync -b lp:~gandelman-a/charm-helpers/fixes \
            -d hooks/helpers core contrib.openstack contrib.hahelpers

Script will create missing __init__.py's to ensure each subdirectory is
importable, assuming the script is run from the charm's top-level directory.