From time to time, an application requires non-standard operation in its build-system, so a `code block` is used.
`@configure` code blocks allow to change the execution of the `configure` script in a package build.
Without it, `packaging` simply performs a `./configure` with options provided in the recipe.
In the next example, a file (`some-file`) needs to be changed before using the `configure` script.
```YAML
# "@configure" is a code block in the recipes of `packaging`.
@configure
sed -i "s/a/b/" some-file
./configure
```
In this example, `sed` is called before `./configure`, and this could have been as complex as required by the build system of the application.
Having this code block allows to package applications with non-standard build system, while keeping recipes as simple as possible when applications do use standard build systems.
<aname="example-service"></a>
## In `service`
A service description can be as simple as providing the name of the service, the command to run it and the list of tokens the service provides or consumes.
For example, the `pubsubd` service:
```YAML
name: pubsubd
environment-variables:
- LD_LIBRARY_PATH=/usr/local/lib
command: pubsubd -s /srv/${ENVIRONMENT}/pubsub
provides: pubsub
```
Additionaly, before running the service, the service may require the creation of directories (or files).
In this case, sections are used to describe the file to create.
In the next example,
```YAML
# "%configuration" is a section and its "target" ("nginx.conf" in this example ) is
# the name of both the template to use and the generated file.
%configuration nginx.conf
# Within a section, variables are declared in the same way as outside the block.
name: This is the configuration file for Nginx.
permissions: 0700
```
Another example is the `%directory` section.
```YAML
# "%directory" is a section, the target is the name of the directory.
%directory %{SERVICE_ROOT}/data
name: Storage directory for pubsubd.
# A command may be provided to know how to create the directory and its content.
command: install -d -m6777 %{SERVICE_ROOT}/data
```
<aname="rationale"></a>
# Rationale
## `spec` is *declarative* <side-note>*describe what is, not how*</side-note>
Configuration should be about <u>describing what something is</u>.
For example, a web server should ask the domains it should serve.
## `spec` can be *imperative* too <side-note>*for complex cases, where it is not possible to do differently*</side-note>
<u>How</u> things are done is an **implementation detail**.
However, in complex cases the user may provide <u>optional</u> informations on *how* to do things.
Imperative configuration is useful for example in [packaging][packaging]: some applications require specific non-generic operations to be packaged.
In those cases, it is not a reasonable solution to try to implement every possible - and changing - way of packaging an application directly in `packaging`.
Instead, each application with a non-standard build system has a code block in its recipe where every non-standard operation is performed.
## `spec` is concise and simple <side-note>variables, lists, code blocks and sections</side-note>
Variables and lists look like YAML (and markdown), which is one of the simpliest configuration possible.
It is humanly readable, unlike XML and its bloated-beyond-repair syntax, and it is simpler to read than JSON.
XML <side-note>(XML Schema could be used too, to create simpler lists *after the definition of the schema*, but seriously… if documentation is needed to create a simple fucking list, this is just fucked up)</side-note>