osm.etsi.org Git - osm/riftware.git/blob

   1 # Overview
   2
   3 This is the base layer for all charms [built using layers][building].  It
   4 provides all of the standard Juju hooks and runs the
   5 [charms.reactive.main][charms.reactive] loop for them.  It also bootstraps the
   6 [charm-helpers][] and [charms.reactive][] libraries and all of their
   7 dependencies for use by the charm.
   8
   9 # Usage
  10
  11 To create a charm layer using this base layer, you need only include it in
  12 a `layer.yaml` file:
  13
  14 ```yaml
  15 includes: ['layer:basic']
  16 ```
  17
  18 This will fetch this layer from [interfaces.juju.solutions][] and incorporate
  19 it into your charm layer.  You can then add handlers under the `reactive/`
  20 directory.  Note that **any** file under `reactive/` will be expected to
  21 contain handlers, whether as Python decorated functions or [executables][non-python]
  22 using the [external handler protocol][].
  23
  24 You can also define Python libraries under `lib/charms/X` where `X` is a
  25 package under the `charms.` namespace for your charm.  See [PyPI][pypi charms.X]
  26 for what packages already exist under the `charms.` namespace.
  27
  28 # Hooks
  29
  30 This layer provides hooks that other layers can react to using the decorators
  31 of the [charms.reactive][] library:
  32
  33   * `config-changed`
  34   * `install`
  35   * `leader-elected`
  36   * `leader-settings-changed`
  37   * `start`
  38   * `stop`
  39   * `upgrade-charm`
  40   * `update-status`
  41
  42 Other hooks are not implemented at this time. A new layer can implement storage
  43 or relation hooks in their own layer by putting them in the `hooks` directory.
  44
  45 **Note:** Because `update-status` is invoked every 5 minutes, you should take
  46 care to ensure that your reactive handlers only invoke expensive operations
  47 when absolutely necessary.  It is recommended that you use helpers like
  48 [`@only_once`][], [`@when_file_changed`][], and [`data_changed`][] to ensure
  49 that handlers run only when necessary.
  50
  51 # Layer Configuration
  52
  53 This layer does not currently support any configuration.
  54
  55
  56 # Reactive States
  57
  58 This layer currently does not set any reactive states.
  59
  60
  61 # Actions
  62
  63 This layer currently does not define any actions.
  64
  65
  66 [building]: https://jujucharms.com/docs/devel/authors-charm-building
  67 [charm-helpers]: https://pythonhosted.org/charmhelpers/
  68 [charms.reactive]: https://pythonhosted.org/charms.reactive/
  69 [interfaces.juju.solutions]: http://interfaces.juju.solutions/
  70 [non-python]: https://pythonhosted.org/charms.reactive/#non-python-reactive-handlers
  71 [external handler protocol]: https://pythonhosted.org/charms.reactive/charms.reactive.bus.html#charms.reactive.bus.ExternalHandler
  72 [pypi charms.X]: https://pypi.python.org/pypi?%3Aaction=search&term=charms.&submit=search
  73 [`@only_once`]: https://pythonhosted.org/charms.reactive/charms.reactive.decorators.html#charms.reactive.decorators.only_once
  74 [`@when_file_changed`]: https://pythonhosted.org/charms.reactive/charms.reactive.decorators.html#charms.reactive.decorators.when_file_changed
  75 [`data_changed`]: https://pythonhosted.org/charms.reactive/charms.reactive.helpers.html#charms.reactive.helpers.data_changed