diff options
Diffstat (limited to 'MANIFEST-FORMAT.md')
| -rw-r--r-- | MANIFEST-FORMAT.md | 38 |
1 files changed, 19 insertions, 19 deletions
diff --git a/MANIFEST-FORMAT.md b/MANIFEST-FORMAT.md index 08064f1..d1474bf 100644 --- a/MANIFEST-FORMAT.md +++ b/MANIFEST-FORMAT.md @@ -38,11 +38,11 @@ rely entirely on the built-in rules. # Path matching rules Most of the manifest is about declaring rules for a given path such as "foo must be a symlink" -or "bar must be owned by root:tty and have mode 02755". +or "bar must be owned by root:tty and have mode 02755". The manifest contains the following types of matches: - 1) Exact path matches. These specify the path inside the debian package exactly without any + 1) Exact path matches. These specify the path inside the Debian package exactly without any form of wildcards (e.g., `*` or `?`). However, they can use substitution variables. Examples include: * `usr/bin/sudo` @@ -97,7 +97,7 @@ These limitations are in place because of implementation details in `debputy`. The manifest can contain seemly mutually exclusive rules. As an example, if you ask for `foo/symlink` to be a symlink but also state that you want to remove `foo` entirely -from the debian package then the manifest now has two mutually exclusive requests. +from the Debian package then the manifest now has two mutually exclusive requests. To resolve these problems, `debputy` relies on the following rules for conflict resolutions: @@ -151,7 +151,7 @@ In general, the following rules applies to globs in `debputy`. * The `*` match 0 or more times any characters except `/`. * The `?` match exactly one character except `/`. - * The glob `foo/*` matches _everything_ inside `foo/` including hidden files (i.e., paths starting + * The glob `foo/*` matches _everything_ inside `foo/` including hidden files (i.e., paths starting with `.`) unlike `bash`/`sh` globs. However, `foo/*` does _not_ match `foo/` itself (this latter part matches `bash`/`sh` behaviour and should be unsurprising). * For the special-cases where `**` is supported, then `**` matches zero or more levels of directories. @@ -166,7 +166,7 @@ work. The rules will explicitly list if they divert from the above listed glob r The `debputy` tool supports substitution in various places (usually paths) via the following rules. That means: - 1) All substitutions must start with `{{` and end with `}}`. The part inbetween is + 1) All substitutions must start with `{{` and end with `}}`. The part between is the `MANIFEST_VARIABLE` and must match the regular expression `[A-Za-z0-9][-_:0-9A-Za-z]*`. Note that you can use space around the variable name if you feel that increases readability. (That is, `{{ FOO }}` can be used as an alternative to `{{FOO}}`). @@ -224,7 +224,7 @@ one of the following formats: 1) A name (e.g., `owner: root`). 2) An id (e.g., `owner: 0`). Please avoid using quotes around the ID in YAML as that can cause `debputy` to read the number as a name. - 3) A name and an id with a colon inbetween (e.g., `owner: "root:0"`). The name must always + 3) A name and an id with a colon in between (e.g., `owner: "root:0"`). The name must always come first here. You may have to quote the value to prevent the YAML parser from being confused. @@ -243,7 +243,7 @@ Regardless of which form you pick: be invalid as the id for `root` is defined to be `0` in the `base-passwd` data files. 3) The `debputy` tool maintains a `deny`-list of owners that it refuses even though `base-passwd` - defines them. As a notable non-exhaustive example, `debputy` considers `nobody` or id `65534` + defines them. As a notable non-exhaustive example, `debputy` considers `nobody` or id `65534` (the ID of `nobody` / `nogroup`) to be invalid owners. @@ -703,7 +703,7 @@ This install rule resemble that of `dh_installdocs`. It is a shorthand over the With these two things in mind, it behaves just like the `install` rule. Note: It is often worth considering to use a more specialized version of the `install-docs` -rule when one such is available. If you are looking to install an example or a manpage, +rule when one such is available. If you are looking to install an example or a man page, consider whether `install-examples` or `install-man` might be a better fit for your use-case. @@ -805,16 +805,16 @@ or `sources` (respectively). This form can only be used when `into` is not requ Note: While the canonical name for this rule use plural, the `install-example` variant is accepted as alternative name. -## Install manpages (`install-man`) +## Install man pages (`install-man`) -Install rule for installing manpages similar to `dh_installman`. It is a shorthand over the generic +Install rule for installing man pages similar to `dh_installman`. It is a shorthand over the generic `install` rule with the following key features: 1) The rule can only match files (notably, symlinks cannot be matched by this rule). - 2) The `dest-dir` is computed per source file based on the manpage's section and language. + 2) The `dest-dir` is computed per source file based on the man page's section and language. 3) The `into` parameter can be omitted as long as there is a exactly one non-`udeb` package listed in `debian/control`. - 4) The rule comes with manpage specific attributes such as `language` and `section` for when the + 4) The rule comes with man page specific attributes such as `language` and `section` for when the auto-detection is insufficient. 5) The rule comes with pre-defined conditional logic for skipping the rule under `DEB_BUILD_OPTIONS=nodoc`, so you do not have to write that conditional yourself. @@ -841,18 +841,18 @@ has the following key/value pairs: search directories. Only files can be matched. * `into` (conditional): Either a package name or a list of package names for which these paths should be - installed as manpages. This key is conditional on whether there are multiple (non-`udeb`) binary + installed as man pages. This key is conditional on whether there are multiple (non-`udeb`) binary packages listed in `debian/control`. When there is only one (non-`udeb`) binary package, then that binary is the default for `into`. Otherwise, the key is required. * `section` (optional): If provided, it must be an integer between 1 and 9 (both inclusive), defining the - section the manpages belong overriding any auto-detection that `debputy` would have performed. + section the man pages belong overriding any auto-detection that `debputy` would have performed. * `language` (optional): If provided, it must be either a 2 letter language code (such as `de`), a 5 letter language + dialect code (such as `pt_BR`), or one of the special keywords `C`, `derive-from-path`, or `derive-from-basename`. The default is `derive-from-path`. - - When `language` is `C`, then the manpages are assumed to be "untranslated". - - When `language` is a language code (with or without dialect), then all manpages matched will be assumed + - When `language` is `C`, then the man pages are assumed to be "untranslated". + - When `language` is a language code (with or without dialect), then all man pages matched will be assumed to be translated to that concrete language / dialect. - When `language` is `derive-from-path`, then `debputy` attempts to derive the language from the path (`man/<language>/man<section>`). This matches the default of `dh_installman`. When no language can @@ -997,7 +997,7 @@ you might find yourself with some files that are _not_ relevant for the Debian p relevant for other distros or for non-distro local builds). Common examples include `INSTALL` files or `LICENSE` files (when they are just a subset of `debian/copyright`). -In the manifest, you can ask `debputy` to remove paths from the debian package by using the `remove` +In the manifest, you can ask `debputy` to remove paths from the Debian package by using the `remove` transformation rule. An example being: packages: @@ -1361,7 +1361,7 @@ Each mapping has the following key/value pairs: not supported. - `restart`: During an upgrade, `restart` the service post upgrade. The service will be left running during the upgrade process. - - `stop-then-start`: Stop the service before the upgrade, preform the upgrade and then start the service. + - `stop-then-start`: Stop the service before the upgrade, perform the upgrade and then start the service. ### Service managers and aliases @@ -1421,7 +1421,7 @@ Use this feature sparingly as it is generally not possible to undo as each versi higher than the previous one. This feature translates into `-v` option for `dpkg-gencontrol`. The value for the `binary-version` key is a string that defines the binary version. Generally, you will -want it to contain one of the versioned related substitution variables such as +want it to contain one of the versioned related substitution variables such as `{{DEB_VERSION_UPSTREAM_REVISION}}`. Otherwise, you will have to remember to bump the version manually with each upload as versions cannot be reused and the package would not support binNMUs either. |