github.com/dahs81/otto@v0.2.1-0.20160126165905-6400716cf085/website/source/docs/plugins/scriptpack.html.md (about)

     1  ---
     2  layout: "docs"
     3  page_title: "ScriptPacks- Appfile"
     4  sidebar_current: "docs-plugins-scriptpack"
     5  description: |-
     6    ScriptPacks are libraries of shell functions to run with application
     7    types and other Otto plugins.
     8  ---
     9  
    10  # ScriptPacks
    11  
    12  ScriptPacks are fully self-contained shell scripting libraries that
    13  other plugins such as [application types](/docs/plugins/app.html)
    14  use to perform logic on guest machines.
    15  
    16  The idea is that all Otto functionality that happens on a user's machine
    17  should be written in Go, and all functionality that happens on a remote
    18  machine (dev, deploy, etc.) should be implemented by calling ScriptPack
    19  functions.
    20  
    21  ScriptPacks are tested in isolation, enabling you to unit test specific
    22  functionality without a long feedback loop. Furthermore, ScriptPacks
    23  encourage reusability of functionality across Otto plugins.
    24  
    25  ~> **Advanced topic!** Plugin development is a highly advanced topic in
    26     Otto, and is not required knowledge for day-to-day usage. If you don't plan
    27     on writing any plugins, we recommend not reading this section of the
    28     documentation.
    29  
    30  If you're interested in ScriptPack development and usage, then read on. The
    31  remainder of this page will assume you're familiar with
    32  [plugin basics](/docs/plugins/basics.html)
    33  and that you already have a basic development environment setup.
    34  
    35  ## Skeleton
    36  
    37  A basic skeleton for writing a new ScriptPack can be
    38  [found in the Otto repository](https://github.com/hashicorp/otto/tree/master/builtin/scriptpack/skeleton). This is a fully functioning example that any new ScriptPacks
    39  can be based off of. For a real example, see any ScriptPacks within the
    40  Otto repository.
    41  
    42  The basic ScriptPack folder structure contains:
    43  
    44    * **Go files:** We use Go as an API to work with ScriptPacks from
    45      Go. The shell files within the data directory do not require Go, however.
    46      These Go files let you use the ScriptPack as a Go library from your
    47      other Otto plugins.
    48  
    49    * **`data` directory:** This contains a set of shell scripts that contain
    50      all the functionality of the ScriptPack. This directory will be available
    51      at the env var `SCRIPTPACK_NAME_ROOT` where `NAME` is the name of the
    52      ScriptPack.
    53  
    54    * **`test` directory:** This contains
    55      [BATS](https://github.com/sstephenson/bats) tests for the various
    56      functions within the `data` directory. You can easily run these tests
    57      by using Otto itself (covered below).
    58  
    59  ## Developing ScriptPacks
    60  
    61  ScriptPacks are developed using Otto itself. Otto has a
    62  [scriptpack app type](/docs/apps/scriptpack). This app type introduces
    63  CLI commands for easily interacting with ScriptPacks.
    64  
    65  Bring up a ScriptPack dev environment with `otto dev`. This will start
    66  a VM that is used for testing ScriptPacks. Next, use `otto dev scriptpack-test`
    67  to test your ScriptPack:
    68  
    69      $ otto dev scriptpack-test test/foo.bats
    70      ...
    71  
    72  This will use a container to isolate the test file and test your ScriptPack. By
    73  using containers, we can run the tests on "clean" systems to test a variety
    74  of cases quickly.
    75  
    76  The Otto workflow enables a fast feedback cycle on potentially complex
    77  shell functionality. This enables plugin developers to more quickly develop
    78  complex [app type plugins](/docs/plugins/app.html).
    79  
    80  ## Dependencies
    81  
    82  ScriptPacks can depend on other ScriptPacks. Within `main.go`, you can
    83  see the skeleton ScriptPack depends on "stdlib":
    84  
    85      var ScriptPack = scriptpack.ScriptPack{
    86          ...
    87          Dependencies: []*scriptpack.ScriptPack{
    88              &stdlib.ScriptPack,
    89          },
    90      }
    91  
    92  
    93  As you can see, dependencies are done using Go directly. By using Go,
    94  the dependency is "locked" to exactly the contents of the ScriptPack at
    95  compile-time. For each dependent scriptpack, an environment variable
    96  becomes available to access its data. For example, for the dependency above,
    97  `SCRIPTPACK_STDLIB_ROOT` can be used to get the path to the root of that
    98  dependency.
    99  
   100  ## Using ScriptPacks
   101  
   102  To use a ScriptPack, see the [app type plugins](/docs/plugins/app.html)
   103  page. App type plugins have a higher level API to make using ScriptPacks
   104  easier within Otto.
   105  
   106  ScriptPacks can also be used directly with the
   107  [scriptpack package API](https://github.com/hashicorp/otto/tree/master/scriptpack).
   108  This is a fairly low level API that you shouldn't need to use directly
   109  for Otto plugins, but if you want to use ScriptPacks outside of Otto you
   110  may need it.