=head1 Writing a hook

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

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

C<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.

  log "Start of charm authoring for config-changed";

The C<log> facility uses C<juju-log> as the utility for logging what's happening
in your charm.

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

C<config-get> routine will pull config options defined in F<config.yaml>.

  # close existing bitlbee port

  log "Opening port for bitlbee";

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

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

C<path> is exposed from L<Path::Tiny> so anything that applies to that module works
the same here.

  service 'bitlbee' => 'restart';

C<service_control> is another helper for start/stopping services on the system
where the charm is placed.

  run "open-port $port";

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

=head1 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 B<lib> directory. Similar to how you write Perl modules.

For example, your directory structure

The structure your project should look similar to:

  charm-project/
    hooks/
      install
      config-changed
      start
      stop
      upgrade-charm
    tests/
      00-basic.test
    lib/                # Add lib to toplevel charm directory
      bitlbee.pm
    t/
      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;
  use bitlbee;

  my $bb = bitlbee->new;
  $bb->syntax_check_config;

=cut
