From 2487579c91d57017238919f5c8513b4ab8153129 Mon Sep 17 00:00:00 2001 From: Panu Matilainen Date: Tue, 27 Oct 2020 16:11:27 +0200 Subject: [PATCH 1/2] Document (however briefly) all our actively used header tags --- doc/manual/queryformat.md | 2 + doc/manual/tags.md | 499 ++++++++++++++++++++++++++++++++++++-- 2 files changed, 477 insertions(+), 24 deletions(-) diff --git a/doc/manual/queryformat.md b/doc/manual/queryformat.md index cb2e2be412..bb8df7e517 100644 --- a/doc/manual/queryformat.md +++ b/doc/manual/queryformat.md @@ -31,6 +31,8 @@ then) this: Each of these tags also has a version with a RPMTAG_ prefix, such as RPMTAG_NAME. You can use this tags with or without the RPMTAG_ prefix. +More detailed documentation about the tags can be found in the +[tag documentation](tags.md). A tag can consist of one element or an array of elements. Each element can be a string or number only. diff --git a/doc/manual/tags.md b/doc/manual/tags.md index 63e87ecd56..c11d1988d2 100644 --- a/doc/manual/tags.md +++ b/doc/manual/tags.md @@ -3,96 +3,296 @@ ## Base package tags * Name (1000) string + + Package name. + * Version (1001) string + + Package version. + * Release (1002) string + + Package release. + * Epoch (1003) int32 + + Package epoch (optional). An absent epoch is equal to epoch value `0`. + +* License (1014) string + + License of the package contents. + * Summary (1004) i18nstring + + One line summary of the package's purpose. + * Description (1005) i18nstring + + Multiline description of the package's purpose + * Os (1021) string + + The operating system the package is for + * Arch (1022) string + The architecture the package is for. `noarch` is a special case denoting + a architecture independent package. + ## Informative package tags * Buildhost (1007) string + + Hostname of the system the package was built on. + * Buildtime (1006) int32 + + Unix timestamp of package build time. + * Bugurl (5012) string + + URL to package bug tracker. + * Changelogname (1081) string array + + Per entry changelog author information, typically `name `. + * Changelogtext (1082) string array + + Per entry changelog text. + * Changelogtime (1080) int32 array + + Per entry changelog Unix timestamp. + * Cookie (1094) string + + An opaque value for tracking packages from a single build operation. + * Distribution (1010) string + + Distribution name. + * Disttag (1155) string + + Distribution acronym. + * Disturl (1123) string + + Distribution specific URL of the package. + * Encoding (5062) string -* Gif (1012) bin + + Encoding of the header string data. When present it is always `utf-8`) and + the data has actually been validated. + * Group (1016) i18nstring -* Icon (1043) bin -* License (1014) string + + Group of the package. + * Modularitylabel (5096) string + * Optflags (1122) string + + `%{optflags}` value at the time of package build. + * Packager (1015) string + + Packager contact information. + * Platform (1132) string + + Package platform (arch-os-vendor). + * Policies (1150) string array * Policyflags (5033) int32 array * Policynames (5030) string array * Policytypes (5031) string array * Policytypesindexes (5032) int32 array -* Prefixes (1098) string array + * Rpmversion (1064) string -* Size (1009) int32 + + Version of rpm used to build the package. + * Sourcepkgid (1146) bin * Sourcerpm (1044) string + + Package source rpm file name. + * Url (1020) string + + Package URL, typically project upstream website. + * Vcs (5034) string + + Package source code VCS location + * Vendor (1011) string -* Xpm (1013) bin + + Package vendor contact information. ## Packages with files * Archivesize (1046) int32 + + (Compressed) payload size. + +* Dirnames (1118) string array + + dirname(3) components of contained paths + +* Filedigestalgo (5011) int32 + + ID of file digest algorithm. If missing, considered `0` for `md5`. + +* Longarchivesize (271) int64 + + (Compressed) payload size when > 4GB. + +* Longsize (5009) int64 + + Installed package size when > 4GB. + * Payloadcompressor (1125) string + + Payload compressor name (as passed to rpmio `Fopen()`) + * Payloadflags (1126) string + + Payload compressor level (as passed to rpmio `Fopen()`) + * Payloadformat (1124) string -* Longarchivesize (271) int64 -* Longsigsize (270) int64 -* Longsize (5009) int64 + + Payload format (`cpio`) + +* Prefixes (1098) string array + + Relocatable prefixes (on relocatable packages). + +* Size (1009) int32 + + Installed package size. ## Per-file information + * Basenames (1117) string array + + basename(3) of the path. + * Dirindexes (1116) int32 array -* Dirnames (1118) string array + + Index into dirname(3) array of the pacakge (see Dirname tag). + * Filedevices (1095) int32 array -* Filedigestalgo (5011) int32 + + Abstract device ID (hardlink calculation only). + * Filedigests (1035) string array + + File cryptographic digest (aka hash) using algorithm specified in + Filedigestalgo. + * Fileflags (1037) int32 array + + File virtual attributes (doc, license, ghost, artifact etc) + * Filegroupname (1040) string array + + Unix group name. + * Fileinodes (1096) int32 array + + Abstract inode number (hardlink calculation only). + * Filelangs (1097) string array + + Optional language of the file (eg man page translations) + * Filelinktos (1036) string array + + Symlink target for symlink files. + * Filemodes (1030) int16 array + + Unix file mode. + * Filemtimes (1034) int32 array + + Unix file modification timestamp (aka mtime). + * Filerdevs (1033) int16 array -* Filesignaturelength (5091) int32 -* Filesignatures (5090) string array + + Device ID (of device files) + * Filesizes (1028) int32 array + + File size (when all files are < 4GB) + * Fileusername (1039) string array + + Unix owner name + * Fileverifyflags (1045) int32 array + + File verification flags (which aspects of file to verify) + * Longfilesizes (5008) int64 array + File size (when files > 4GB are present) + ### Optional file information + * Classdict (1142) string array + + File class (libmagic string) dictionary + * Dependsdict (1145) int32 array + + File dependencies dictionary + * Filecaps (5010) string array + + `cap_to_text(3)` textual representation of file capabilities. + * Fileclass (1141) int32 array + + Index into Classdict + * Filecolors (1140) int32 array -* Filecontexts (1147) string array + + File "color" - 1 for 32bit ELF, 2 for 64bit ELF and 0 otherwise + * Filedependsn (1144) int32 array + + Number of file dependencies in Dependsdict, starting from Filedependsx + * Filedependsx (1143) int32 array -* Filestates (1029) char array -* Origbasenames (1120) string array -* Origdirindexes (1119) int32 array -* Origdirnames (1121) string array + + Index into Dependsdict denoting start of this file's dependencies. + +* Filesignaturelength (5091) int32 + + IMA signature length. + +* Filesignatures (5090) string array + + IMA signature (hex encoded). + +* Veritysignaturealgo (277) int32 + + fsverity signature algorithm ID. + +* Veritysignatures (276) string array + + fsverity signature (base64 encoded). ## Dependency information + +All dependency tags follow the same pattern. The name tag contains +dependency token names, the flags tag may contain additional context +information and the dependency is versioned as per (`RPMSENSE_*` bitfield), +the range related to the version specified in the version tag. + +### Hard dependencies * Providename (1047) string array * Provideversion (1113) string array * Provideflags (1112) int32 array @@ -109,7 +309,7 @@ * Obsoleteversion (1115) string array * Obsoleteflags (1114) int32 array -### Weak dependencies +### Soft dependencies * Enhancename (5055) string array * Enhanceversion (5056) string array * Enhanceflags (5057) int32 array @@ -133,6 +333,13 @@ ## Scriptlets ### Basic scriptlets + +All scriptlet tags follow the same pattern. The main tag contains the +corresponding scriptlet (eg `%postin`) body. If present, the prog tag +denotes the scriptlet interpreter and possible arguments, and flags tag +contains additional processing information such as whether to macro +expand the scriptlet body. + * Postin (1024) string * Postinflags (5021) int32 * Postinprog (1086) string array @@ -163,6 +370,13 @@ ### Triggers +Triggers are stored in a combination of dependency and scriptlet tags. + +Triggerscripts, Triggerscriptflags and Triggerscriptprog form a scriptlet +triplet, and Triggername, Triggerflags, Triggerversion form a dependency +triplet. Triggerindexes is a per dependency index into Triggerscripts, +binding the two triplets together. + * Triggerflags (1068) int32 array * Triggerindex (1069) int32 array * Triggername (1066) string array @@ -173,6 +387,11 @@ ### File triggers +File trigger tags are like normal trigger tags, with an additional +priority tag to affect trigger running order. File triggers in +Filetrigger-tags run once per triggered package, whereas triggers in +Transfiletrigger-tags run once per transaction. + * Filetriggerflags (5072) int32 array * Filetriggerindex (5070) int32 array * Filetriggername (5069) string array @@ -192,43 +411,149 @@ * Transfiletriggerversion (5081) string array ## Signatures and digests + * Dsaheader (267) bin + + OpenPGP DSA signature of the header (if thus signed) + +* Longsigsize (270) int64 + + Header+payload size if > 4GB. + * Payloaddigest (5092) string array + + Cryptographic digest of the compressed payload. + * Payloaddigestalgo (5093) int32 + + ID of the payload digest algorithm. + * Payloaddigestalt (5097) string array + + Cryptographic digest of the uncompressed payload. + * Rsaheader (268) bin + + OpenPGP RSA signature of the header (if thus signed). + * Sha1header (269) string + + SHA1 digest of the header. + * Sha256header (273) string + + SHA256 digest of the header. + * Siggpg (262) bin + + OpenPGP DSA signature of the header+payload (if thus signed). + * Sigmd5 (261) bin + + MD5 digest of the header+payload. + * Sigpgp (259) bin + + OpenPGP RSA signature of the header+payload (if thus signed). + * Sigsize (257) int32 -* Veritysignaturealgo (277) int32 -* Veritysignatures (276) string array + + Header+payload size. ## Installed packages + +* Filestates (1029) char array + + Per-file installed status information (installed/skipped/forced etc) + * Installcolor (1127) int32 + + "Color" of transaction in which the package was installed. + * Installtid (1128) int32 + + ID of transaction in which the package was installed. + * Installtime (1008) int32 + + Unix timestamp of package installation. + * Instprefixes (1099) string array +* Origbasenames (1120) string array + + Original Basenames (relocated packages only) + +* Origdirindexes (1119) int32 array + + Original Dirindexes (relocated packages only) + +* Origdirnames (1121) string array + + Original Dirnames (relocated packages only) + + ## Source packages * Buildarchs (1089) string array + + If present, specifies the architectures the package may be built for. + * Excludearch (1059) string array + + If present, limits the architectures on which the package is buildable + by excluding those specified. + * Excludeos (1060) string array + + If present, limits the operating systems on which the package is buildable + by excluding those specified. + * Exclusivearch (1061) string array + + If present, limits the architectures on which the package is buildable + exclusively to those specified. + * Exclusiveos (1062) string array + + If present, limits the operating systems on which the package is buildable + exclusively to those specified. + * Nopatch (1052) int32 array + + Denotes a patch number for which source is not supplied. + * Nosource (1051) int32 array + + Denotes a source number for which source is not supplied. + * Patch (1019) string array + + Patch file names. + * Source (1018) string array + + Source file names. + * Sourcepackage (1106) int32 + Denotes a source rpm. + ## Internal / special + * Headeri18ntable (100) string array + + Locales for which the header has translations. + * Headerimmutable (63) bin + Special tag to return the unmodified, original image of the header + even after data has been added to it in eg installation. + ## Deprecated / Obsolete +* Filecontexts (1147) string array +* Fscontexts (1148) string array +* Gif (1012) bin +* Icon (1043) bin * Oldenhancesname (1159) string array * Oldenhancesversion (1160) string array * Oldenhancesflags (1161) int32 array @@ -240,9 +565,14 @@ * Patchesname (1133) string array * Patchesversion (1135) string array * Pubkeys (266) string array +* Recontexts (1149) string array * Removetid (1129) int32 +* Xpm (1013) bin ## Aliases + +Aliases are simply shorthands or alternative names for other tags. + * C (Conflictname) string array * Conflicts (Conflictname) string array * E (Epoch) int32 @@ -265,38 +595,159 @@ * V (Version) string ## Extension + +Extension tags do not exist in concrete form anywhere, their data is +constructed at query time based on other information in the headers +or runtime environment. A few physical tags do have an extension format +as well however, these exceptions noted below. + * Dbinstance (1195) int32 + + Header ID of installed package, 0 otherwise. + * Epochnum (5019) int32 + + Package epoch as numeric value (0 if not present). + * Evr (5013) string + + Formatted `epoch:version-release` string of the package + +* Fileclass (1141) string array + + Per-file formatted libmagic classification strings, calculated from the + Fileclass and Classdict tags. Note overlap with the concrete Fileclass + tag with different type (integer array)! + * Headercolor (5017) int32 + + Header "color" calculated from file colors. + * Nevr (5015) string + + Formatted `name-epoch:version-release` string of the package + * Nevra (5016) string + + Formatted `name-epoch:version-release.arch` string of the package + * Nvr (5014) string + + Formatted `name-version-release` string of the package + * Nvra (1196) string + Formatted `name-version-release.arch` string of the package + * Filenames (5000) string array + + Per file paths contained in the package, calculated from the path triplet. + * Filenlinks (5045) int32 array + + Per file hardlink number, calculated from inode/device information. + * Fileprovide (5001) string array + + Per file dependency capabilities provided by the corresponding files. + * Filerequire (5002) string array -* Fscontexts (1148) string array + + Per file dependency capabilities required by the corresponding files. + * Instfilenames (5040) string array + + Per file paths installed from the package, calculated from the path triplet + and file status info. + +* Longfilesizes + + Per file sizes in 64bit format regardless of underlying storage size. + Note overlap with the concrete Longfilesizes tag. + + Always use this to access file sizes. + +* Longarchivesize + + Archive size in 64bit format regardless of underlying storage size. + Note overlap with the concrete Longarchivesize tag. + + Always use this to access archive size. + +* Longsize + + Uncompressed size in 64bit format regardless of underlying storage size. + Note overlap with the concrete Longsize tag. + + Always use this to access uncompressed size. + +* Longsigsize + + Header+payload size in 64bit format regardless of underlying storage size. + Note overlap with the concrete Longsigsize tag. + + Always use this to access header+payload size. + * Origfilenames (5007) string array -* Recontexts (1149) string array + + Original Filenames in relocated packages. * Providenevrs (5042) string array + + Formatted `name [op version]` provide dependency strings. + * Conflictnevrs (5044) string array + + Formatted `name [op version]` conflict dependency strings. + * Obsoletenevrs (5043) string array + + Formatted `name [op version]` obsolete dependency strings. + * Enhancenevrs (5061) string array + + Formatted `name [op version]` enhance dependency strings. + * Recommendnevrs (5058) string array + + Formatted `name [op version]` recommend dependency strings. + * Requirenevrs (5041) string array + + Formatted `name [op version]` require dependency strings. + * Suggestnevrs (5059) string array + + Formatted `name [op version]` suggest dependency strings. + * Supplementnevrs (5060) string array -* Filetriggertype (5087) string array + Formatted `name [op version]` supplement dependency strings. + * Filetriggerconds (5086) string array + + Formatted file trigger condition information. + +* Filetriggertype (5087) string array + + Formatted file trigger type information. + * Transfiletriggerconds (5088) string array + + Formatted transaction file trigger condition information. + * Transfiletriggertype (5089) string array + + Formatted transaction file trigger type information. + * Triggerconds (5005) string array + + Formatted trigger condition information. + * Triggertype (5006) string array + Formatted trigger type information. + * Verbose (5018) int32 + + Returns 1 if rpm is running in verbose mode. From cd97f67b09866401d14e89c8227b1b894b1f7f99 Mon Sep 17 00:00:00 2001 From: Panu Matilainen Date: Wed, 28 Oct 2020 12:14:40 +0200 Subject: [PATCH 2/2] Reorganize the ancient spec tag blurb into a new beginning Remove long since obsoleted tags and such, at least mention all spec sections by name. Obviously mountains of information is missing, and what is there is totally chaotic and inconsistent, but at least there's a place to add more now. --- doc/manual/spec.md | 343 +++++++++++++++++++++++++++------------------ 1 file changed, 203 insertions(+), 140 deletions(-) diff --git a/doc/manual/spec.md b/doc/manual/spec.md index 78d13c21e7..8a51a7ef0f 100644 --- a/doc/manual/spec.md +++ b/doc/manual/spec.md @@ -1,6 +1,73 @@ -# Spec file tags +# Spec file format -A few additions have been made to the spec file format. +## Generic syntax + +### Comments + +Comments in spec file have # at the start of the line. + +``` + # this is a comment +``` + +Macros are expanded even in comment lines. If this is undesireable, escape +the macro with an extra percent sign (%): + +``` + # make unversioned %%__python an error unless explicitly overridden +``` + +Another option is to use built-in macro %dnl that discards text to next +line without expanding it. + +``` + %dnl make unversioned %__python an error unless explicitly overridden +``` + +### Conditionals + +RPM's spec file format allows conditional blocks of code to be used +depending on various properties such as architecture (%ifarch /%ifnarch), +operating system (%ifos / %ifnos), or a conditional expression (%if). + +%ifarch is generally used for building RPM packages for multiple +platforms like: +``` + %ifarch s390 s390x + BuildRequires: s390utils-devel + %endif +``` + +%ifos is used to control RPM's spec file processing according to the +build target operating system. + +%if can be used for various purposes. The test can be evaluated based on +the existence of a macro, like: +``` + %if %{defined with_foo} && %{undefined with_bar} +``` +string comparison: +``` + %if "%{optimize_flags}" != "none" +``` +or a mathematical statement: +``` + %if 0%{?fedora} > 10 || 0%{?rhel} > 7 +``` +Generally, a mathematical statement allows to use logical operators +`&&`, `||`, `!`, relational operators `!=`, `==`, `<`, `>` , `<=`, `>=`, +arithmetic operators `+`, `-`, `/`, `*`, the ternary operator `? :`, +and parentheses. + +The conditional blocks end by %endif. Inside the conditional block %elif, +%elifarch, %elifos or %else can be optionally used. Conditionals %endif and +%else should not be followed by any text. Conditionals may be nested within +other conditionals. + +%if-conditionals are not macros, and are unlikely to yield expected results +if used in them. + +## Preamble Name @@ -19,64 +86,28 @@ definition: %package -n newname ``` -## Summary: and Description: Tags +### Summary and description The Summary: tag should be use to give a short (50 char or so) summary -of the package. Most package's Description: line should be changed to -a Summary: line. The Description: tag is still supported but should -be changed to a "%description" entry similar to %package and %files. -At some point in the future support will be removed for "Description:". -As an example, this spec file fragment: - -``` - Description: Screen drawing library - Name: screenlib - Version: 1.0 - - %package devel - Description: Screen drawing library headers and static libs -``` - -might be changed to: - -``` - Summary: Screen drawing library - Name: screenlib - Version: 1.0 - - %description - The screen drawing library - is a handy development tool - - %package devel - Summary: Screen drawing library headers and static libs - - %description devel - This package contains all of the - headers and the static libraries for - screenlib. +of the package. - You'll only need this package if you - are doing development. -``` - -The description is free form text, but there are two things to note. +%description is free form text, but there are two things to note. The first regards reformatting. Lines that begin with white space are considered "pre-formatted" and will be left alone. Adjacent lines without leading whitespace are considered a single paragraph and may be subject to formatting by glint or another RPM tool. -## URL: and Packager: Tags +### URL: and Packager: Tags + +"URL:" is a place to put a URL for more information and/or documentation +on the software contained in the package. -Two new tags are "URL:" and "Packager:". "URL:" is a place to put a -URL for more information and/or documentation on the software -contained in the package. Some future RPM package tool may make use -of this. The Packager: tag is meant to contain the name and email +Packager: tag is meant to contain the name and email address of the person who "maintains" the RPM package (which may be different from the person who actually maintains the program the package contains). -## BuildArchitectures: Tag +### BuildArchitectures: Tag This tag specifies the architecture which the resulting binary package will run on. Typically this is a CPU architecture like sparc, @@ -84,59 +115,9 @@ i386. The string 'noarch' is reserved for specifying that the resulting binary package is platform independent. Typical platform independent packages are html, perl, python, java, and ps packages. -## Virtual File Attribute(s) in %files Section - -A %ghost tag on a file indicates that this file is not to be included -in the package. It is typically used when the attributes of the file -are important while the contents is not (e.g. a log file). - -The %config(missingok) indicates that the file need not exist on the -installed machine. The %config(missingok) is frequently used for files -like /etc/rc.d/rc2.d/S55named where the (non-)existence of the symlink -is part of the configuration in %post, and the file may need to be -removed when this package is removed. This file is not required to -exist at either install or uninstall time. - -The %config(noreplace) indicates that the file in the package should -be installed with extension .rpmnew if there is already a modified file -with the same name on the installed machine. - -The virtual file attribute token %verify tells `-V/--verify' to ignore -certain features on files which may be modified by (say) a postinstall -script so that false problems are not displayed during package verification. -``` - %verify(not size filedigest mtime) %{prefix}/bin/javaswarm -``` - -## Shell Globbing of %files Section - -The usual rules for shell globbing apply. Most special characters can -be escaped by prefixing them with a '\'. Spaces are used to separate -file names and so must be escaped by enclosing the file name with quotes. -For example: - -``` - /tmp/are\.you\|bob\? - /tmp/bob\'s\*htdocs\* - "/tmp/bob\'s htdocs" -``` - -Names containing "%%" will be rpm macro expanded into "%". When -trying to escape large number of file names, it is often best to -create a file with the complete list of escaped file names. This is -easiest to do with a shell script like this: - -``` - rm -f $RPM_BUILD_DIR/filelist.rpm - echo '%defattr(-,root,root)' >> $RPM_BUILD_DIR/filelist.rpm - find $RPM_BUILD_ROOT/%{_prefix} -type f -print | \ - sed "s!$RPM_BUILD_ROOT!!" | perl -pe 's/([?|*.\'"])/\\$1/g' \ - >> $RPM_BUILD_DIR/filelist.rpm - - %files -f filelist.rpm -``` +### Dependencies -## Fine Adjustment of Automatic Dependencies +#### Fine Adjustment of Automatic Dependencies Rpm currently supports separate "Autoreq:" and "Autoprov:" tags in a spec file to independently control the running of find-requires and @@ -163,7 +144,7 @@ Similarly there is an Autoprov tag to turn off the automatic provision generation and a Autoreqprov to turn off both the automatic provides and the automatic requires generation. -## NoSource: Tag +### NoSource: Tag Files ending in .nosrc.rpm are generally source RPM packages whose spec files have one or more NoSource: or NoPatch: directives in them. Both @@ -186,7 +167,7 @@ The end result of all this, though, is that you can't rebuild ``no-source'' RPM packages using `rpm --rebuild' unless you also have the sources or patches which are not included in the .nosrc.rpm. -## BuildRequires: Tag +### BuildRequires: Tag Build dependencies are identical to install dependencies except: @@ -214,66 +195,148 @@ can express this as BuildConflicts: gcc <= 2.7.2.1 ``` -## Comments +## Build scriptlets -Comments in spec file have # at the start of the line. +Package build is divided into multiple separate steps, each executed +in a separate shell. -``` - # this is a comment -``` +### %prep -Macros are expanded even in comment lines. If this is undesireable, escape -the macro with an extra percent sign (%): +%prep prepares the sources for building. This is where sources are +unpacked and possible patches applied, and other similar activies +could be performed. + +Typically (%autosetup)[autosetup.md] is used to automatically handle +it all, but for more advanced cases there are lower level `%setup` +and `%patch` builtin-macros available in this slot. +In simple packages `%prep` is often just: ``` - # make unversioned %%__python an error unless explicitly overridden +%prep +%autosetup ``` -Another option is to use built-in macro %dnl that discards text to next -line without expanding it. +### %build + +In %build, the unpacked sources are compiled to binaries. +Different build- and language ecosystems come with their +own helper macros, but rpm has helpers for autotools based builds such as +itself which typically look like this: ``` - %dnl make unversioned %__python an error unless explicitly overridden +%build +%configure +%make_build ``` -## Conditionals +### %install -RPM's spec file format allows conditional blocks of code to be used -depending on various properties such as architecture (%ifarch /%ifnarch), -operating system (%ifos / %ifnos), or a conditional expression (%if). +In `%install`, the software installation layout is prepared by creating +the necessary directory structure into an initially empty "build root" +directory and copying the just-built software in there to appropriate +places. For many simple packages this is just: -%ifarch is generally used for building RPM packages for multiple -platforms like: ``` - %ifarch s390 s390x - BuildRequires: s390utils-devel - %endif +%install +%make_install ``` -%ifos is used to control RPM's spec file processing according to the -build target operating system. +`%install` required for creating packages that contain any files. -%if can be used for various purposes. The test can be evaluated based on -the existence of a macro, like: -``` - %if %{defined with_foo} && %{undefined with_bar} +### %check + +If the packaged software has accomppanying tests, this is where they +should be executed. + +## Runtime scriptlets + +Runtime scriptlets are executed at the time of install and erase of the +package. By default, scriptlets are executed with `/bin/sh` shell, but +this can be overridden with `-p ` as an argument to the scriptlet +for each scriptlet individually. Other supported operations include +[scriptlet expansion](scriptlet_expansion.md). + +### Basic scriptlets + + * `%pre` + * `%post` + * `%preun` + * `%postun` + * `%pretrans` + * `%posttrans` + * `%verify` + +### Triggers + + * `%triggerprein` + * `%triggerin` + * `%triggerun` + * `%triggerpostun` + +More information is available in [trigger chapter](triggers.md). + +### File triggers + + * `%filetriggerin` + * `%filetriggerun` + * `%filetriggerpostun` + * `%transfiletriggerin` + * `%transfiletriggerun` + * `%transfiletriggerpostun` + +More information is available in [file trigger chapter](file_triggers.md). + +## %files section + +### Virtual File Attribute(s) + +A %ghost tag on a file indicates that this file is not to be included +in the package. It is typically used when the attributes of the file +are important while the contents is not (e.g. a log file). + +The %config(missingok) indicates that the file need not exist on the +installed machine. The %config(missingok) is frequently used for files +like /etc/rc.d/rc2.d/S55named where the (non-)existence of the symlink +is part of the configuration in %post, and the file may need to be +removed when this package is removed. This file is not required to +exist at either install or uninstall time. + +The %config(noreplace) indicates that the file in the package should +be installed with extension .rpmnew if there is already a modified file +with the same name on the installed machine. + +The virtual file attribute token %verify tells `-V/--verify' to ignore +certain features on files which may be modified by (say) a postinstall +script so that false problems are not displayed during package verification. ``` -string comparison: + %verify(not size filedigest mtime) %{prefix}/bin/javaswarm ``` - %if "%{optimize_flags}" != "none" + +### Shell Globbing + +The usual rules for shell globbing apply. Most special characters can +be escaped by prefixing them with a '\'. Spaces are used to separate +file names and so must be escaped by enclosing the file name with quotes. +For example: + ``` -or a mathematical statement: + /opt/are\.you\|bob\? + /opt/bob\'s\*htdocs\* + "/opt/bob\'s htdocs" ``` - %if 0%{?fedora} > 10 || 0%{?rhel} > 7 + +Names containing "%%" will be rpm macro expanded into "%". When +trying to escape large number of file names, it is often best to +create a file with the complete list of escaped file names. This is +easiest to do with a shell script like this: + ``` -Generally, a mathematical statement allows to use logical operators -&&, ||, !, relational operators !=, ==, <, > , <=, >=, arithmetic operators -+, -, /, *, the ternary operator ? :, and parentheses. + rm -f filelist.txt + find $RPM_BUILD_ROOT/%{_prefix} -type f -print | \ + sed "s!$RPM_BUILD_ROOT!!" | perl -pe 's/([?|*.\'"])/\\$1/g' \ + >> $RPM_BUILD_DIR/filelist.txt -The conditional blocks end by %endif. Inside the conditional block %elif, -%elifarch, %elifos or %else can be optionally used. Conditionals %endif and -%else should not be followed by any text. Conditionals may be nested within -other conditionals. + %files -f filelist.rpm +``` -%if-conditionals are not macros, and are unlikely to yield expected results -if used in them. +## %changelog section