Project: Chef Habitat (App Definition and Development / Application Definition & Image Build)
File: plan_settings.md

+++ title = "Plan Settings" description = "Define basic metadata about your artifact with plan settings" gh_repo = "habitat" [menu] [menu.habitat] title = "Plan Settings" identifier = "habitat/reference/plan-settings" parent = "habitat/reference" +++ Habitat reserves some names for internal use. You can set all of these values in your plan and use them as variables in your Habitat code. For example: ```bash plan.sh pkg_name=two-tier-app ${pkg_name} ``` ```powershell plan.ps1 pkg_name=two-tier-app ${"pkg_name"} ``` FORMAT: setting : Short definition. How to use. How habitat uses. If required other settings. Type: String, array, boolean,etc. Default: if any. Optional/Required pkg_name : Sets the name of the package. Can contain upper and lowercase letters, numbers, dashes, and underscores. By default, Chef Habitat uses `pkgname`, `pkgorigin`, and `pkgversion` to create the fully-qualified package name. Type: string. Required_. {{< foundation_tabs tabs-id="bash-powershell-panel" >}} {{< foundation_tab active="true" panel-link="bash-panel" tab-text="Bash">}} {{< foundation_tab panel-link="powershell-panel" tab-text="Powershell" >}} {{< /foundation_tabs >}} {{< foundationtabspanels tabs-id="bash-powershell-panel" >}} {{< foundationtabspanel active="true" panel-id="bash-panel" >}} ```bash pkg_name=zlib ``` {{< /foundationtabspanel >}} {{< foundationtabspanel panel-id="powershell-panel" >}} ```powershell $pkg_name="zlib" ``` {{< /foundationtabspanel >}} {{< /foundationtabspanels >}} pkg_origin : The name of the origin for this package. Can contain upper and lowercase letters, numbers, dashes, and underscores. The `HABORIGIN` environment variable overrides the `pkgorigin` Type: string. Required. {{< foundation_tabs tabs-id="bash-powershell-panel1" >}} {{< foundation_tab active="true" panel-link="bash-panel1" tab-text="Bash">}} {{< foundation_tab panel-link="powershell-panel1" tab-text="Powershell" >}} {{< /foundation_tabs >}} {{< foundationtabspanels tabs-id="bash-powershell-panel1" >}} {{< foundationtabspanel active="true" panel-id="bash-panel1" >}} ```bash pkg_origin=Habitat ``` {{< /foundationtabspanel >}} {{< foundationtabspanel panel-id="powershell-panel1" >}} ```powershell $pkg_origin="Habitat" ``` {{< /foundationtabspanel >}} {{< /foundationtabspanels >}} pkg_version : Sets the version of the package By default, Chef Habitat uses `pkgname`, `pkgorigin`, and `pkgversion` to create the fully-qualified package name. You can set the value through the `pkgversion()` function. Type: string. Required. {{< foundation_tabs tabs-id="bash-powershell-panel2" >}} {{< foundation_tab active="true" panel-link="bash-panel2" tab-text="Bash">}} {{< foundation_tab panel-link="powershell-panel2" tab-text="Powershell" >}} {{< /foundation_tabs >}} {{< foundationtabspanels tabs-id="bash-powershell-panel2" >}} {{< foundationtabspanel active="true" panel-id="bash-panel2" >}} ```bash pkg_version=1.2.8 ``` {{< /foundationtabspanel >}} {{< foundationtabspanel panel-id="powershell-panel2" >}} ```powershell $pkg_version="1.2.8" ``` {{< /foundationtabspanel >}} {{< /foundationtabspanels >}} {{< note >}} Habitat uses the guidelines of the semantic versioning specification to determine version order (see <https://semver.org/>). Keep in mind that including a hyphen in your version indicates that the package is a pre-release that will be given lower precedence to other versions. {{< /note >}} pkg_maintainer : The name and email address of the package maintainer. Type: string.Optional. {{< foundation_tabs tabs-id="bash-powershell-panel3" >}} {{< foundation_tab active="true" panel-link="bash-panel3" tab-text="Bash">}} {{< foundation_tab panel-link="powershell-panel3" tab-text="Powershell" >}} {{< /foundation_tabs >}} {{< foundationtabspanels tabs-id="bash-powershell-panel3" >}} {{< foundationtabspanel active="true" panel-id="bash-panel3" >}} ```bash pkg_maintainer="Your Name <someone@example.com>" ``` {{< /foundationtabspanel >}} {{< foundationtabspanel panel-id="powershell-panel3" >}} ```powershell $pkg_maintainer="Your Name <someone@example.com>" ``` {{< /foundationtabspanel >}} {{< /foundationtabspanels >}} pkg_license : One or more that relate to this package. Type: array. Optional. {{< foundation_tabs tabs-id="bash-powershell-panel4" >}} {{< foundation_tab active="true" panel-link="bash-panel4" tab-text="Bash">}} {{< foundation_tab panel-link="powershell-panel4" tab-text="Powershell" >}} {{< /foundation_tabs >}} {{< foundationtabspanels tabs-id="bash-powershell-panel4" >}} {{< foundationtabspanel active="true" panel-id="bash-panel4" >}} ```bash pkg_license=('Apache-2.0') ``` {{< /foundationtabspanel >}} {{< foundationtabspanel panel-id="powershell-panel4" >}} ```powershell $pkg_license=("'Apache-2.0'") ``` {{< /foundationtabspanel >}} {{< /foundationtabspanels >}} {{< note >}} If your package has a custom license, use a string literal matching the title of the license. For example, you'll see `pkg_license=('Boost Software License')` for the `cmake` plan. {{< /note >}} pkg_source : A URL that specifies the location from which to download an external source. Any valid `wget` url will work. Typically, the relative path for the URL typically contains the `pkgname` and `pkgversion`

Type: URL. Optional. {{< foundation_tabs tabs-id="bash-powershell-panel5" >}} {{< foundation_tab active="true" panel-link="bash-panel5" tab-text="Bash">}} {{< foundation_tab panel-link="powershell-panel5" tab-text="Powershell" >}} {{< /foundation_tabs >}} {{< foundationtabspanels tabs-id="bash-powershell-panel5" >}} {{< foundationtabspanel active="true" panel-id="bash-panel5" >}} ```bash pkgsource=http://downloads.sourceforge.net/project/libpng/$pkgname/${pkgversion}/${pkgname}-${pkg_version}.tar.gz ``` {{< /foundationtabspanel >}} {{< foundationtabspanel panel-id="powershell-panel5" >}} ```powershell $pkgsource="http://downloads.sourceforge.net/project/libpng/$pkgname/${pkgversion}/${pkgname}-${pkg_version}.tar.gz" ``` {{< /foundationtabspanel >}} {{< /foundationtabspanels >}} pkg_filename : The filename for the finished artifact. By default, Chef Habitat ] constructs this from `pkgname` and `pkgversion`. Type: string. Optional. {{< foundation_tabs tabs-id="bash-powershell-panel6" >}} {{< foundation_tab active="true" panel-link="bash-panel6" tab-text="Bash">}} {{< foundation_tab panel-link="powershell-panel6" tab-text="Powershell" >}} {{< /foundation_tabs >}} {{< foundationtabspanels tabs-id="bash-powershell-panel6" >}} {{< foundationtabspanel active="true" panel-id="bash-panel6" >}} ```bash pkgfilename=${pkgname}-${pkg_version}.tar.gz ``` {{< /foundationtabspanel >}} {{< foundationtabspanel panel-id="powershell-panel6" >}} ```powershell $pkgfilename="${pkgname}-${pkg_version}.tar.gz" ``` {{< /foundationtabspanel >}} {{< /foundationtabspanels >}} pkg_shasum : The sha-256 sum of the downloaded `pkgsource`. If you do not have the checksum, generate it by downloading the source and using the `sha256sum` or `gsha256sum` tools. Override with `doverify()`. When the value is unset or incorrect and you do not override it with `doverify()`, then the build output of your package will show the expected value. Type: varchar(64) or char(64). Required when providing a valid URL is provided for `pkgsource`, but is otherwise Optional. {{< foundation_tabs tabs-id="bash-powershell-panel7" >}} {{< foundation_tab active="true" panel-link="bash-panel7" tab-text="Bash">}} {{< foundation_tab panel-link="powershell-panel7" tab-text="Powershell" >}} {{< /foundation_tabs >}} {{< foundationtabspanels tabs-id="bash-powershell-panel7" >}} {{< foundationtabspanel active="true" panel-id="bash-panel7" >}} ```bash pkg_shasum=36658cb768a54c1d4dec43c3116c27ed893e88b02ecfcb44f2166f9c0b7f2a0d ``` {{< /foundationtabspanel >}} {{< foundationtabspanel panel-id="powershell-panel7" >}} ```powershell $pkg_shasum="36658cb768a54c1d4dec43c3116c27ed893e88b02ecfcb44f2166f9c0b7f2a0d" ``` {{< /foundationtabspanel >}} {{< /foundationtabspanels >}} pkg_deps : The dependencies that your packages needs at runtime. Refer to packages at three levels of specificity: origin/package, origin/package/version, or origin/package/version/release. Type: array. Optional. {{< foundation_tabs tabs-id="bash-powershell-panel8" >}} {{< foundation_tab active="true" panel-link="bash-panel8" tab-text="Bash">}} {{< foundation_tab panel-link="powershell-panel8" tab-text="Powershell" >}} {{< /foundation_tabs >}} {{< foundationtabspanels tabs-id="bash-powershell-panel8" >}} {{< foundationtabspanel active="true" panel-id="bash-panel8" >}} ```bash pkg_deps=(core/glibc core/pcre core/openssl core/zlib) ``` {{< /foundationtabspanel >}} {{< foundationtabspanel panel-id="powershell-panel8" >}} ```powershell $pkg_deps="(core/glibc core/pcre core/openssl core/zlib)" ``` {{< /foundationtabspanel >}} {{< /foundationtabspanels >}} pkgbuilddeps : The dependencies your package requires at build time. Type: array. Optional. {{< foundation_tabs tabs-id="bash-powershell-panel9" >}} {{< foundation_tab active="true" panel-link="bash-panel9" tab-text="Bash">}} {{< foundation_tab panel-link="powershell-panel9" tab-text="Powershell" >}} {{< /foundation_tabs >}} {{< foundationtabspanels tabs-id="bash-powershell-panel9" >}} {{< foundationtabspanel active="true" panel-id="bash-panel9" >}} ```bash pkgbuilddeps=(core/gcc core/linux-headers) ``` {{< /foundationtabspanel >}} {{< foundationtabspanel panel-id="powershell-panel9" >}} ```powershell $pkgbuilddeps="(core/gcc core/linux-headers)" ``` {{< /foundationtabspanel >}} {{< /foundationtabspanels >}} pkglibdirs : An array of paths, relative to the final install of the software, where libraries can be found. Used to populate `LDFLAGS` and `LDRUNPATH` for software that depends on your package. Optional_. ```bash pkglibdirs=(lib) ``` pkgincludedirs : An array of paths, relative to the final install of the software, where headers can be found. Used to populate `CFLAGS` for software that depends on your package. Optional. ```bash pkgincludedirs=(include) ``` pkgbindirs : An array of paths, relative to the final install of the software, where binaries can be found. Used to populate `PATH` for software that depends on your package. Optional. ```bash pkgbindirs=(bin) ``` pkgpconfigdirs : An array of paths, relative to the final install of the software, where pkg-config metadata (.pc files) can be found. Used to populate `PKGCONFIGPATH` for software that depends on your package. Optional. ```bash pkgpconfigdirs=(lib/pkgconfig) ``` pkgsvcrun : The command for the Supervisor to execute when starting a service. This setting requires `pkgbindirs` to place package binaries in the path. If your package hs complex start-up behaviors, use a

