+++ /dev/null
-# Overview
-
-This is the base layer for all charms [built using layers][building]. It
-provides all of the standard Juju hooks and runs the
-[charms.reactive.main][charms.reactive] loop for them. It also bootstraps the
-[charm-helpers][] and [charms.reactive][] libraries and all of their
-dependencies for use by the charm.
-
-# Usage
-
-To create a charm layer using this base layer, you need only include it in
-a `layer.yaml` file:
-
-```yaml
-includes: ['layer:basic']
-```
-
-This will fetch this layer from [interfaces.juju.solutions][] and incorporate
-it into your charm layer. You can then add handlers under the `reactive/`
-directory. Note that **any** file under `reactive/` will be expected to
-contain handlers, whether as Python decorated functions or [executables][non-python]
-using the [external handler protocol][].
-
-### Charm Dependencies
-
-Each layer can include a `wheelhouse.txt` file with Python requirement lines.
-For example, this layer's `wheelhouse.txt` includes:
-
-```
-pip>=7.0.0,<8.0.0
-charmhelpers>=0.4.0,<1.0.0
-charms.reactive>=0.1.0,<2.0.0
-```
-
-All of these dependencies from each layer will be fetched (and updated) at build
-time and will be automatically installed by this base layer before any reactive
-handlers are run.
-
-Note that the `wheelhouse.txt` file is intended for **charm** dependencies only.
-That is, for libraries that the charm code itself needs to do its job of deploying
-and configuring the payload. If the payload itself has Python dependencies, those
-should be handled separately, by the charm.
-
-See [PyPI][pypi charms.X] for packages under the `charms.` namespace which might
-be useful for your charm.
-
-### Layer Namespace
-
-Each layer has a reserved section in the `charms.layer.` Python package namespace,
-which it can populate by including a `lib/charms/layer/<layer-name>.py` file or
-by placing files under `lib/charms/layer/<layer-name>/`. (If the layer name
-includes hyphens, replace them with underscores.) These can be helpers that the
-layer uses internally, or it can expose classes or functions to be used by other
-layers to interact with that layer.
-
-For example, a layer named `foo` could include a `lib/charms/layer/foo.py` file
-with some helper functions that other layers could access using:
-
-```python
-from charms.layer.foo import my_helper
-```
-
-### Layer Options
-
-Any layer can define options in its `layer.yaml`. Those options can then be set
-by other layers to change the behavior of your layer. The options are defined
-using [jsonschema][], which is the same way that [action paramters][] are defined.
-
-For example, the `foo` layer could include the following option definitons:
-
-```yaml
-includes: ['layer:basic']
-defines: # define some options for this layer (the layer "foo")
- enable-bar: # define an "enable-bar" option for this layer
- description: If true, enable support for "bar".
- type: boolean
- default: false
-```
-
-A layer using `foo` could then set it:
-
-```yaml
-includes: ['layer:foo']
-options:
- foo: # setting options for the "foo" layer
- enable-bar: true # set the "enable-bar" option to true
-```
-
-The `foo` layer can then use the `charms.layer.options` helper to load the values
-for the options that it defined. For example:
-
-```python
-from charms import layer
-
-@when('state')
-def do_thing():
- layer_opts = layer.options('foo') # load all of the options for the "foo" layer
- if layer_opts['enable-bar']: # check the value of the "enable-bar" option
- hookenv.log("Bar is enabled")
-```
-
-You can also access layer options in other handlers, such as Bash, using
-the command-line interface:
-
-```bash
-. charms.reactive.sh
-
-@when 'state'
-function do_thing() {
- if layer_option foo enable-bar; then
- juju-log "Bar is enabled"
- juju-log "bar-value is: $(layer_option foo bar-value)"
- fi
-}
-
-reactive_handler_main
-```
-
-Note that options of type `boolean` will set the exit code, while other types
-will be printed out.
-
-# Hooks
-
-This layer provides hooks that other layers can react to using the decorators
-of the [charms.reactive][] library:
-
- * `config-changed`
- * `install`
- * `leader-elected`
- * `leader-settings-changed`
- * `start`
- * `stop`
- * `upgrade-charm`
- * `update-status`
-
-Other hooks are not implemented at this time. A new layer can implement storage
-or relation hooks in their own layer by putting them in the `hooks` directory.
-
-**Note:** Because `update-status` is invoked every 5 minutes, you should take
-care to ensure that your reactive handlers only invoke expensive operations
-when absolutely necessary. It is recommended that you use helpers like
-[`@only_once`][], [`@when_file_changed`][], and [`data_changed`][] to ensure
-that handlers run only when necessary.
-
-# Layer Configuration
-
-This layer supports the following options, which can be set in `layer.yaml`:
-
- * **packages** A list of system packages to be installed before the reactive
- handlers are invoked.
-
- * **use_venv** If set to true, the charm dependencies from the various
- layers' `wheelhouse.txt` files will be installed in a Python virtualenv
- located at `$CHARM_DIR/../.venv`. This keeps charm dependencies from
- conflicting with payload dependencies, but you must take care to preserve
- the environment and interpreter if using `execl` or `subprocess`.
-
- * **include_system_packages** If set to true and using a venv, include
- the `--system-site-packages` options to make system Python libraries
- visible within the venv.
-
-An example `layer.yaml` using these options might be:
-
-```yaml
-includes: ['layer:basic']
-options:
- basic:
- packages: ['git']
- use_venv: true
- include_system_packages: true
-```
-
-
-# Reactive States
-
-This layer will set the following states:
-
- * **`config.changed`** Any config option has changed from its previous value.
- This state is cleared automatically at the end of each hook invocation.
-
- * **`config.changed.<option>`** A specific config option has changed.
- **`<option>`** will be replaced by the config option name from `config.yaml`.
- This state is cleared automatically at the end of each hook invocation.
-
- * **`config.set.<option>`** A specific config option has a True or non-empty
- value set. **`<option>`** will be replaced by the config option name from
- `config.yaml`. This state is cleared automatically at the end of each hook
- invocation.
-
- * **`config.default.<option>`** A specific config option is set to its
- default value. **`<option>`** will be replaced by the config option name
- from `config.yaml`. This state is cleared automatically at the end of
- each hook invocation.
-
-An example using the config states would be:
-
-```python
-@when('config.changed.my-opt')
-def my_opt_changed():
- update_config()
- restart_service()
-```
-
-
-# Actions
-
-This layer currently does not define any actions.
-
-
-[building]: https://jujucharms.com/docs/devel/authors-charm-building
-[charm-helpers]: https://pythonhosted.org/charmhelpers/
-[charms.reactive]: https://pythonhosted.org/charms.reactive/
-[interfaces.juju.solutions]: http://interfaces.juju.solutions/
-[non-python]: https://pythonhosted.org/charms.reactive/#non-python-reactive-handlers
-[external handler protocol]: https://pythonhosted.org/charms.reactive/charms.reactive.bus.html#charms.reactive.bus.ExternalHandler
-[jsonschema]: http://json-schema.org/
-[action paramters]: https://jujucharms.com/docs/stable/authors-charm-actions
-[pypi charms.X]: https://pypi.python.org/pypi?%3Aaction=search&term=charms.&submit=search
-[`@only_once`]: https://pythonhosted.org/charms.reactive/charms.reactive.decorators.html#charms.reactive.decorators.only_once
-[`@when_file_changed`]: https://pythonhosted.org/charms.reactive/charms.reactive.decorators.html#charms.reactive.decorators.when_file_changed
-[`data_changed`]: https://pythonhosted.org/charms.reactive/charms.reactive.helpers.html#charms.reactive.helpers.data_changed
projects / osm / devops.git / blobdiff