From da1ddefda955720f5f54c17378d48fdd879285a6 Mon Sep 17 00:00:00 2001 From: Guillem Jover Date: Sun, 17 Sep 2023 03:57:40 +0200 Subject: [PATCH] man: Use semantic line breaks (must requirements) MIME-Version: 1.0 Content-Type: text/plain; charset=utf8 Content-Transfer-Encoding: 8bit Add line breaks after every «.», «!» and «?» that ends a sentence. We only reflow or fold lines that are getting modified anyway as part of this change, to avoid diff churn. In addition this will make the manual page output consistent, and removes duplicate paragraphs in the translations only differing the spacing after the full stop. This change should not affect the semantics of the sentences and should produce a no-change «git diff --word-diff» output. See . --- man/deb-control.pod | 49 ++++++--- man/deb-extra-override.pod | 9 +- man/deb-md5sums.pod | 3 +- man/deb-old.pod | 18 ++-- man/deb-origin.pod | 8 +- man/deb-override.pod | 9 +- man/deb-shlibs.pod | 9 +- man/deb-split.pod | 12 ++- man/deb-src-control.pod | 77 ++++++++----- man/deb-src-symbols.pod | 209 ++++++++++++++++++++++------------- man/deb-substvars.pod | 26 +++-- man/deb-symbols.pod | 12 ++- man/deb-triggers.pod | 12 ++- man/deb-version.pod | 42 +++++--- man/deb.pod | 15 ++- man/dpkg-architecture.pod | 42 +++++--- man/dpkg-buildflags.pod | 110 ++++++++++++------- man/dpkg-buildpackage.pod | 38 ++++--- man/dpkg-checkbuilddeps.pod | 10 +- man/dpkg-deb.pod | 54 ++++++---- man/dpkg-divert.pod | 21 ++-- man/dpkg-fsys-usrunmess.pod | 9 +- man/dpkg-genbuildinfo.pod | 12 ++- man/dpkg-genchanges.pod | 9 +- man/dpkg-gencontrol.pod | 28 +++-- man/dpkg-gensymbols.pod | 76 ++++++++----- man/dpkg-maintscript-helper.pod | 82 +++++++++----- man/dpkg-mergechangelogs.pod | 15 ++- man/dpkg-name.pod | 21 ++-- man/dpkg-parsechangelog.pod | 26 +++-- man/dpkg-query.pod | 41 ++++--- man/dpkg-scanpackages.pod | 12 ++- man/dpkg-scansources.pod | 17 +-- man/dpkg-shlibdeps.pod | 113 ++++++++++++------- man/dpkg-source.pod | 228 +++++++++++++++++++++++++-------------- man/dpkg-split.pod | 18 ++-- man/dpkg-statoverride.pod | 15 ++- man/dpkg-trigger.pod | 9 +- man/dpkg-vendor.pod | 9 +- man/dpkg.cfg.pod | 7 +- man/dpkg.pod | 234 ++++++++++++++++++++++++++-------------- man/dselect.cfg.pod | 7 +- man/dselect.pod | 125 +++++++++++++-------- man/start-stop-daemon.pod | 71 +++++++----- man/update-alternatives.pod | 62 +++++++---- 45 files changed, 1338 insertions(+), 693 deletions(-) diff --git a/man/deb-control.pod b/man/deb-control.pod index 6f72e2ba9..4c8d006b8 100644 --- a/man/deb-control.pod +++ b/man/deb-control.pod @@ -43,7 +43,8 @@ or B (case insensitive), followed by a colon, and the body of the field (case sensitive unless stated otherwise). -Fields are delimited only by field tags. In other words, field text +Fields are delimited only by field tags. +In other words, field text may be multiple lines in length, but the installation tools will generally join lines when processing the body of the field (except in the case of the @@ -69,8 +70,9 @@ More types might be added in the future. =item B I (required) Typically, this is the original package's version number in whatever form -the program's author uses. It may also include a Debian revision number -(for non-native packages). The exact format and sorting algorithm +the program's author uses. +It may also include a Debian revision number (for non-native packages). +The exact format and sorting algorithm are described in L. @@ -85,8 +87,9 @@ software that was packaged. =item S< >I The format for the package description is a short brief summary on the -first line (after the B field). The following lines should be -used as a longer, more detailed description. Each line of the long description +first line (after the B field). +The following lines should be used as a longer, more detailed description. +Each line of the long description must be preceded by a space, and blank lines in the long description must contain a single ‘B<.>’ following the preceding space. @@ -161,7 +164,8 @@ The name of the distribution this package is originating from. =item B I -The I of the bug tracking system for this package. The current +The I of the bug tracking system for this package. +The current used format is IB<://>I, like B. @@ -171,7 +175,8 @@ The upstream project home page I. =item B I -List of tags describing the qualities of the package. The description and +List of tags describing the qualities of the package. +The description and list of supported tags can be found in the B package. =item B B|B|B|B @@ -229,12 +234,14 @@ L I List of packages that are required for this package to provide a -non-trivial amount of functionality. The package maintenance software +non-trivial amount of functionality. +The package maintenance software will not allow a package to be installed if the packages listed in its B field aren't installed (at least not without using the force options). In an installation, the postinst scripts of packages listed in B -fields are run before those of the packages which depend on them. On the +fields are run before those of the packages which depend on them. +On the opposite, in a removal, the prerm script of a package is run before those of the packages listed in its B field. @@ -242,14 +249,16 @@ those of the packages listed in its B field. List of packages that must be installed B -configured before this one can be installed. This is usually used in the +configured before this one can be installed. +This is usually used in the case where this package requires another package for running its preinst script. =item B I Lists packages that would be found together with this one in all but -unusual installations. The package maintenance software will warn the +unusual installations. +The package maintenance software will warn the user if they install a package without those listed in its B field. @@ -268,7 +277,8 @@ B, B and B -fields is a list of groups of alternative packages. Each group is a list +fields is a list of groups of alternative packages. +Each group is a list of packages separated by vertical bar (or “pipe”) symbols, ‘B<|>’. The groups are separated by commas. @@ -298,7 +308,8 @@ for equal to. =item B I Lists packages that this one breaks, for example by exposing bugs -when the named packages rely on this one. The package maintenance +when the named packages rely on this one. +The package maintenance software will not allow broken packages to be configured; generally the resolution is to upgrade the packages named in a B @@ -307,15 +318,18 @@ field. =item B I Lists packages that conflict with this one, for example by containing -files with the same names. The package maintenance software will not -allow conflicting packages to be installed at the same time. Two +files with the same names. +The package maintenance software will not allow conflicting packages to be +installed at the same time. +Two conflicting packages should each include a B line mentioning the other. =item B I -List of packages files from which this one replaces. This is used for +List of packages files from which this one replaces. +This is used for allowing this package to overwrite the files of another package and is usually used with the B @@ -423,7 +437,8 @@ The only currently used reason is B. =item B I -This field specifies a whitespace separated list of ELF build-ids. These +This field specifies a whitespace separated list of ELF build-ids. +These are unique identifiers for semantically identical ELF objects, for each of these within the package. diff --git a/man/deb-extra-override.pod b/man/deb-extra-override.pod index 352867631..ec7c5cd51 100644 --- a/man/deb-extra-override.pod +++ b/man/deb-extra-override.pod @@ -29,9 +29,11 @@ B While most information about a binary/source package can be found in the control/.dsc file, all of it can be overridden when it's exported to -Packages/Sources files. The extra override file contains those overrides. +Packages/Sources files. +The extra override file contains those overrides. -The extra override file has a simple whitespace-delimited format. Comments are +The extra override file has a simple whitespace-delimited format. +Comments are allowed (denoted with a B<#>). @@ -50,7 +52,8 @@ I is the name of the field that is overridden. I -is the value to put in the field. It can contain spaces as the line is split +is the value to put in the field. +It can contain spaces as the line is split in no more than 3 columns when it's parsed. The extra override files used to make the official Packages lists may be found diff --git a/man/deb-md5sums.pod b/man/deb-md5sums.pod index 14d4b635a..a0139d85c 100644 --- a/man/deb-md5sums.pod +++ b/man/deb-md5sums.pod @@ -29,7 +29,8 @@ B A package declares the MD5 digests for the package file contents by including an I file in its control archive (i.e. I -during package creation). This file is used for integrity verification +during package creation). +This file is used for integrity verification and deduplication purposes, and not for any kind of security purpose. This file contains a list of MD5 digests (as 32 case-insensitive hexadecimal diff --git a/man/deb-old.pod b/man/deb-old.pod index a5253ef83..0acf9a98a 100644 --- a/man/deb-old.pod +++ b/man/deb-old.pod @@ -31,10 +31,12 @@ IB<.deb> The B<.deb> -format is the Debian binary package file format. This manual page +format is the Debian binary package file format. +This manual page describes the B -format, used before Debian 0.93. Please see +format, used before Debian 0.93. +Please see L for details of the new format. @@ -53,24 +55,28 @@ the length of the first gzipped tarfile. Each of these lines is terminated with a single newline character. The first tarfile contains the control information, as a series of -ordinary files. The file +ordinary files. +The file B must be present, as it contains the core control information. In some very old archives, the files in the control tarfile may optionally be in a B -subdirectory. In that case, the +subdirectory. +In that case, the B subdirectory will be in the control tarfile too, and the control -tarfile will have only files in that directory. Optionally the +tarfile will have only files in that directory. +Optionally the control tarfile may contain an entry for ‘B<.>’, that is, the current directory. The second gzipped tarfile is the filesystem archive, containing pathnames relative to the root directory of the system to be installed -on. The pathnames do not have leading slashes. +on. +The pathnames do not have leading slashes. =head1 SEE ALSO diff --git a/man/deb-origin.pod b/man/deb-origin.pod index 8d449982c..bf8080dff 100644 --- a/man/deb-origin.pod +++ b/man/deb-origin.pod @@ -34,8 +34,9 @@ various vendors who are providing Debian packages. They contain a number of fields, or comments when the line starts with ‘B<#>’. Each field begins with a tag, such as B or B, -followed by a colon and the body of the field. Fields are delimited -only by field tags. In other words, field text may be multiple lines +followed by a colon and the body of the field. +Fields are delimited only by field tags. +In other words, field text may be multiple lines in length, but the tools will join lines when processing the body of the field. @@ -75,7 +76,8 @@ The value of this field determines the vendor URL. =item B I The value of this field determines the type and address of the bug -tracking system used by this vendor. It can be a mailto URL or a +tracking system used by this vendor. +It can be a mailto URL or a debbugs URL (e.g., debbugs://bugs.debian.org/). =item B I diff --git a/man/deb-override.pod b/man/deb-override.pod index f7304d262..332a8b524 100644 --- a/man/deb-override.pod +++ b/man/deb-override.pod @@ -33,7 +33,8 @@ some is managed centrally by the distribution czars rather than by the maintainer in order to offer some global consistency. This information is found in the override file. -The override file has a simple whitespace-delimited format. Comments are +The override file has a simple whitespace-delimited format. +Comments are allowed (denoted with a B<#>). @@ -47,13 +48,15 @@ I
=back I -is the name of the package. Entries in the override file for packages +is the name of the package. +Entries in the override file for packages not found in the tree of binary packages are ignored. I and I
-correspond to the respective control fields available in the .deb. The +correspond to the respective control fields available in the .deb. +The allowed values are specific to each distribution archive. I, diff --git a/man/deb-shlibs.pod b/man/deb-shlibs.pod index bb912c565..3bc9ae5da 100644 --- a/man/deb-shlibs.pod +++ b/man/deb-shlibs.pod @@ -31,8 +31,10 @@ B, BIB<.shlibs>, B B files map shared library names and versions (I) -to dependencies suitable for a package control file. There is one -entry per line. Blank lines are B allowed. Lines beginning +to dependencies suitable for a package control file. +There is one entry per line. +Blank lines are B allowed. +Lines beginning with a B<#> character are considered commentary, and are ignored. All other lines must have the format: @@ -46,7 +48,8 @@ I =back The I and I fields are whitespace-delimited, -but the I field extends to the end of the line. The +but the I field extends to the end of the line. +The I field is optional and normally not needed. The I field has the same syntax as the B diff --git a/man/deb-split.pod b/man/deb-split.pod index 93f416c1b..b1cd1ae74 100644 --- a/man/deb-split.pod +++ b/man/deb-split.pod @@ -36,7 +36,8 @@ The file is an B archive with a magic value of BarchE>. The file names might contain a trailing slash (since dpkg 1.15.6). The first member is named B and contains a series -of lines, separated by newlines. Currently eight lines are present: +of lines, separated by newlines. +Currently eight lines are present: =over @@ -81,14 +82,17 @@ format version number to be increased and additional lines to be present, and should ignore these if this is the case. If the major format version number has changed, an incompatible change has -been made and the program should stop. If it has not, then the program should +been made and the program should stop. +If it has not, then the program should be able to safely continue, unless it encounters an unexpected member in the archive (except at the end), as described below. The second, last required member is named BI, where I -denotes the part number. It contains the raw part data. +denotes the part number. +It contains the raw part data. -These members must occur in this exact order. Current implementations +These members must occur in this exact order. +Current implementations should ignore any additional members after BI. Further members may be defined in the future, and (if possible) will be placed after these two. diff --git a/man/deb-src-control.pod b/man/deb-src-control.pod index 65dd027d4..5f3a0fd86 100644 --- a/man/deb-src-control.pod +++ b/man/deb-src-control.pod @@ -44,11 +44,13 @@ A field starts with a field name, such as B or B
(case insensitive), followed by a colon, the body of the field (case sensitive unless stated otherwise) and a newline. Multi-line fields are also allowed, but each supplementary line, without a -field name, should start with at least one space. The content of the multi-line +field name, should start with at least one space. +The content of the multi-line fields is generally joined to a single line by the tools (except in the case of the B -field, see below). To insert empty lines into a multi-line +field, see below). +To insert empty lines into a multi-line field, insert a dot after the space. Lines starting with a ‘B<#>’ are treated as comments. @@ -59,9 +61,11 @@ Lines starting with a ‘B<#>’ are treated as comments. =item B I (required) The value of this field is the name of the source package, and should -match the name of the source package in the debian/changelog file. A package +match the name of the source package in the debian/changelog file. +A package name must consist only of lowercase letters (a-z), digits (0-9), plus (+) and -minus (-) signs, and periods (.). Package names must be at least two characters +minus (-) signs, and periods (.). +Package names must be at least two characters long and must start with a lowercase alphanumeric character (a-z0-9). =item B I (recommended) @@ -98,9 +102,11 @@ The upstream project home page URL. =item B I -The I of the bug tracking system for this package. The current +The I of the bug tracking system for this package. +The current used format is IB<://>I, like -B. This field is usually not needed. +B. +This field is usually not needed. =item B B|B|I @@ -169,9 +175,11 @@ B or copied literally to the source control file. =item B I The I of the Version Control System repository used to maintain this -package. Currently supported are B, B (Bazaar), B, +package. +Currently supported are B, B (Bazaar), B, B, B, B (Mercurial), B (Monotone) and -B (Subversion). Usually this field points to the latest version +B (Subversion). +Usually this field points to the latest version of the package, such as the main branch or the trunk. =item B I @@ -181,7 +189,8 @@ repository. =item B I -The name of the distribution this package is originating from. This field is +The name of the distribution this package is originating from. +This field is usually not needed. =item B I
@@ -218,15 +227,17 @@ package. =item B I Same as B, but they are only needed when building the -architecture dependent packages. The B are also -installed in this case. This field is supported since dpkg 1.16.4; in +architecture dependent packages. +The B are also installed in this case. +This field is supported since dpkg 1.16.4; in order to build with older dpkg versions, B should be used instead. =item B I Same as B, but they are only needed when building the -architecture independent packages. The B are also +architecture independent packages. +The B are also installed in this case. =item B I @@ -241,7 +252,8 @@ used for source-only builds. =item B I Same as B, but only when building the architecture -dependent packages. This field is supported since dpkg 1.16.4; in +dependent packages. +This field is supported since dpkg 1.16.4; in order to build with older dpkg versions, B should be used instead. @@ -309,11 +321,14 @@ equal to, ‘B=>’ for less than or equal to, and ‘B<=>’ for equal to. An architecture specification consists of one or more architecture names, -separated by whitespace. Exclamation marks may be prepended to each of the +separated by whitespace. +Exclamation marks may be prepended to each of the names, meaning “NOT”. A restriction formula consists of one or more restriction lists, separated -by whitespace. Each restriction list is enclosed in angle brackets. Items +by whitespace. +Each restriction list is enclosed in angle brackets. +Items in the restriction list are build profile names, separated by whitespace and can be prefixed with an exclamation mark, meaning “NOT”. A restriction formula represents a disjunctive normal form expression. @@ -321,7 +336,8 @@ A restriction formula represents a disjunctive normal form expression. Note that dependencies on packages in the B set can be omitted and that declaring build conflicts against them is -impossible. A list of these packages is in the build-essential package. +impossible. +A list of these packages is in the build-essential package. =head1 BINARY FIELDS @@ -336,7 +352,8 @@ source package. =item B I (required) -This field is used to name the binary package name. The same restrictions as +This field is used to name the binary package name. +The same restrictions as to a source package name apply. =item B B|B|I @@ -348,14 +365,18 @@ More types might be added in the future. =item B I|B|B (required) -The architecture specifies on which type of hardware this package runs. For +The architecture specifies on which type of hardware this package runs. +For packages that run on all architectures, use the B -value. For packages that are architecture independent, such as shell and Perl +value. +For packages that are architecture independent, such as shell and Perl scripts or documentation, use the B -value. To restrict the packages to a certain set of architectures, specify the -architecture names, separated by a space. It's also possible to put +value. +To restrict the packages to a certain set of architectures, specify the +architecture names, separated by a space. +It's also possible to put architecture wildcards in that list (see L for more information about them). @@ -414,7 +435,8 @@ package. =item B I -These fields declare relationships between packages. They are discussed in +These fields declare relationships between packages. +They are discussed in the L manual page. @@ -438,8 +460,9 @@ L, followed by zero or more of the letters B and a hyphen. @@ -463,13 +486,15 @@ L. =back Note that the B[B]B<-> prefixes are stripped when the -fields are copied over to the output files. A field B +fields are copied over to the output files. +A field B will appear as B in the changes file and will not appear in the binary or source package control files. Take into account that these user-defined fields will be using the global namespace, which might at some point in the future collide with officially -recognized fields. To avoid such potential situation you can prefix those +recognized fields. +To avoid such potential situation you can prefix those fields with B, such as B. =head1 EXAMPLE diff --git a/man/deb-src-symbols.pod b/man/deb-src-symbols.pod index bcd21255b..0e5428d81 100644 --- a/man/deb-src-symbols.pod +++ b/man/deb-src-symbols.pod @@ -38,7 +38,8 @@ see L. =head2 Comments -Comments are supported in template symbol files. Any line with ‘#’ as +Comments are supported in template symbol files. +Any line with ‘#’ as the first character is a comment except if it starts with ‘#include’ (see section L). Lines starting with ‘#MISSING:’ are special comments documenting @@ -48,28 +49,37 @@ symbols that have disappeared. In some rare cases, the name of the library varies between architectures. To avoid hardcoding the name of the package in the symbols file, you can -use the marker I<#PACKAGE#>. It will be replaced by the real package -name during installation of the symbols files. Contrary to the +use the marker I<#PACKAGE#>. +It will be replaced by the real package name during installation of the +symbols files. +Contrary to the I<#MINVER#> marker, I<#PACKAGE#> will never appear in a symbols file inside a binary package. =head2 Using symbol tags -Symbol tagging is useful for marking symbols that are special in some way. Any -symbol can have an arbitrary number of tags associated with it. While all tags are +Symbol tagging is useful for marking symbols that are special in some way. +Any symbol can have an arbitrary number of tags associated with it. +While all tags are parsed and stored, only some of them are understood by -B and trigger special handling of the symbols. See +B and trigger special handling of the symbols. +See subsection L for reference of these tags. Tag specification comes right before the symbol name (no whitespace is allowed -in between). It always starts with an opening bracket B<(>, ends with a -closing bracket B<)> and must contain at least one tag. Multiple tags are -separated by the B<|> character. Each tag can optionally have a value which -is separated form the tag name by the B<=> character. Tag names and values +in between). +It always starts with an opening bracket B<(>, +ends with a closing bracket B<)> and must contain at least one tag. +Multiple tags are separated by the B<|> character. +Each tag can optionally have a value which is separated form the tag name +by the B<=> character. +Tag names and values can be arbitrary strings except they cannot contain any of the special B<)> -B<|> B<=> characters. Symbol names following a tag specification can +B<|> B<=> characters. +Symbol names following a tag specification can optionally be quoted with either B<'> or B<"> characters to allow -whitespaces in them. However, if there are no tags specified for the symbol, +whitespaces in them. +However, if there are no tags specified for the symbol, quotes are treated as part of the symbol name which continues up until the first space. @@ -79,18 +89,22 @@ first space. The first symbol in the example is named I and has two tags: I with value I and I -that has no value. The second symbol named I is -only tagged with the tag named I. The last symbol is an +that has no value. +The second symbol named I is only tagged with the +tag named I. +The last symbol is an example of the normal untagged symbol. Since symbol tags are an extension of the L format, they can only be part of the symbols files used in source packages (those files should then be seen as templates used to build the symbols files that are -embedded in binary packages). When +embedded in binary packages). +When B is called without the B<-t> option, it will output symbols files compatible to the L format: it fully processes symbols according to the requirements of their standard tags -and strips all tags from the output. On the contrary, in template mode +and strips all tags from the output. +On the contrary, in template mode (B<-t>) all symbols and their tags (both standard and unknown ones) are kept in the output and are written in their original form as they were loaded. @@ -102,17 +116,21 @@ loaded. =item B A symbol marked as optional can disappear from the library at any time and that -will never cause B to fail. However, disappeared optional +will never cause B to fail. +However, disappeared optional symbols will continuously appear as MISSING in the diff in each new package -revision. This behavior serves as a reminder for the maintainer that such a -symbol needs to be removed from the symbol file or readded to the library. When +revision. +This behavior serves as a reminder for the maintainer that such a +symbol needs to be removed from the symbol file or readded to the library. +When the optional symbol, which was previously declared as MISSING, suddenly reappears in the next revision, it will be upgraded back to the “existing” status with its minimum version unchanged. This tag is useful for symbols which are private where their disappearance do -not cause ABI breakage. For example, most of C++ template instantiations fall -into this category. Like any other tag, this one may also have an arbitrary +not cause ABI breakage. +For example, most of C++ template instantiations fall into this category. +Like any other tag, this one may also have an arbitrary value: it could be used to indicate why the symbol is considered optional. =item BI @@ -122,14 +140,17 @@ value: it could be used to indicate why the symbol is considered optional. =item BI These tags allow one to restrict the set of architectures where the symbol -is supposed to exist. The B and B tags -are supported since dpkg 1.18.0. When the symbols list is updated with +is supposed to exist. +The B and B tags are supported since dpkg 1.18.0. +When the symbols list is updated with the symbols discovered in the library, all arch-specific symbols which do not concern -the current host architecture are treated as if they did not exist. If an +the current host architecture are treated as if they did not exist. +If an arch-specific symbol matching the current host architecture does not exist in the library, normal procedures for missing symbols apply and it may -cause B to fail. On the other hand, if the +cause B to fail. +On the other hand, if the arch-specific symbol is found when it was not supposed to exist (because the current host architecture is not listed in the tag or does not match the endianness and bits), it is made arch neutral (i.e. the arch, arch-bits @@ -138,13 +159,15 @@ to this change), but it is not considered as new. When operating in the default non-template mode, among arch-specific symbols only those that match the current host architecture are written to the -symbols file. On the contrary, all arch-specific symbols (including those +symbols file. +On the contrary, all arch-specific symbols (including those from foreign arches) are always written to the symbol file when operating in template mode. The format of I is the same as the one used in the B field of I (except the enclosing -square brackets []). For example, the first symbol from the list below +square brackets []). +For example, the first symbol from the list below will be considered only on alpha, any-amd64 and ia64 architectures, the second only on linux architectures, while the third one anywhere except on armel. @@ -183,17 +206,20 @@ supported since dpkg 1.15.3). =item B -Denotes I symbol pattern. See L subsection +Denotes I symbol pattern. +See L subsection below. =item B -Denotes I (symbol version) symbol pattern. See L (symbol version) symbol pattern. +See L subsection below. =item B -Denotes I symbol pattern. See L subsection +Denotes I symbol pattern. +See L subsection below. =back @@ -201,25 +227,36 @@ below. =head2 Using symbol patterns Unlike a standard symbol specification, a pattern may cover multiple real -symbols from the library. B will attempt to match each +symbols from the library. +B will attempt to match each pattern against each real symbol that does I have a specific symbol -counterpart defined in the symbol file. Whenever the first matching pattern is +counterpart defined in the symbol file. +Whenever the first matching pattern is found, all its tags and properties will be used as a basis specification of the -symbol. If none of the patterns matches, the symbol will be considered as new. +symbol. +If none of the patterns matches, the symbol will be considered as new. -A pattern is considered lost if it does not match any symbol in the library. By +A pattern is considered lost if it does not match any symbol in the library. +By default this will trigger a B failure under B<-c1> or -higher level. However, if the failure is undesired, the pattern may be marked -with the I tag. Then if the pattern does not match anything, it -will only appear in the diff as MISSING. Moreover, like any symbol, the pattern -may be limited to the specific architectures with the I tag. Please +higher level. +However, if the failure is undesired, the pattern may be marked with the +I tag. +Then if the pattern does not match anything, +it will only appear in the diff as MISSING. +Moreover, like any symbol, +the pattern may be limited to the specific architectures with the I tag. +Please refer to L subsection above for more information. Patterns are an extension of the L format hence they are -only valid in symbol file templates. Pattern specification syntax is not any -different from the one of a specific symbol. However, symbol name part of the +only valid in symbol file templates. +Pattern specification syntax is not any different from the one of a +specific symbol. +However, symbol name part of the specification serves as an expression to be matched against I -of the real symbol. In order to distinguish among different pattern types, a +of the real symbol. +In order to distinguish among different pattern types, a pattern will typically be tagged with a special tag. At the moment, B supports three basic pattern types: @@ -228,14 +265,19 @@ At the moment, B supports three basic pattern types: =item B -This pattern is denoted by the I tag. It matches only C++ symbols by -their demangled symbol name (as emitted by L utility). This +This pattern is denoted by the I tag. +It matches only C++ symbols by their demangled symbol name +(as emitted by L utility). +This pattern is very handy for matching symbols which mangled names might vary -across different architectures while their demangled names remain the same. One +across different architectures while their demangled names remain the same. +One group of such symbols is I which have architecture -specific offsets embedded in their mangled names. A common instance of this +specific offsets embedded in their mangled names. +A common instance of this case is a virtual destructor which under diamond inheritance needs a -non-virtual thunk symbol. For example, even if _ZThn8_N3NSB6ClassDD1Ev@Base on +non-virtual thunk symbol. +For example, even if _ZThn8_N3NSB6ClassDD1Ev@Base on 32-bit architectures will probably be _ZThn16_N3NSB6ClassDD1Ev@Base on 64-bit ones, it can be matched with a single I pattern: @@ -249,19 +291,24 @@ The demangled name above can be obtained by executing the following command: $ echo '_ZThn8_N3NSB6ClassDD1Ev@Base' | c++filt Please note that while mangled name is unique in the library by definition, -this is not necessarily true for demangled names. A couple of distinct real -symbols may have the same demangled name. For example, that's the case with +this is not necessarily true for demangled names. +A couple of distinct real symbols may have the same demangled name. +For example, that's the case with non-virtual thunk symbols in complex inheritance configurations or with most constructors and destructors (since g++ typically generates two real symbols -for them). However, as these collisions happen on the ABI level, they should +for them). +However, as these collisions happen on the ABI level, they should not degrade quality of the symbol file. =item B -This pattern is denoted by the I tag. Well maintained libraries have +This pattern is denoted by the I tag. +Well maintained libraries have versioned symbols where each version corresponds to the upstream version where -the symbol got added. If that's the case, you can use a I pattern to -match any symbol associated to the specific version. For example: +the symbol got added. +If that's the case, you can use a I pattern to +match any symbol associated to the specific version. +For example: libc.so.6 libc6 #MINVER# (symver)GLIBC_2.0 2.0 @@ -271,22 +318,26 @@ match any symbol associated to the specific version. For example: All symbols associated with versions GLIBC_2.0 and GLIBC_2.7 will lead to minimal version of 2.0 and 2.7 respectively with the exception of the symbol -access@GLIBC_2.0. The latter will lead to a minimal dependency on libc6 version +access@GLIBC_2.0. +The latter will lead to a minimal dependency on libc6 version 2.2 despite being in the scope of the "(symver)GLIBC_2.0" pattern because specific symbols take precedence over patterns. Please note that while old style wildcard patterns (denoted by "*@version" in the symbol name field) are still supported, they have been deprecated by new -style syntax "(symver|optional)version". For example, "*@GLIBC_2.0 2.0" should +style syntax "(symver|optional)version". +For example, "*@GLIBC_2.0 2.0" should be written as "(symver|optional)GLIBC_2.0 2.0" if the same behavior is needed. =item B -Regular expression patterns are denoted by the I tag. They match by -the perl regular expression specified in the symbol name field. A regular +Regular expression patterns are denoted by the I tag. +They match by the perl regular expression specified in the symbol name field. +A regular expression is matched as it is, therefore do not forget to start it with the I<^> character or it may match any part of the real symbol -I string. For example: +I string. +For example: libdummy.so.1 libdummy1 #MINVER# (regex)"^mystack_.*@Base$" 1.0 @@ -299,40 +350,48 @@ names and matches will inherit I tag from the pattern. =back -Basic patterns listed above can be combined where it makes sense. In that case, -they are processed in the order in which the tags are specified. For example, +Basic patterns listed above can be combined where it makes sense. +In that case, they are processed in the order in which the tags are specified. +For example, both: (c++|regex)"^NSA::ClassA::Private::privmethod\d\(int\)@Base" 1.0 (regex|c++)N3NSA6ClassA7Private11privmethod\dEi@Base 1.0 will match symbols "_ZN3NSA6ClassA7Private11privmethod1Ei@Base" and -"_ZN3NSA6ClassA7Private11privmethod2Ei@Base". When matching the first pattern, +"_ZN3NSA6ClassA7Private11privmethod2Ei@Base". +When matching the first pattern, the raw symbol is first demangled as C++ symbol, then the demangled name is -matched against the regular expression. On the other hand, when matching the +matched against the regular expression. +On the other hand, when matching the second pattern, regular expression is matched against the raw symbol name, then -the symbol is tested if it is C++ one by attempting to demangle it. A failure +the symbol is tested if it is C++ one by attempting to demangle it. +A failure of any basic pattern will result in the failure of the whole pattern. Therefore, for example, "__N3NSA6ClassA7Private11privmethod\dEi@Base" will not match either of the patterns because it is not a valid C++ symbol. In general, all patterns are divided into two groups: aliases (basic I and I) and generic patterns (I, all combinations of -multiple basic patterns). Matching of basic alias-based patterns is fast (O(1)) +multiple basic patterns). +Matching of basic alias-based patterns is fast (O(1)) while generic patterns are O(N) (N - generic pattern count) for each symbol. Therefore, it is recommended not to overuse generic patterns. When multiple patterns match the same real symbol, aliases (first I, -then I) are preferred over generic patterns. Generic patterns are +then I) are preferred over generic patterns. +Generic patterns are matched in the order they are found in the symbol file template until the first -success. Please note, however, that manual reordering of template file entries +success. +Please note, however, that manual reordering of template file entries is not recommended because B generates diffs based on the alphanumerical order of their names. =head2 Using includes When the set of exported symbols differ between architectures, it may become -inefficient to use a single symbol file. In those cases, an include directive +inefficient to use a single symbol file. +In those cases, an include directive may prove to be useful in a couple of ways: =over @@ -352,7 +411,8 @@ The include directive may also be tagged like any symbol: (tag|...|tagN)#include "file-to-include" As a result, all symbols included from I will be considered -to be tagged with I ... I by default. You can use this feature +to be tagged with I ... I by default. +You can use this feature to create a common I.symbols file which includes architecture specific symbol files: @@ -364,17 +424,22 @@ specific symbol files: =back The symbols files are read line by line, and include directives are processed -as soon as they are encountered. This means that the content of the included +as soon as they are encountered. +This means that the content of the included file can override any content that appeared before the include directive and that any content after the directive can override anything contained in the -included file. Any symbol (or even another #include directive) in the included +included file. +Any symbol (or even another #include directive) in the included file can specify additional tags or override values of the inherited tags in -its tag specification. However, there is no way for the symbol to remove +its tag specification. +However, there is no way for the symbol to remove any of the inherited tags. An included file can repeat the header line containing the SONAME of the -library. In that case, it overrides any header line previously read. -However, in general it's best to avoid duplicating header lines. One way +library. +In that case, it overrides any header line previously read. +However, in general it's best to avoid duplicating header lines. +One way to do it is the following: #include "libsomething1.symbols.common" diff --git a/man/deb-substvars.pod b/man/deb-substvars.pod index cbca016bc..c6fca2975 100644 --- a/man/deb-substvars.pod +++ b/man/deb-substvars.pod @@ -82,13 +82,15 @@ and an empty value is assumed. While variable substitution is done on all control fields, some of those fields are used and needed during the build when the substitution did not -yet occur. That's why you can't use variables in the B, +yet occur. +That's why you can't use variables in the B, B and B fields. Variable substitution happens on the content of the fields after they have been parsed, thus if you want a variable to expand over multiple lines you -do not have to include a space after the newline. This is done implicitly -when the field is output. For example, if the variable +do not have to include a space after the newline. +This is done implicitly when the field is output. +For example, if the variable B<${Description}> is set to "foo is bar.${Newline}foo is great." and if you have the following field: @@ -143,7 +145,8 @@ a binNMU for example; since dpkg 1.13.19). =item B -The source package version (from the changelog file). This variable is now +The source package version (from the changelog file). +This variable is now B and emits an error when used as its meaning is different from its function, please use the B or B as appropriate. @@ -160,9 +163,11 @@ B field, if it exists (since dpkg 1.19.0). =item B -The approximate total size of the package's installed files. This value is +The approximate total size of the package's installed files. +This value is copied into the corresponding control file field; setting it will modify -the value of that field. If this variable is not set +the value of that field. +If this variable is not set B will compute the default value by accumulating the size of each regular file and symlink rounded to 1 KiB used units, and a baseline of 1 KiB for @@ -176,7 +181,8 @@ or less space than the specified in this field. =item B -Additional disk space used when the package is installed. If this +Additional disk space used when the package is installed. +If this variable is set its value is added to that of the B variable (whether set explicitly or using the default value) before it @@ -197,7 +203,8 @@ These variables are only available when generating binary control files. The value of the output field I -(which must be given in the canonical capitalization). Setting these +(which must be given in the canonical capitalization). +Setting these variables has no effect other than on places where they are expanded explicitly. @@ -206,7 +213,8 @@ explicitly. The B<.changes> file format version generated by this version of the source packaging -scripts. If you set this variable the contents of the +scripts. +If you set this variable the contents of the B field in the B<.changes> diff --git a/man/deb-symbols.pod b/man/deb-symbols.pod index 0e9a0ad71..ca9b086b3 100644 --- a/man/deb-symbols.pod +++ b/man/deb-symbols.pod @@ -44,7 +44,8 @@ Z<> I I [I] The I is exactly the value of the SONAME field -as exported by L. A I is a +as exported by L. +A I is a dependency where I<#MINVER#> is dynamically replaced either by a version check like “(E= I)” or by nothing (if an unversioned dependency is deemed sufficient). @@ -53,13 +54,15 @@ Each exported I (listed as I@I, with I being “Base” if the library is not versioned) is associated to a I of its dependency template (the main dependency template is always used and will end up being combined with the dependency -template referenced by I if present). The +template referenced by I if present). +The first alternative dependency template is numbered 1, the second one 2, etc. Each column is separated by exactly a single whitespace. Each entry for a library can also have some fields of meta-information. -Those fields are stored on lines starting with an asterisk. Currently, +Those fields are stored on lines starting with an asterisk. +Currently, the only valid fields are: =over @@ -85,7 +88,8 @@ It indicates what internal symbol groups should be ignored, as a whitespace separated list, so that the symbols contained in those groups get included in the output file (since dpkg 1.20.1). This should only be necessary for toolchain -packages providing those internal symbols. The available groups are +packages providing those internal symbols. +The available groups are system dependent, for ELF and GNU-based systems these are B and B. diff --git a/man/deb-triggers.pod b/man/deb-triggers.pod index c54a423b5..bdffce46a 100644 --- a/man/deb-triggers.pod +++ b/man/deb-triggers.pod @@ -33,7 +33,8 @@ A package declares its relationship to some trigger(s) by including a I file in its control archive (i.e. I during package creation). -This file contains directives, one per line. Leading and trailing whitespace +This file contains directives, one per line. +Leading and trailing whitespace and everything after the first B<#> on any line will be trimmed, and empty lines will be ignored. @@ -47,7 +48,8 @@ The trigger control directives currently supported are: =item B I -Specifies that the package is interested in the named trigger. All +Specifies that the package is interested in the named trigger. +All triggers in which a package is interested must be listed using this directive in the triggers control file. @@ -68,7 +70,8 @@ by the trigger is not crucial. =item B I Arranges that changes to this package's state will activate the -specified trigger. The trigger will be activated at the start of +specified trigger. +The trigger will be activated at the start of the following operations: unpack, configure, remove (including for the benefit of a conflicting package), purge and deconfigure. @@ -81,7 +84,8 @@ by the trigger is not crucial. If this package disappears during the unpacking of another package the trigger will be activated when the disappearance is noted -towards the end of the unpack. Trigger processing, and transition +towards the end of the unpack. +Trigger processing, and transition from triggers-awaited to installed, does not cause activations. In the case of unpack, triggers mentioned in both the old and new versions of the package will be activated. diff --git a/man/deb-version.pod b/man/deb-version.pod index c0475a9ef..c8368dad0 100644 --- a/man/deb-version.pod +++ b/man/deb-version.pod @@ -31,14 +31,16 @@ deb-version - Debian package version number format =head1 DESCRIPTION Version numbers as used for Debian binary and source packages -consist of three components. These are: +consist of three components. +These are: =over =item I -This is a single (generally small) unsigned integer. It -may be omitted, in which case zero is assumed. If it is +This is a single (generally small) unsigned integer. +It may be omitted, in which case zero is assumed. +If it is omitted then the I may not contain any colons. @@ -48,10 +50,12 @@ previous version numbering schemes, to be left behind. =item I -This is the main part of the version number. It is +This is the main part of the version number. +It is usually the version number of the original (“upstream”) package from which the I<.deb> file has been made, -if this is applicable. Usually this will be in the same +if this is applicable. +Usually this will be in the same format as that specified by the upstream author(s); however, it may need to be reformatted to fit into the package management system's format and comparison @@ -59,14 +63,16 @@ scheme. The comparison behavior of the package management system with respect to the I is -described below. The I +described below. +The I portion of the version number is mandatory. The I may contain only alphanumerics (“A-Za-z0-9”) and the characters B<.> B<+> B<-> B<:> B<~> (full stop, plus, hyphen, colon, tilde) and should -start with a digit. If there is no +start with a digit. +If there is no I then hyphens are not allowed; if there is no I then colons are not allowed. @@ -74,7 +80,8 @@ allowed. =item I This part of the version number specifies the version of -the Debian package based on the upstream version. It +the Debian package based on the upstream version. +It may contain only alphanumerics and the characters B<+> B<.> B<~> (plus, full stop, tilde) and is @@ -95,7 +102,8 @@ I is increased. Dpkg will break the version number apart at the last hyphen in the string (if there is one) to determine the I and -I. The absence of a +I. +The absence of a I compares earlier than the presence of one (but note that the I is the least significant part of the version number). @@ -111,17 +119,20 @@ same algorithm: The strings are compared from left to right. First the initial part of each string consisting entirely of -non-digit characters is determined. These two parts (one of -which may be empty) are compared lexically. If a difference -is found it is returned. The lexical comparison is a +non-digit characters is determined. +These two parts (one of which may be empty) are compared lexically. +If a difference is found it is returned. +The lexical comparison is a comparison of ASCII values modified so that all the letters sort earlier than all the non-letters and so that a tilde -sorts before anything, even the end of a part. For example, +sorts before anything, even the end of a part. +For example, the following parts are in sorted order: ‘~~’, ‘~~a’, ‘~’, the empty part, ‘a’. Then the initial part of the remainder of each string which -consists entirely of digit characters is determined. The +consists entirely of digit characters is determined. +The numerical values of these two parts are compared, and any difference found is returned as the result of the comparison. For these purposes an empty string (which can only occur at @@ -134,7 +145,8 @@ difference is found or both strings are exhausted. Note that the purpose of epochs is to allow us to leave behind mistakes in version numbering, and to cope with situations -where the version numbering scheme changes. It is +where the version numbering scheme changes. +It is B intended to cope with version numbers containing strings of letters which the package management system cannot interpret (such as ‘ALPHA’ or ‘pre-’), or with diff --git a/man/deb.pod b/man/deb.pod index 3df1efc52..ae939d080 100644 --- a/man/deb.pod +++ b/man/deb.pod @@ -32,7 +32,8 @@ IB<.deb> The B<.deb> -format is the Debian binary package file format. It is understood +format is the Debian binary package file format. +It is understood since dpkg 0.93.76, and is generated by default since dpkg 1.2.0 and 1.1.1elf (i386/ELF builds). @@ -65,7 +66,8 @@ negative timestamps, and 63-bit UID, GID and device numbers. The first member is named B -and contains a series of lines, separated by newlines. Currently only +and contains a series of lines, separated by newlines. +Currently only one line is present, the format version number, B<2.0> at the time this manual page was written. @@ -74,7 +76,8 @@ minor number to be increased and new lines to be present, and should ignore these if this is the case. If the major number has changed, an incompatible change has been made -and the program should stop. If it has not, then the program should +and the program should stop. +If it has not, then the program should be able to safely continue, unless it encounters an unexpected member in the archive (except at the end), as described below. @@ -111,11 +114,13 @@ zstd (with B<.zst> extension, supported since dpkg 1.21.18), bzip2 (with B<.bz2> extension, supported since dpkg 1.10.24) or lzma (with B<.lzma> extension, supported since dpkg 1.13.25). -These members must occur in this exact order. Current implementations +These members must occur in this exact order. +Current implementations should ignore any additional members after B. Further members may be defined in the future, and (if possible) will be -placed after these three. Any additional members that may need to be +placed after these three. +Any additional members that may need to be inserted after B and before diff --git a/man/dpkg-architecture.pod b/man/dpkg-architecture.pod index d9e58f208..cb2f362f9 100644 --- a/man/dpkg-architecture.pod +++ b/man/dpkg-architecture.pod @@ -41,12 +41,15 @@ L, and cannot be set at the command line. You can specify the host architecture by providing one or both of the options B<--host-arch> and B<--host-type>, otherwise the B variable -is used if set (and B<--force> not being specified). The default is +is used if set (and B<--force> not being specified). +The default is determined by an external call to L, or the same as the build architecture if B or gcc are both not -available. One out of B<--host-arch> and B<--host-type> is +available. +One out of B<--host-arch> and B<--host-type> is sufficient, the value of the -other will be set to a usable default. Indeed, it is often better to only +other will be set to a usable default. +Indeed, it is often better to only specify one, because B will warn you if your choice does not match the default. @@ -57,7 +60,8 @@ does not match the default. =item B<-l>, B<--list> Print the environment variables, one each line, in the format -I. This is the default action. +I. +This is the default action. =item B<-e>, B<--equal> I @@ -81,7 +85,8 @@ Print the value of a single variable. =item B<-s>, B<--print-set> -Print an export command. This can be used to set the environment variables +Print an export command. +This can be used to set the environment variables using the POSIX shell or make B, depending on the output format. =item B<-u>, B<--print-unset> @@ -141,12 +146,14 @@ the specified architecture wildcard (since dpkg 1.17.14). =item B<-B>, B<--match-bits> I Restrict the architectures listed by B<--list-known> to ones with the -specified CPU bits (since dpkg 1.17.14). Either B<32> or B<64>. +specified CPU bits (since dpkg 1.17.14). +Either B<32> or B<64>. =item B<-E>, B<--match-endian> I Restrict the architectures listed by B<--list-known> to ones with the -specified endianness (since dpkg 1.17.14). Either B or B. +specified endianness (since dpkg 1.17.14). +Either B or B. =item B<--print-format> I @@ -157,7 +164,8 @@ Sets the output format for B<--print-set> and B<--print-unset> Values set by existing environment variables with the same name as used by the scripts are honored (i.e. used by B), except if -this force flag is present. This allows the user +this force flag is present. +This allows the user to override a value even when the call to B is buried in some other script (for example L). @@ -185,7 +193,8 @@ and to build (or run emulated) code for the target architecture. =item Debian architecture The Debian architecture string, which specifies the binary tree in the -FTP archive. Examples: i386, sparc, hurd-i386. +FTP archive. +Examples: i386, sparc, hurd-i386. =item Debian architecture tuple @@ -386,7 +395,8 @@ paths (since dpkg 1.17.14). =head2 Architecture tables All these files have to be present for B to -work. Their location can be overridden at runtime with the environment +work. +Their location can be overridden at runtime with the environment variable B. These tables contain a format B pseudo-field on their first line to mark their format, so that parsers can check if they understand @@ -431,7 +441,8 @@ B outputs (since dpkg 1.16.1). =head1 EXAMPLES B accepts the B<-a> option and passes it to -B. Other examples: +B. +Other examples: =over @@ -465,10 +476,13 @@ Check if the current or specified host architecture is a Linux system: =head2 Usage in debian/rules The environment variables set by B are passed to -I as make variables (see make documentation). However, +I as make variables (see make documentation). +However, you should not rely on them, as this breaks manual invocation of the -script. Instead, you should always initialize them using -B with the B<-q> option. Here are some examples, +script. +Instead, you should always initialize them using +B with the B<-q> option. +Here are some examples, which also show how you can improve the cross compilation support in your package: diff --git a/man/dpkg-buildflags.pod b/man/dpkg-buildflags.pod index 54e15a27b..6673a65ec 100644 --- a/man/dpkg-buildflags.pod +++ b/man/dpkg-buildflags.pod @@ -86,7 +86,8 @@ Since dpkg 1.16.1. =back The configuration files can contain comments on lines starting with a hash -(#). Empty lines are also ignored. +(#). +Empty lines are also ignored. This program was introduced in dpkg 1.15.7. @@ -96,14 +97,17 @@ This program was introduced in dpkg 1.15.7. =item B<--dump> -Print to standard output all compilation flags and their values. It prints +Print to standard output all compilation flags and their values. +It prints one flag per line separated from its value by an equal sign -(“I=I”). This is the default action. +(“I=I”). +This is the default action. =item B<--list> Print the list of flags supported by the current vendor -(one per line). See the L section for more +(one per line). +See the L section for more information about them. =item B<--status> @@ -114,29 +118,34 @@ current vendor, state of all feature flags. Also print the resulting compiler flags with their origin. This is intended to be run from B, so that the build log -keeps a clear trace of the build flags used. This can be useful to diagnose +keeps a clear trace of the build flags used. +This can be useful to diagnose problems related to them. =item B<--export=>I Print to standard output commands that can be used to export all the -compilation flags for some particular tool. If the I value is not -given, B is assumed. Only compilation flags starting with an +compilation flags for some particular tool. +If the I value is not given, B is assumed. +Only compilation flags starting with an upper case character are included, others are assumed to not be suitable -for the environment. Supported formats: +for the environment. +Supported formats: =over =item B Shell commands to set and export all the compilation flags in the -environment. The flag values are quoted so the output is ready for +environment. +The flag values are quoted so the output is ready for evaluation by a shell. =item B Arguments to pass to a build program's command line to use all the -compilation flags (since dpkg 1.17.0). The flag values are quoted in +compilation flags (since dpkg 1.17.0). +The flag values are quoted in shell syntax. =item B @@ -146,20 +155,23 @@ This is a legacy alias for B. =item B Make directives to set and export all the compilation flags in the -environment. Output can be written to a Makefile fragment and +environment. +Output can be written to a Makefile fragment and evaluated using an B directive. =back =item B<--get> I -Print the value of the flag on standard output. Exits with 0 +Print the value of the flag on standard output. +Exits with 0 if the flag is known otherwise exits with 1. =item B<--origin> I -Print the origin of the value that is returned by B<--get>. Exits -with 0 if the flag is known otherwise exits with 1. The origin can be one +Print the origin of the value that is returned by B<--get>. +Exits with 0 if the flag is known otherwise exits with 1. +The origin can be one of the following values: =over @@ -316,7 +328,8 @@ objects (if the linker is called directly, then B<-Wl> and B<,> -have to be stripped from these options). Default value: empty. +have to be stripped from these options). +Default value: empty. =item B @@ -530,7 +543,8 @@ B, B and B. This setting (since dpkg 1.18.0; disabled by default) adds B<-fsanitize=leak> to -B. It gets automatically disabled if either the B
+B. +It gets automatically disabled if either the B
or the B features are enabled, as they imply it. =item B @@ -558,7 +572,8 @@ B<-Wformat -Werror=format-security> to B, B, B and B. This will warn about improper format string uses, and will fail when format functions are used in a way -that represent possible security problems. At present, this warns about +that represent possible security problems. +At present, this warns about calls to B and B functions where the format string is not a string literal and there are no format arguments, as in B instead of B @@ -569,16 +584,20 @@ input and contains ‘%n’. This setting (since dpkg 1.16.1; enabled by default) adds B<-D_FORTIFY_SOURCE=2> -to B. During code generation the compiler +to B. +During code generation the compiler knows a great deal of information about buffer sizes (where possible), and attempts to replace insecure unlimited length buffer function calls with -length-limited ones. This is especially useful for old, crufty code. +length-limited ones. +This is especially useful for old, crufty code. Additionally, format strings in writable memory that contain ‘%n’ are -blocked. If an application depends on such a format string, it will need +blocked. +If an application depends on such a format string, it will need to be worked around. Note that for this option to have any effect, the source must also -be compiled with B<-O1> or higher. If the environment variable +be compiled with B<-O1> or higher. +If the environment variable B contains I, then B support will be disabled, due to new warnings being issued by glibc 2.16 and later. @@ -590,8 +609,9 @@ is not in use) adds B<-fstack-protector --param=ssp-buffer-size=4> to B, B, B, B, B and B. This adds safety checks against stack -overwrites. This renders many potential code injection attacks into -aborting situations. In the best case this turns code injection +overwrites. +This renders many potential code injection attacks into aborting situations. +In the best case this turns code injection vulnerabilities into denial of service or into non-issues (depending on the application). @@ -634,19 +654,24 @@ whether these are valid at run-time. This setting (since dpkg 1.16.1; enabled by default) adds B<-Wl,-z,relro> -to B. During program load, several ELF memory sections need -to be written to by the linker. This flags the loader to turn these -sections read-only before turning over control to the program. Most -notably this prevents GOT overwrite attacks. If this option is disabled, +to B. +During program load, +several ELF memory sections need to be written to by the linker. +This flags the loader to turn these sections read-only before turning over +control to the program. +Most notably this prevents GOT overwrite attacks. +If this option is disabled, B will become disabled as well. =item B This setting (since dpkg 1.16.1; disabled by default) adds B<-Wl,-z,now> -to B. During program load, all dynamic symbols are resolved, +to B. +During program load, all dynamic symbols are resolved, allowing for the entire PLT to be marked read-only (due to B -above). The option cannot become enabled if B is not enabled. +above). +The option cannot become enabled if B is not enabled. =item B @@ -682,7 +707,8 @@ harder since there are no static locations to bounce off of during a memory corruption attack. PIE is not compatible with B<-fPIC>, so in general care must be taken -when building shared objects. But because the PIE flags emitted get injected +when building shared objects. +But because the PIE flags emitted get injected via gcc specs files, it should always be safe to unconditionally set them regardless of the object type being compiled or linked. @@ -707,7 +733,8 @@ Can be linked into any program and shared library. =back If there is a need to set these flags manually, bypassing the gcc specs -injection, there are several things to take into account. Unconditionally +injection, there are several things to take into account. +Unconditionally and explicitly passing B<-fPIE>, B<-fpie> or B<-pie> to a build-system using libtool is safe as these flags will get stripped when building shared libraries. @@ -716,14 +743,16 @@ might need to make sure that when building the shared libraries B<-fPIC> is always passed last (so that it overrides any previous B<-PIE>) to compilation flags such as B, and B<-shared> is passed last (so that it overrides any previous B<-pie>) to linking flags such as -B. B: This should not be needed with the default +B. +B: This should not be needed with the default gcc specs machinery. Additionally, since PIE is implemented via a general register, some register starved architectures (but not including i386 anymore since optimizations implemented in gcc E= 5) can see performance losses of up to 15% in very text-segment-heavy application workloads; most workloads -see less than 1%. Architectures with more general registers (e.g. amd64) +see less than 1%. +Architectures with more general registers (e.g. amd64) do not see as high a worst-case penalty. =back @@ -732,7 +761,8 @@ do not see as high a worst-case penalty. The compile-time options detailed below can be used to help improve build reproducibility or provide additional warning messages during -compilation. Except as noted below, these are enabled by default for +compilation. +Except as noted below, these are enabled by default for architectures that support them. =over @@ -782,8 +812,10 @@ B: This feature has similar reproducible properties as B. There are 2 sets of environment variables doing the same operations, the first one (DEB_I_I) should never be used within -B. It's meant for any user that wants to rebuild the -source package with different build flags. The second set +B. +It's meant for any user that wants to rebuild the source package with +different build flags. +The second set (DEB_I_MAINT_I) should only be used in B by package maintainers to change the resulting build flags. @@ -919,14 +951,16 @@ You should call B or include B from the B file to obtain the needed build flags to pass to the build system. Note that older versions of B (before dpkg 1.16.1) -exported these flags automatically. However, you should not rely on this, +exported these flags automatically. +However, you should not rely on this, since this breaks manual invocation of B. For packages with autoconf-like build systems, you can pass the relevant options to configure or L directly, as shown above. For other build systems, or when you need more fine-grained control -about which flags are passed where, you can use B<--get>. Or you +about which flags are passed where, you can use B<--get>. +Or you can include B instead, which takes care of calling B and storing the build flags in make variables. diff --git a/man/dpkg-buildpackage.pod b/man/dpkg-buildpackage.pod index ac219bc53..a145d12e9 100644 --- a/man/dpkg-buildpackage.pod +++ b/man/dpkg-buildpackage.pod @@ -33,7 +33,8 @@ B =head1 DESCRIPTION B -is a program that automates the process of building a Debian package. It +is a program that automates the process of building a Debian package. +It consists of the following steps: =over @@ -54,7 +55,8 @@ are satisfied (unless B<-d> or B<--no-check-builddeps> is specified). =item B<3.> If one or more specific targets have been selected with the B<-T> or -B<--target> option, it calls those targets and stops here. Otherwise it +B<--target> option, it calls those targets and stops here. +Otherwise it runs the B hook and calls B to clean the build-tree (unless B<-nc> or B<--no-pre-clean> is specified). @@ -263,19 +265,22 @@ Requires that the target be run with root rights. =item B<-e>I -Passed unchanged to B. See its manual page. +Passed unchanged to B. +See its manual page. =item B<--build-by=>I =item B<--source-by=>I (since dpkg 1.21.10) -Pass as B<-m> to B. See its manual page. +Pass as B<-m> to B. +See its manual page. =item B<--release-by=>I =item B<--changed-by=>I (since dpkg 1.21.10) -Pass as B<-e> to B. See its manual page. +Pass as B<-e> to B. +See its manual page. =item B<-a>, B<--host-arch> I @@ -310,7 +315,8 @@ default GNU system type of the target Debian architecture. Specify the profile(s) we build, as a comma-separated list (since dpkg 1.17.2, long option since dpkg 1.18.8). The default -behavior is to build for no specific profile. Also sets them (as a space +behavior is to build for no specific profile. +Also sets them (as a space separated list) as the B environment variable which allows, for example, B files to use this information for conditional builds. @@ -334,7 +340,8 @@ The I value will override the BI or B option in the B environment variable. Note that the B value will get replaced by the actual number of currently active processors, and as such will not get propagated to any -child process. If the number of online processors cannot be inferred then +child process. +If the number of online processors cannot be inferred then the code will fallback to using serial execution (since dpkg 1.18.15), although this should only happen on exotic and unsupported systems. @@ -464,7 +471,8 @@ as I). Command used to check the B<.changes> file itself and any artifact built referenced in the file (since dpkg 1.17.6). The command should take the B<.changes> pathname -as an argument. This command will usually be B. +as an argument. +This command will usually be B. =item B<--check-option=>I @@ -681,7 +689,8 @@ or other internal heuristics. =item B<-Z>, B<--compression=>I -Passed unchanged to B. See its manual page. +Passed unchanged to B. +See its manual page. =item B<--source-option=>I @@ -822,7 +831,8 @@ standalone should be supported. =item B B is called with the B<-a> and B<-t> -parameters forwarded. Any variable that is output by its B<-s> +parameters forwarded. +Any variable that is output by its B<-s> option is integrated in the build environment. =item B @@ -869,13 +879,15 @@ User configuration file. Between dpkg 1.14.17 and 1.16.1, B exported compiler flags (B, B, B, B and B) with values as returned -by B. This is no longer the case. +by B. +This is no longer the case. =head2 Default build targets B is using the B and -B targets since dpkg 1.16.2. Those targets are thus -mandatory. But to avoid breakages of existing packages, and ease +B targets since dpkg 1.16.2. +Those targets are thus mandatory. +But to avoid breakages of existing packages, and ease the transition, if the source package does not build both architecture independent and dependent binary packages (since dpkg 1.18.8) it will fallback to use the B target if B diff --git a/man/dpkg-checkbuilddeps.pod b/man/dpkg-checkbuilddeps.pod index 201efc7b3..9097e7e32 100644 --- a/man/dpkg-checkbuilddeps.pod +++ b/man/dpkg-checkbuilddeps.pod @@ -32,7 +32,8 @@ B =head1 DESCRIPTION This program checks the installed packages in the system against the build -dependencies and build conflicts listed in the control file. If any are +dependencies and build conflicts listed in the control file. +If any are not met, it displays them and exits with a nonzero return code. By default, B is read, but an alternate control filename @@ -57,7 +58,8 @@ B<-B> when only a source package is to be built. =item B<-B> Ignore B and B -lines. Use when only arch-dep packages will be built, or combine with +lines. +Use when only arch-dep packages will be built, or combine with B<-A> when only a source package is to be built. =item B<-I> @@ -103,7 +105,9 @@ Show the version and exit. =item B If set, it will be used as the active build profile(s) for the package -being built. It is a space separated list of profile names. Overridden +being built. +It is a space separated list of profile names. +Overridden by the B<-P> option. =item B diff --git a/man/dpkg-deb.pod b/man/dpkg-deb.pod index e197917ab..103d6c094 100644 --- a/man/dpkg-deb.pod +++ b/man/dpkg-deb.pod @@ -43,7 +43,8 @@ B by calling B with whatever options you want to pass to -B. B +B. +B will spot that you wanted B and run it for you. @@ -60,11 +61,13 @@ their respective command description. =item B<-b>, B<--build> I [I|I] Creates a debian archive from the filesystem tree stored in -I. I +I. +I must have a B subdirectory, which contains the control information files such -as the control file itself. This directory will +as the control file itself. +This directory will I appear in the binary package's filesystem archive, but instead the files in it will be put in the binary package's control @@ -74,7 +77,8 @@ Unless you specify B<--nocheck>, B will read B -and parse it. It will check the file for syntax errors and other problems, +and parse it. +It will check the file for syntax errors and other problems, and display the name of the binary package being built. B will also check the permissions of the maintainer scripts and other @@ -124,7 +128,8 @@ about each one and exit with status 2. Provides information about a binary package archive in the format specified by the B<--showformat> -argument. The default format displays the package's name and version +argument. +The default format displays the package's name and version on one line, separated by a tabulator. =item B<-f>, B<--field> I [I...] @@ -138,7 +143,8 @@ are specified then it will print the whole control file. If any are specified then B will print their contents, in the order in which they appear in the -control file. If more than one +control file. +If more than one I is specified then B @@ -149,7 +155,8 @@ No errors are reported for fields requested but not found. =item B<-c>, B<--contents> I Lists the contents of the filesystem tree archive portion of the -package archive. It is currently produced in the format generated by +package archive. +It is currently produced in the format generated by B's verbose listing. @@ -160,7 +167,8 @@ directory. Note that extracting a package to the root directory will I -result in a correct installation! Use +result in a correct installation! +Use B to install packages. @@ -193,7 +201,8 @@ it from standard input («B<->») is B supported. Extracts the control data from a binary package and sends it to standard output in B -format (since dpkg 1.17.14). Together with +format (since dpkg 1.17.14). +Together with L this can be used to extract a particular control file from a package archive. The input archive will always be processed sequentially. @@ -203,7 +212,8 @@ The input archive will always be processed sequentially. Extracts the filesystem tree data from a binary package and sends it to standard output in B -format. Together with +format. +Together with L this can be used to extract a particular file from a package archive. The input archive will always be processed sequentially. @@ -237,14 +247,16 @@ Show the version and exit. =item B<--showformat=>I This option is used to specify the format of the output B<--show> -will produce. The format is a string that will be output for each package +will produce. +The format is a string that will be output for each package listed. The string may reference any status field using the “${I}” form, a list of the valid fields can be easily produced using B<-I> -on the same package. A complete explanation of the formatting options +on the same package. +A complete explanation of the formatting options (including escape sequences and field tabbing) can be found in the explanation of the B<--showformat> option in L. @@ -265,7 +277,8 @@ compressors. =item B<-S>I Specify which compression strategy to use on the compressor backend, when -building a package (since dpkg 1.16.2). Allowed values are B (since +building a package (since dpkg 1.16.2). +Allowed values are B (since dpkg 1.16.4), B, B, B and B for gzip (since dpkg 1.17.0) and B for xz. @@ -281,7 +294,8 @@ and B (default is B<%DEB_DEFAULT_COMPRESSOR%>). Specify that the same compression parameters should be used for all archive members (i.e. B and B; since dpkg 1.17.6). Otherwise only the -B member will use those parameters. The only supported +B member will use those parameters. +The only supported compression types allowed to be uniformly used are B, B, B and B. The B<--no-uniform-compression> option disables uniform compression @@ -318,7 +332,8 @@ as i386 a.out only. Inhibits B's -usual checks on the proposed contents of an archive. You can build +usual checks on the proposed contents of an archive. +You can build any archive you want, no matter how broken, this way. =item B<-v>, B<--verbose> @@ -329,7 +344,8 @@ B<--vextract>. =item B<-D>, B<--debug> -Enables debugging output. This is not very interesting. +Enables debugging output. +This is not very interesting. =back @@ -395,7 +411,8 @@ the L file entries. Do not attempt to use just B -to install software! You must use +to install software! +You must use B proper to ensure that all the files are correctly placed and the package's scripts run and its status and contents recorded. @@ -426,7 +443,8 @@ B<.deb> files; in fact, there isn't even a straightforward checksum. (Higher level tools like APT support authenticating B<.deb> packages retrieved from a given repository, and most packages nowadays provide an -md5sum control file generated by debian/rules. Though this is not directly +md5sum control file generated by debian/rules. +Though this is not directly supported by the lower level tools.) =head1 SEE ALSO diff --git a/man/dpkg-divert.pod b/man/dpkg-divert.pod index e4be12a89..eef67b956 100644 --- a/man/dpkg-divert.pod +++ b/man/dpkg-divert.pod @@ -38,8 +38,10 @@ is the utility used to set up and update the list of diversions. File I are a way of forcing L not to install a file into its -location, but to a I location. Diversions can be used through the -Debian package scripts to move a file away when it causes a conflict. System +location, but to a I location. +Diversions can be used through the Debian package scripts to move a file +away when it causes a conflict. +System administrators can also use it to override some package's configuration file, or whenever some files (which aren't marked as “conffiles”) need to be preserved by B, when installing a newer version of a package which @@ -106,13 +108,15 @@ provided by other packages, will be diverted. Specifies that all packages' versions of this file are diverted. This means, that there are no exceptions, and whatever package is installed, -the file is diverted. This can be used by an admin to install a locally +the file is diverted. +This can be used by an admin to install a locally modified version. =item B<--package> I I is the name of a package whose copy of I will not -be diverted. i.e. I will be diverted for all packages except +be diverted. +i.e. I will be diverted for all packages except I. =item B<--quiet> @@ -121,7 +125,8 @@ Quiet mode, i.e. no verbose output. =item B<--rename> -Actually move the file aside (or back). B will abort operation +Actually move the file aside (or back). +B will abort operation in case the destination file already exists. This is the common behavior used for diversions of files from the non-B package set (see B<--no-rename> for more details). @@ -205,7 +210,8 @@ B. =item I<%ADMINDIR%/diversions> -File which contains the current list of diversions of the system. It is +File which contains the current list of diversions of the system. +It is located in the B administration directory, along with other files important to B, such as I or I. @@ -217,7 +223,8 @@ I<-old>, before replacing it with the new one. =head1 NOTES When adding, default is B<--local> and B<--divert> -IB<.distrib>. When removing, B<--package> or +IB<.distrib>. +When removing, B<--package> or B<--local> and B<--divert> must match if specified. Directories can't be diverted with B. diff --git a/man/dpkg-fsys-usrunmess.pod b/man/dpkg-fsys-usrunmess.pod index d6711efed..799bdf6f5 100644 --- a/man/dpkg-fsys-usrunmess.pod +++ b/man/dpkg-fsys-usrunmess.pod @@ -30,7 +30,8 @@ B [B