Omit this setting for packages that are designed for consumption by other packages instead of being run directly by a Supervisor. Optional. ```bash pkgsvcrun="haproxy -f $pkgsvcconfig_path/haproxy.conf" ``` pkg_exports : Configuration data that will be passed between peers. The keys in this array are used with `pkgexposes` and for any consuming services that set `pkgbinds` or `pkgbindsoptional`. An in Bash or a `hashtable` in Powershell. Type: array. Optional. ```bash pkg_exports=( [port]=server.port [host]=server.host [ssl-port]=ssl.port ) ``` In this example, the corresponding `default.toml` file would have the following key/value pairs defined: ```toml default.toml [server] port = 80 host = "www.example.com" [ssl] port = 443 ``` pkg_exposes : An array of `pkgexports` keys containing default values for the ports that this package exposes. These values are used as sensible defaults for other tools, such as when exporting a package to a container format. Optional_. ```bash pkg_exposes=(port ssl-port) ``` {{< note >}} In addition to specifying the keys you defined in `pkg_exports`, you must have a default.toml file indicating the port values to expose. {{< /note >}} pkg_binds : An associative array (or `hashtable` in Powershell) representing services which you depend on and the configuration keys that you expect the service to export (by their `pkgexports`). These binds *must* be set for the Supervisor to load the service. The loaded service will wait to run until its bind becomes available. If the bind does not contain the expected keys, the service will not start successfully. Optional_. ```bash pkg_binds=( [database]="port host" ) ``` pkgbindsoptional : Same as `pkgbinds` but these represent optional services to connect to. Optional_. ```bash pkgbindsoptional=( [storage]="port host" ) ``` pkg_interpreters : An array of interpreters used in ) lines for scripts. Specify the subdirectory where the binary is relative to the package, for example, `bin/bash` or `libexec/neverland`, since binaries can be located in directories besides `bin`. This list of interpreters will be written to the metadata INTERPRETERS file, located inside a package, with their fully-qualified path. Then these can be used with the fixinterpreter function. For more information on declaring shebangs in Chef Habitat, see , and for more information on the fixinterpreter function, see . Optional. ```bash pkg_interpreters=(bin/bash) ``` pkgsvcuser : The user to run the service as. Default: `hab`. On Windows, if the `hab` user does not exist then the service will run under the same account as the Supervisor. Optional. ```bash pkgsvcuser=hab ``` pkgsvcgroup : Assigned service group for the package. Not used in a `plan.ps1`. Type: string. Default: `hab`. Optional. ```bash pkgsvcgroup=$pkgsvcuser ``` pkgshutdownsignal : The signal to send the service to shutdown. Not used in a `plan.ps1`. Default: `TERM`. Optional. ```bash pkgshutdownsignal=HUP ``` pkgshutdowntimeout_sec : The number of seconds to wait for a service to shutdown. After this interval the service will forcibly be killed. Not used in a `plan.ps1`. Default: `8`. Optional. ```bash pkgshutdowntimeoutsec=$pkgshutdowntimeoutsec ``` pkg_description : A short description of the package. It can be a simple string, or you can create a multi-line description using markdown to provide a rich description of your package. This description will be displayed on the Web app when users search for or browse to your package. Type: Text.Required for plans, but otherwise Optional. ```bash pkg_description=$(cat << EOF This is the package for the foo library. It's pretty awesome. EOF ) ``` {{< note >}} Escape all special characters other than `#`. The hab-plan-build script interprets unescaped characters as code during the package build. {{< /note >}} pkgupstreamurl : An upstream project homepage or website URL. Optional. ```bash pkgupstreamurl=https://github.com/myrepo ```