Writing a hook

We'll start with an example of a config-changed hook and break down the code piece by piece

  #!/usr/bin/env perl
  BEGIN {
      # Install charmkit
      system "qpt-get install -qyf cpanminus";
      system "cpanm -qn App::Charmkit";
  }

  use charm;

use charm is the entrypoint to exposing charm routines useful for deploying the service. This provides facilities such as installing packages, printing logs, getting relation information, and configuring service level options.

  my $port = sh 'config-get port';

config routine will pull config options defined in config.yaml.

  # close existing bitlbee port

  ( my $output = qq{BITLBEE_PORT=$port
  BITLBEE_OPTS="-F"
  BITLBEE_DISABLED=0
  BITLBEE_UPGRADE_DONT_RESTART=0
  } );

  file "/etc/default/bitlebee", content => $output;

  service 'bitlbee' => 'restart';

service is another helper for start/stopping services on the system where the charm is placed.

  sh "open-port $port";

open_port exposes a port accessible publicly, and its opposite close_port will remove that accessibility.

Adding custom libraries

There are cases where you want to write reusable subroutines to be used throughout your charm hooks. charmkit will automatically search in your toplevel project searching for a lib directory. Similar to how you write Perl modules.

For example, your directory structure

The structure of your project should look similar to:

  charm-project/
    hooks/
      install
      config-changed
      start
      stop
      upgrade-charm
    tests/              # Functional
      00-basic.test
    lib/                # Add lib to toplevel charm directory
      bitlbee.pm
    t/                  # Unit
      01-test-bitlbee.t
    config.yaml
    metadata.yaml
    LICENSE
    README.md

Now in your hook file you can just call:

  #!/usr/bin/env perl
  use charm;

  plugin 'bitlbee';
  $bb->syntax_check_config;