From bb72a0c0cea80cdc24e80c57c4a375b84d1b7369 Mon Sep 17 00:00:00 2001 From: Adrien Delorme Date: Wed, 18 Dec 2019 16:57:36 +0100 Subject: [PATCH] document hcl language & syntax --- .../docs/configuration/from-1.5/index.html.md | 74 +++++++++++ .../configuration/from-1.5/syntax.html.md | 119 ++++++++++++++++++ website/source/layouts/docs.erb | 11 ++ 3 files changed, 204 insertions(+) create mode 100644 website/source/docs/configuration/from-1.5/index.html.md create mode 100644 website/source/docs/configuration/from-1.5/syntax.html.md diff --git a/website/source/docs/configuration/from-1.5/index.html.md b/website/source/docs/configuration/from-1.5/index.html.md new file mode 100644 index 000000000..ff3953d70 --- /dev/null +++ b/website/source/docs/configuration/from-1.5/index.html.md @@ -0,0 +1,74 @@ +--- +layout: "docs" +page_title: "Configuration Language" +sidebar_current: "configuration" +description: |- + Packer uses text files to describe infrastructure and to set variables. + These text files are called Packer _configurations_ and are + written in the HCL language. +--- + +# HCL Configuration Language + +Packer uses the Hashicorp Configuration Language - HCL - designed to allow +concise descriptions of the required steps to get to a build file. + +## Builds + +The main purpose of the HCL language is defining builds and sources. All other +language features exist only to make the definition of builds more flexible and +convenient. + + +`packer build` takes one argument. When a directory is passed, all files in the +folder with a name ending with ".pkr.hcl" or ".pkr.json" will be parsed using +the HCL2 format. When a file ending with ".pkr.hcl" or ".pkr.json" is passed it +will be parsed using the HCL2 schema. For every other case; the *JSON only* old +packer schema will be used. + +## Arguments, Blocks, and Expressions + +The syntax of the HCL language consists of only a few basic elements: + +```hcl +source "amazon-ebs" "main" { + ami_name = "main-ami" +} + + "" "" { + # Block body + = # Argument +} +``` + +- _Blocks_ are containers for other content and usually represent the + configuration of some kind of object, like a source. Blocks have a + _block type,_ can have zero or more _labels,_ and have a _body_ that contains + any number of arguments and nested blocks. Most of Packer's features are + controlled by top-level blocks in a configuration file. +- _Arguments_ assign a value to a name. They appear within blocks. +- _Expressions_ represent a value, either literally or by referencing and + combining other values. They appear as values for arguments, or within other + expressions. + +For full details about Packer's syntax, see: + +- [Configuration Syntax](./syntax.html) +- [Expressions](./expressions.html) + +## Code Organization + +The HCL language uses configuration files that are named with the `.pkr.hcl` +file extension. There is also [a JSON-based variant of the +language](./syntax-json.html) that is named with the `.pkr.json` file +extension. + +Configuration files must always use UTF-8 encoding, and by convention are +usually maintained with Unix-style line endings (LF) rather than Windows-style +line endings (CRLF), though both are accepted. + +## Configuration Ordering + +The ordering of root blocks is not significant. The order of `provisioner` or +`post-processor` blocks within a `build` is the only major feature where block +order matters. diff --git a/website/source/docs/configuration/from-1.5/syntax.html.md b/website/source/docs/configuration/from-1.5/syntax.html.md new file mode 100644 index 000000000..4bcbb4e91 --- /dev/null +++ b/website/source/docs/configuration/from-1.5/syntax.html.md @@ -0,0 +1,119 @@ +--- +layout: "docs" +page_title: "Syntax - Configuration Language" +sidebar_current: configuration-syntax +description: |- + HCL has its own syntax, intended to combine declarative + structure with expressions in a way that is easy for humans to read and + understand. +--- + +# HCL Configuration Syntax + +Other pages in this section have described various configuration constructs +that can appear in HCL. This page describes the lower-level syntax of the +language in more detail, revealing the building blocks that those constructs +are built from. + +This page describes the _native syntax_ of HCL, which is a rich language +designed to be easy for humans to read and write. The constructs in HCL can +also be expressed in [JSON syntax](/syntax-json.html), which is harder for +humans to read and edit but easier to generate and parse programmatically. + +This low-level syntax of HCL is defined in terms of a syntax called _HCL_, +which is also used by configuration languages in other applications, and in +particular other HashiCorp products. It is not necessary to know all of the +details of HCL in order to use Packer, and so this page summarizes the most +important details. If you are interested, you can find a full definition of HCL +syntax in [the HCL native syntax +specification](https://github.com/hashicorp/hcl/blob/hcl2/hclsyntax/spec.md). + +## Arguments and Blocks + +HCL syntax is built around two key syntax constructs: +arguments and blocks. + +### Arguments + +An _argument_ assigns a value to a particular name: + +```hcl +image_id = "abc123" +``` + +The identifier before the equals sign is the _argument name_, and the expression +after the equals sign is the argument's value. + +The context where the argument appears determines what value types are valid +(for example, each source type has a schema that defines the types of its +arguments), but many arguments accept arbitrary +[expressions](/expressions.html), which allow the value to +either be specified literally or generated from other values programmatically. + +### Blocks + +A _block_ is a container for other content: + +```hcl +source "amazon-ebs" "example" { + ami_name = "abc123" + + tags { + # ... + } +} +``` + +A block has a _type_ (`source` in this example). Each block type defines +how many _labels_ must follow the type keyword. The `source` block type +expects two labels, which are `amazon-ebs` and `example` in the example above. +A particular block type may have any number of required labels, or it may +require none as with the nested `tags` block type. + +After the block type keyword and any labels, the block _body_ is delimited +by the `{` and `}` characters. Within the block body, further arguments +and blocks may be nested, creating a hierarchy of blocks and their associated +arguments. + +HCL uses a limited number of _top-level block types,_ which +are blocks that can appear outside of any other block in a configuration file. +Most of Packer's features (including resources, input variables, output +values, data sources, etc.) are implemented as top-level blocks. + +## Identifiers + +Argument names, block type names, and the names of most Packer-specific +constructs like resources, input variables, etc. are all _identifiers_. + +Identifiers can contain letters, digits, underscores (`_`), and hyphens (`-`). +The first character of an identifier must not be a digit, to avoid ambiguity +with literal numbers. + +For complete identifier rules, Packer implements +[the Unicode identifier syntax](http://unicode.org/reports/tr31/), extended to +include the ASCII hyphen character `-`. + +## Comments + +HCL supports three different syntaxes for comments: + +* `#` begins a single-line comment, ending at the end of the line. +* `//` also begins a single-line comment, as an alternative to `#`. +* `/*` and `*/` are start and end delimiters for a comment that might span + over multiple lines. + +The `#` single-line comment style is the default comment style and should be +used in most cases. Automatic configuration formatting tools may automatically +transform `//` comments into `#` comments, since the double-slash style is +not idiomatic. + +## Character Encoding and Line Endings + +Packer configuration files must always be UTF-8 encoded. While the +delimiters of the language are all ASCII characters, Packer accepts +non-ASCII characters in identifiers, comments, and string values. + +Packer accepts configuration files with either Unix-style line endings +(LF only) or Windows-style line endings (CR then LF), but the idiomatic style +is to use the Unix convention, and so automatic configuration formatting tools +may automatically transform CRLF endings to LF. diff --git a/website/source/layouts/docs.erb b/website/source/layouts/docs.erb index 657ed4867..2099e6be0 100644 --- a/website/source/layouts/docs.erb +++ b/website/source/layouts/docs.erb @@ -1,6 +1,17 @@ <% wrap_layout :inner do %> <% content_for :sidebar do %>