<commit_before>---
title: Creating Habitat plans
---

# Create plans
At the center of Habitat packaging is the plan. This is a folder comprised of shell scripts and optional configuration files that define how you download, configure, make, install, and manage the lifecycle of the software in the package.

As a way to start to understand plans, let's look at an example `plan.sh` for [zlib](http://www.zlib.net/):

~~~ bash
pkg_name=zlib
pkg_distname=$pkg_name
pkg_origin=core
pkg_version=1.2.8
pkg_maintainer="The Habitat Maintainers <<EMAIL>>"
pkg_license=('zlib')
pkg_source=http://zlib.net/current/${pkg_distname}-${pkg_version}.tar.gz
pkg_shasum=36658cb768a54c1d4dec43c3116c27ed893e88b02ecfcb44f2166f9c0b7f2a0d
pkg_dirname=${pkg_distname}-${pkg_version}
pkg_deps=(core/glibc)
pkg_build_deps=(core/coreutils core/diffutils core/patch core/make core/gcc)
pkg_lib_dirs=(lib)
pkg_include_dirs=(include)
~~~

It has the name of the software, the version, where to download it,
a checksum to verify the contents are what we expect, a single run dependency on `core/glibc`, build dependencies on `core/coreutils`, `core/diffutils`, `core/patch`, `core/make`, `core/gcc`, and it has the resulting libraries in `lib` and header files in `include`.

When you have finished creating your plan and call `build` in Habitat studio, the following occurs:

1.  The build script ensures that the origin key is available to sign the package.
2.  The software is downloaded.
3.  The checksum is validated.
4.  The source is extracted from the archive file that the script downloaded in step two.
5.  The build environment is set to depend on the `glibc` Habitat package.
6.  The callback methods are run with their default implementations.
7.  Data is written that allows other packages to take a dependency on `zlib`.
8.  A signed tarball of the `zlib` package is created.

The plan.sh file is the only required file to create a package. Configuration files, runtime hooks, and other source files are optional.

## Set up the environment
<%= partial "/shared/setup_environment" %>

## Write a plan
To create a plan, do the following:

1. In a terminal window, create a new directory for your plan. This directory is known as the plan context.

2. All plans must have a `plan.sh` at the root of the plan context. This file will be used by the hab-plan-build command to build your package, so create a plan.sh file in your plan context and open it.

       $EDITOR plan.sh

3. Copy the following template into plan.sh. You can use it as a skeleton template when writing new plans.

~~~ bash
pkg_origin=
pkg_name=
pkg_version=
pkg_maintainer="<NAME> <your email address>"
pkg_license=()
pkg_source=http://example.com/${pkg_name}-${pkg_version}.tar.xz
pkg_shasum=sha256sum
pkg_deps=()
pkg_build_deps=()
pkg_bin_dirs=(bin)
pkg_include_dirs=(include)
pkg_lib_dirs=(lib)
~~~

When writing a plan, it's important to understand that you are defining both how the package is built and how the Habitat service will behave when the supervisor starts and manages the child process in the package. The following sections explain what you need to do for each phase.

### Buildtime workflow
For buildtime installation and configuration, workflow steps need to be included in the plan.sh file. This script defines how you will install your application source files into a package. Before writing your plan, you should know and understand how your application binaries are currently built, installed, what their dependencies are, and where your application or software library expects to find those dependencies.

The main steps in the buildtime workflow are the following:

1. Create your fully-qualified package identifier.
2. Add licensing and contact information.
3. Download and unpack your source files.
4. Define your dependencies.
5. (Optional) Override any callbacks.

The following sections describe each of these steps in more detail.

