<commit_before># The OPAM manual

This manual gathers reference information on OPAM and its file formats. It is
primarily of use for packagers, package maintainers and repository maintainers.

* For simple usage of OPAM, see the [Usage](Usage.html) page, and the
  comprehensive built-in documentation `opam [command] --help`.
* For a gentler introduction to packaging, see the
  [Packaging guide](Packaging.html)
* For a more complete specification, and if you are interested in more details
  on the layout of `~/.opam`, you may want to check the
  [OPAM Developer's Manual](http://opam.ocaml.org/doc/manual/dev-manual.html)

This version of the manual documents the version `1.2` of the file formats, with
some `1.2.1` experimental extensions mentionned.


## General file format

### General syntax

The OPAM file formats share a common base syntax. The files are utf8 encoded
and made of a list of fields in the form `<field-name>: <value>`.

Available field names are specific to each specific file format, and each of
them only allows values of a certain format.

Base values can be literal booleans, integers or strings, identifiers, and
operators. Strings allow the escapes `\\`, `\n`, `\r`, `\b`, `\t`, as well as
three-digit decimal and two-digit hexadecimal character codes (`\NNN` and
`\xNN`), and escaped newlines. Lists must be enclosed in square brackets unless
they contain a single element. Values can be followed by an argument in braces.
Parentheses may be used to group sub-expressions.

<table class="table">
<thead><tr> <th>type</th> <th>format</th> <th>example</th> </tr></thead>
<tbody>
  <tr> <td>bool</td> <td><code>true|false</code></td> <td><code>true</code></td> </tr>
  <tr> <td>int</td> <td><code>-?[0-9]+</code></td> <td><code>42</code></td> </tr>
  <tr> <td>string</td> <td><code>"..."</code></td> <td><code>"a string"</code></td> </tr>
  <tr> <td>ident</td> <td><code>[a-zA-Z_][a-zA-Z0-9:_+-]*</code></td> <td><code>foo</code></td> </tr>
  <tr> <td>operator</td> <td><code>[!=&lt;&gt;|&amp;+:]+</code></td> <td><code>&gt;=</code></td> </tr>
  <tr> <td>list</td> <td> <code>&lt;value&gt;</code> or <code>[ &lt;value&gt; &lt;value&gt; ... ]</code> </td> <td><code>[ foo "bar" ]</code></td> </tr>
  <tr> <td>option</td> <td> <code>&lt;value&gt;</code> or <code>&lt;value&gt; { &lt;value&gt; &lt;value&gt; ... }</code> </td> <td><code>foo { &gt; "0" }</code></td> </tr>
  <tr> <td>parens</td> <td><code>(&lt;value&gt;)</code></td> <td><code>(foo &amp; bar)</code></td> </tr>
</tbody>
</table>

Comments may be either enclosed in `(*` and `*)`, or `#` and newline. They are
ignored by OPAM.


### Package Formulas

Both package names and versions are encoded as strings. Formulas allow to
specify conditions on installed packages. They are logic formulas using the
operators `&` and `|` for AND and OR, over package names:

```
("neat_package" | "also_neat_package") & "required_package"
```

Package names can be suffixed with _version constraints_, which restricts the
requirement further. Version constraints have the form `<relop> <version>` and
can be combined with binary AND `&` and OR `|`, and prefix NOT `!`. The allowed
relational operators are `=`, `!=`, `<`, `<=`, `>` and `>=`, and their meaning
is defined by Version Ordering.

> <a id="version-ordering">**Version Ordering**</a> follows the basics of the
> [Debian definition](https://www.debian.org/doc/debian-policy/ch-controlfields.html#s-f-Version).
>
> It is basically "lexicographical order, with numbers handled properly". In
> more detail:
>
> - version strings are sliced into alternate, possibly empty non-digit / digit
>   sequences, always starting with a non-digit sequence. `1.0~beta2` is thus
>   `["";1;".";0;"~beta";2]`.
> - those are sorted lexicographically, using resp. ASCII (with symbol > letter)
>   and number order. For example `a` gives `["a"]`, and `1` gives `["";1]`, so
>  `a` is latest (`"" < "a"`).
> - the `~` character is special as it sorts even before the end of sequence
>   (_i.e._ before anything shorter: "~" sorts before "", "a~b" before "a").
>   It's most convenient for pre-releases, allowing `1.0~beta` to be before
>   `1.0`.
>
> Here is an example of an ordered sequence: `~~`, `~`, `~beta2`, `~beta10`,
> `0.1`, `1.0~beta`, `1.0`, `1.0-test`, `1.0.1`, `1.0.10`, `dev`, `trunk`.

Here is a full example:

```
"foo" { >= "3.12" } & ("bar" | "baz" { !(> "2" & < "3.5") & != "5.1" })
```

### Variables

#### Usage

Variables may appear at a few different places in OPAM files and configuration.
They can be used in two forms:

- raw idents: `foo < bar`
- within strings, using _interpolation_, when enclosed in `%{` and `}%`:
  `"%{foo}%/bar"`

For both forms, and within values that allow them, the variables are replaced by
their contents, if any, just before the value is used. Variable contents can be
either _strings_, _booleans_ or _undefined_, and automatic conversion may take
place using the strings `"true"` and `"false"` (leading to an _undefined_ bool
when converting from any other string). Undefined values are propagated through<commit_msg>attempt to clarify version ordering<commit_after># The OPAM manual

This manual gathers reference information on OPAM and its file formats. It is
primarily of use for packagers, package maintainers and repository maintainers.

* For simple usage of OPAM, see the [Usage](Usage.html) page, and the
  comprehensive built-in documentation `opam [command] --help`.
* For a gentler introduction to packaging, see the
  [Packaging guide](Packaging.html)
* For a more complete specification, and if you are interested in more details
  on the layout of `~/.opam`, you may want to check the
  [OPAM Developer's Manual](http://opam.ocaml.org/doc/manual/dev-manual.html)

This version of the manual documents the version `1.2` of the file formats, with
some `1.2.1` experimental extensions mentionned.


## General file format

### General syntax

The OPAM file formats share a common base syntax. The files are utf8 encoded
and made of a list of fields in the form `<field-name>: <value>`.

Available field names are specific to each specific file format, and each of
them only allows values of a certain format.

Base values can be literal booleans, integers or strings, identifiers, and
operators. Strings allow the escapes `\\`, `\n`, `\r`, `\b`, `\t`, as well as
three-digit decimal and two-digit hexadecimal character codes (`\NNN` and
`\xNN`), and escaped newlines. Lists must be enclosed in square brackets unless
they contain a single element. Values can be followed by an argument in braces.
Parentheses may be used to group sub-expressions.

<table class="table">
<thead><tr> <th>type</th> <th>format</th> <th>example</th> </tr></thead>
<tbody>
  <tr> <td>bool</td> <td><code>true|false</code></td> <td><code>true</code></td> </tr>
  <tr> <td>int</td> <td><code>-?[0-9]+</code></td> <td><code>42</code></td> </tr>
  <tr> <td>string</td> <td><code>"..."</code></td> <td><code>"a string"</code></td> </tr>
  <tr> <td>ident</td> <td><code>[a-zA-Z_][a-zA-Z0-9:_+-]*</code></td> <td><code>foo</code></td> </tr>
  <tr> <td>operator</td> <td><code>[!=&lt;&gt;|&amp;+:]+</code></td> <td><code>&gt;=</code></td> </tr>
  <tr> <td>list</td> <td> <code>&lt;value&gt;</code> or <code>[ &lt;value&gt; &lt;value&gt; ... ]</code> </td> <td><code>[ foo "bar" ]</code></td> </tr>
  <tr> <td>option</td> <td> <code>&lt;value&gt;</code> or <code>&lt;value&gt; { &lt;value&gt; &lt;value&gt; ... }</code> </td> <td><code>foo { &gt; "0" }</code></td> </tr>
  <tr> <td>parens</td> <td><code>(&lt;value&gt;)</code></td> <td><code>(foo &amp; bar)</code></td> </tr>
</tbody>
</table>

Comments may be either enclosed in `(*` and `*)`, or `#` and newline. They are
ignored by OPAM.


### Package Formulas

Both package names and versions are encoded as strings. Formulas allow to
specify conditions on installed packages. They are logic formulas using the
operators `&` and `|` for AND and OR, over package names:

```
("neat_package" | "also_neat_package") & "required_package"
```

Package names can be suffixed with _version constraints_, which restricts the
requirement further. Version constraints have the form `<relop> <version>` and
can be combined with binary AND `&` and OR `|`, and prefix NOT `!`. The allowed
relational operators are `=`, `!=`, `<`, `<=`, `>` and `>=`, and their meaning
is defined by Version Ordering.

> <a id="version-ordering">**Version Ordering**</a> follows the basics of the
> [Debian definition](https://www.debian.org/doc/debian-policy/ch-controlfields.html#s-f-Version).
>
> It is basically "lexicographical order, with numbers handled
> properly". In more detail (see the [Debian
> page](https://www.debian.org/doc/debian-policy/ch-controlfields.html#s-f-Version)
> for full details):
>
> - Version strings are sliced into alternate, possibly empty non-digit / digit
>   sequences, always starting with a non-digit sequence. `1.0~beta2` is thus
>   `["";1;".";0;"~beta";2]`.
>
> - Those sequences are sorted lexicographically. Because of the split
>   as `non-digit; digit; non-digit; ...`, non-digit sequences are
>   always compared to non-digit sequences (and conversely). For
>   example, the versions `a` and `1` are sliced into `["a"]` and
>   `[""; 1]`, so we have `1 < a` because the non-digit component of
>   1, which is the empty string `""`, is smaller than `"a"`.
>
> - For non-digit components, the ordering used is that letters are
>   always smaller than non-letters (for example `z` < `"#"`), while
>   non-letters are compared by ASCII order.
>
> - The `~` character is special as it sorts even before the end of sequence
>   (_i.e._ before anything shorter: "~" sorts before "", "a~b" before "a").
>   It's most convenient for pre-releases, allowing `1.0~beta` to be before
>   `1.0`.
>
> Here is an example of an ordered sequence: `~~`, `~`, `~beta2`, `~beta10`,
> `0.1`, `1.0~beta`, `1.0`, `1.0-test`, `1.0.1`, `1.0.10`, `dev`, `trunk`.

Here is a full example:

```
"foo" { >= "3.12" } & ("bar" | "baz" { !(> "2" & < "3.5") & != "5.1" })
```

### Variables

#### Usage

Variables may appear at a few different places in OPAM files and configuration.
They can be used in two forms:

- raw idents: `foo < bar`
- within strings, using _interpolation_, when enclosed in `%{` and `}%`:
  `"%{foo}%/bar"`

For both forms, and within values that allow them, the variables are replaced by
their contents, if any, just before the value is used. Variable contents can be
either _strings_, _booleans_ or _undefined_, and automatic conversion may take
place using the strings `"true"` and `"false"` (leading to an _undefined_ bool
when converting from any other string). Undefined values are propagated through
{'fraction_non_alphanumeric': 0.17395357509089215, 'fraction_numerical': 0.009695161741400206, 'mean_word_length': 4.380140421263792, 'pattern_counts': {'":': 0, '<': 254, '<?xml version=': 0, '>': 301, 'https://': 3, 'lorem ipsum': 0, 'www.': 3, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 2, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '1313031', 'n_tokens_mistral': 3661, 'n_tokens_neox': 3508, 'n_words': 1297}