#### Create your package identifier
The origin defines packages that are conceptually related to each other. For example, the "core" origin packages are foundational to building other packages. If you would like to browse them, they are located in the [plans directory](https://github.com/habitat-sh/habitat/tree/master/plans) of the Habitat repo.

> Note: The "core" origin name is reserved for members of the Habitat maintainers group.

Creating packages for a specific origin requires that you also have access to the secret key for that origin. The secret key will be used to sign the package when it is built by the hab-plan-build command. Keys are kept in `$HOME/.hab/cache/keys` on the host machine and `/hab/cache/keys` while in the studio. For more information on keys, see [Keys](/docs/concepts-keys).

The next important part of your package identifier is the name of the package. Standard naming convention is to base the name of the package off of the name of the source or project you download and install into the package; however, this is not a requirement.

Finally, the version number can align to any versioning format you wish. Similar to the package name, the version of the package typically follows the same version and format as the source or project you are packaging. For example, if you created a package for version 1.2.4 of an application, then you would also use that same version number and format for the `pkg_version` value in your package.

#### Add licensing and contact information
While not strictly required, you should enter your contact information in your plan.<commit_msg>Updated plan example and fixed link to core plans repo.<commit_after>---
title: Creating Habitat plans
---

# Create plans
At the center of Habitat packaging is the plan. This is a folder comprised of shell scripts and optional configuration files that define how you download, configure, make, install, and manage the lifecycle of the software in the package.

As a way to start to understand plans, let's look at an example `plan.sh` for [zlib](http://www.zlib.net/):

~~~ bash
pkg_name=zlib
pkg_description="The zlib library"
pkg_upstream_url=http://zlib.net
pkg_origin=core
pkg_version=1.2.8
pkg_maintainer="The Habitat Maintainers <<EMAIL>>"
pkg_license=('zlib')
pkg_source=http://downloads.sourceforge.net/project/libpng/$pkg_name/${pkg_version}/${pkg_name}-${pkg_version}.tar.gz
pkg_shasum=36658cb768a54c1d4dec43c3116c27ed893e88b02ecfcb44f2166f9c0b7f2a0d
pkg_dirname=${pkg_name}-${pkg_version}
pkg_deps=(core/glibc)
pkg_build_deps=(core/coreutils core/diffutils core/patch core/make core/gcc)
pkg_lib_dirs=(lib)
pkg_include_dirs=(include)
~~~

It has the name of the software, the version, where to download it, a checksum to verify the contents are what we expect, a single run dependency on 
`core/glibc`, build dependencies on `core/coreutils`, `core/diffutils`, `core/patch`, `core/make`, `core/gcc`, and it has the resulting libraries in `lib` 
and header files in `include`. Also, because it's a core plan, it has a description and upstream URL for the source project included.

When you have finished creating your plan and call `build` in Habitat studio, the following occurs:

1.  The build script ensures that the origin key is available to sign the package.
2.  The software is downloaded.
3.  The checksum is validated.
4.  The source is extracted from the archive file that the script downloaded in step two.
5.  The build environment is set to depend on the `glibc` Habitat package.
6.  The callback methods are run with their default implementations.
7.  Data is written that allows other packages to take a dependency on `zlib`.
8.  A signed tarball of the `zlib` package is created.

The plan.sh file is the only required file to create a package. Configuration files, runtime hooks, and other source files are optional.

## Set up the environment
<%= partial "/shared/setup_environment" %>

## Write a plan
To create a plan, do the following:

1. In a terminal window, create a new directory for your plan. This directory is known as the plan context.

2. All plans must have a `plan.sh` at the root of the plan context. This file will be used by the hab-plan-build command to build your package, so create a plan.sh file in your plan context and open it.

       $EDITOR plan.sh

3. Copy the following template into plan.sh. You can use it as a skeleton template when writing new plans.

~~~ bash
pkg_origin=
pkg_name=
pkg_version=
pkg_maintainer="<NAME> <your email address>"
pkg_license=()
pkg_source=http://example.com/${pkg_name}-${pkg_version}.tar.xz
pkg_shasum=sha256sum
pkg_deps=()
pkg_build_deps=()
pkg_bin_dirs=(bin)
pkg_include_dirs=(include)
pkg_lib_dirs=(lib)
~~~

When writing a plan, it's important to understand that you are defining both how the package is built and how the Habitat service will behave when the supervisor starts and manages the child process in the package. The following sections explain what you need to do for each phase.

### Buildtime workflow
For buildtime installation and configuration, workflow steps need to be included in the plan.sh file. This script defines how you will install your application source files into a package. Before writing your plan, you should know and understand how your application binaries are currently built, installed, what their dependencies are, and where your application or software library expects to find those dependencies.

The main steps in the buildtime workflow are the following:

1. Create your fully-qualified package identifier.
2. Add licensing and contact information.
3. Download and unpack your source files.
4. Define your dependencies.
5. (Optional) Override any callbacks.

The following sections describe each of these steps in more detail.

#### Create your package identifier
The origin defines packages that are conceptually related to each other. For example, the "core" origin packages are foundational to building other packages. If you would like to browse them, they are located in the [core-plans repo](https://github.com/habitat-sh/core-plans).

> Note: The "core" origin name is reserved for the foundational library and binary packages owned by the Habitat maintainers group.

Creating packages for a specific origin requires that you also have access to the secret key for that origin. The secret key will be used to sign the package when it is built by the hab-plan-build command. Keys are kept in `$HOME/.hab/cache/keys` on the host machine and `/hab/cache/keys` while in the studio. For more information on keys, see [Keys](/docs/concepts-keys).

The next important part of your package identifier is the name of the package. Standard naming convention is to base the name of the package off of the name of the source or project you download and install into the package; however, this is not a requirement.

Finally, the version number can align to any versioning format you wish. Similar to the package name, the version of the package typically follows the same version and format as the source or project you are packaging. For example, if you created a package for version 1.2.4 of an application, then you would also use that same version number and format for the `pkg_version` value in your package.

#### Add licensing and contact information
While not strictly required, you should enter your contact information in your plan.
{'fraction_non_alphanumeric': 0.06492702344095533, 'fraction_numerical': 0.011145510835913313, 'mean_word_length': 4.6842634489693316, 'pattern_counts': {'":': 0, '<': 13, '<?xml version=': 0, '>': 15, 'https://': 2, 'lorem ipsum': 0, 'www.': 2, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 13, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '4879471', 'n_tokens_mistral': 3069, 'n_tokens_neox': 2951, 'n_words': 1599}