1/*! \page specfile Spec file tags 2 3A few additions have been made to the spec file format. 4 5Name 6 7The Name tag contains the proper name of the package. Names must not 8include whitespace and may include a hyphen '-' (unlike version and release 9tags). Names should not include any numeric operators ('<', '>','=') as 10future versions of rpm may need to reserve characters other than '-'. 11 12By default subpackages are named by prepending `\<main package\>-' to 13the subpackage name(s). If you wish to change the name of a 14subpackage (most commonly this is to change the '-' to '.'), then you 15must specify the full name with the -n argument in the %package 16definition: 17 18\verbatim 19 %package -n newname 20\endverbatim 21 22\section specfile_summary Summary: and Description: Tags 23 24The Summary: tag should be use to give a short (50 char or so) summary 25of the package. Most package's Description: line should be changed to 26a Summary: line. The Description: tag is still supported but should 27be changed to a "%description" entry similar to %package and %files. 28At some point in the future support will be removed for "Description:". 29As an example, this spec file fragment: 30 31\verbatim 32 Description: Screen drawing library 33 Name: screenlib 34 Version: 1.0 35 36 %package devel 37 Description: Screen drawing library headers and static libs 38\endverbatim 39 40might be changed to: 41 42\verbatim 43 Summary: Screen drawing library 44 Name: screenlib 45 Version: 1.0 46 47 %description 48 The screen drawing library 49 is a handy development tool 50 51 %package devel 52 Summary: Screen drawing library headers and static libs 53 54 %description devel 55 This package contains all of the 56 headers and the static libraries for 57 screenlib. 58 59 You'll only need this package if you 60 are doing development. 61\endverbatim 62 63The description is free form text, but there are two things to note. 64The first regards reformatting. Lines that begin with white space 65are considered "pre-formatted" and will be left alone. Adjacent 66lines without leading whitespace are considered a single paragraph 67and may be subject to formatting by glint or another RPM tool. 68 69\section specfile_url URL: and Packager: Tags 70 71Two new tags are "URL:" and "Packager:". "URL:" is a place to put a 72URL for more information and/or documentation on the software 73contained in the package. Some future RPM package tool may make use 74of this. The Packager: tag is meant to contain the name and email 75address of the person who "maintains" the RPM package (which may be 76different from the person who actually maintains the program the 77package contains). 78 79\section specfile_buildarchitectures BuildArchitectures: Tag 80 81This tag specifies the architecture which the resulting binary package 82will run on. Typically this is a CPU architecture like sparc, 83i386. The string 'noarch' is reserved for specifying that the 84resulting binary package is platform independent. Typical platform 85independent packages are html, perl, python, java, and ps packages. 86 87\section specfile_virtual Virtual File Attribute(s) in %files Section 88 89A %ghost tag on a file indicates that this file is not to be included 90in the package. It is typically used when the attributes of the file 91are important while the contents is not (e.g. a log file). 92 93The %config(missingok) indicates that the file need not exist on the 94installed machine. The %config(missingok) is frequently used for files 95like /etc/rc.d/rc2.d/S55named where the (non-)existence of the symlink 96is part of the configuration in %post, and the file may need to be 97removed when this package is removed. This file is not required to 98exist at either install or uninstall time. 99 100The %config(noreplace) indicates that the file in the package should 101be installed with extension .rpmnew if there is already a modified file 102with the same name on the installed machine. 103 104The virtual file attribute token %verify tells `-V/--verify' to ignore 105certain features on files which may be modified by (say) a postinstall 106script so that false problems are not displayed during package verification. 107\verbatim 108 %verify(not size filedigest mtime) %{prefix}/bin/javaswarm 109\endverbatim 110 111\section specfile_globbing Shell Globbing of %files Section 112 113The usual rules for shell globbing apply. Most special characters can 114be escaped by prefixing them with a '\'. Spaces are used to separate 115file names and so must be escaped by enclosing the file name with quotes. 116For example: 117 118\verbatim 119 /tmp/are\.you\|bob\? 120 /tmp/bob\'s\*htdocs\* 121 "/tmp/bob\'s htdocs" 122\endverbatim 123 124Names containing "%%" will be rpm macro expanded into "%". When 125trying to escape large number of file names, it is often best to 126create a file with the complete list of escaped file names. This is 127easiest to do with a shell script like this: 128 129\verbatim 130 rm -f $RPM_BUILD_DIR/filelist.rpm 131 echo '%defattr(-,root,root)' >> $RPM_BUILD_DIR/filelist.rpm 132 find $RPM_BUILD_ROOT/%{_prefix} -type f -print | \ 133 sed "s!$RPM_BUILD_ROOT!!" | perl -pe 's/([?|*.\'"])/\\$1/g' \ 134 >> $RPM_BUILD_DIR/filelist.rpm 135 136 %files -f filelist.rpm 137\endverbatim 138 139\section specfile_automatic Fine Adjustment of Automatic Dependencies 140 141Rpm currently supports separate "Autoreq:" and "Autoprov:" tags in a 142spec file to independently control the running of find-requires and 143find-provides. A common problem occurs when packaging a large third 144party binary which has interfaces to other third party libraries you 145do not own. RPM will require all the third party libraries be 146installed on the target machine even though their intended use was 147optional. To rectify the situation you may turn off requirements when 148building the package by putting 149 150\verbatim 151 Autoreq: 0 152\endverbatim 153 154in your spec file. Any and all requirements should be added manually using the 155 156\verbatim 157 Requires: depend1, ..., dependN 158\endverbatim 159 160in this case. 161 162Similarly there is an Autoprov tag to turn off the automatic provision 163generation and a Autoreqprov to turn off both the automatic provides and 164the automatic requires generation. 165 166\section specfile_nosrc NoSource: Tag 167 168Files ending in .nosrc.rpm are generally source RPM packages whose spec 169files have one or more NoSource: or NoPatch: directives in them. Both 170directives use the named source or patch file to build the resulting 171binary RPM package as usual, but they are not included in the source 172RPM package. 173 174The original intent of this ability of RPM was to allow proprietary or 175non-distributable software to be built using RPM, but to keep the 176proprietary or non-distributable parts out of the resulting source RPM 177package, so that they would not get distributed. 178 179They also have utility if you are building RPM packages for software 180which is archived at a well-known location and does not require that 181you distribute the source with the binary, for example, for an 182organization's internal use, where storing large quantities of source 183is not as meaningful. 184 185The end result of all this, though, is that you can't rebuild 186``no-source'' RPM packages using `rpm --rebuild' unless you also have 187the sources or patches which are not included in the .nosrc.rpm. 188 189\section specfile_buildrequires BuildRequires: Tag 190 191Build dependencies are identical to install dependencies except: 192 193\verbatim 194 1) they are prefixed with build (e.g. BuildRequires: rather than Requires:) 195 2) they are resolved before building rather than before installing. 196\endverbatim 197 198So, if you were to write a specfile for a package that requires egcs to build, 199you would add 200\verbatim 201 BuildRequires: egcs 202\endverbatim 203to your spec file. 204 205If your package was like dump and could not be built w/o a specific version of 206the libraries to access an ext2 file system, you could express this as 207\verbatim 208 BuildRequires: e2fsprofs-devel = 1.17-1 209\endverbatim 210 211Finally, if your package used C++ and could not be built with gcc-2.7.2.1, you 212can express this as 213\verbatim 214 BuildConflicts: gcc <= 2.7.2.1 215\endverbatim 216 217\section comments Comments 218 219Comments in spec file have # at the start of the line. 220 221\verbatim 222 # this is a comment 223\endverbatim 224 225Macros are expanded even in comment lines. If this is undesireable, escape 226the macro with an extra percent sign (%): 227 228\verbatim 229 # make unversioned %%__python an error unless explicitly overridden 230\endverbatim 231 232Another option is to use built-in macro %dnl that discards text to next 233line without expanding it. 234 235\verbatim 236 %dnl make unversioned %__python an error unless explicitly overridden 237\endverbatim 238 239\section conditionals Conditionals 240 241RPM's spec file format allows conditional blocks of code to be used 242depending on various properties such as architecture (%ifarch /%ifnarch), 243operating system (%ifos / %ifnos), or a conditional expression (%if). 244 245%ifarch is generally used for building RPM packages for multiple 246platforms like: 247\verbatim 248 %ifarch s390 s390x 249 BuildRequires: s390utils-devel 250 %endif 251\endverbatim 252 253%ifos is used to control RPM's spec file processing according to the 254build target operating system. 255 256%if can be used for various purposes. The test can be evaluated based on 257the existence of a macro, like: 258\verbatim 259 %if %{defined with_foo} && %{undefined with_bar} 260\endverbatim 261string comparison: 262\verbatim 263 %if "%{optimize_flags}" != "none" 264\endverbatim 265or a mathematical statement: 266\verbatim 267 %if 0%{?fedora} > 10 || 0%{?rhel} > 7 268\endverbatim 269Generally, a mathematical statement allows to use logical operators 270&&, ||, !, relational operators !=, ==, <, > , <=, >=, arithmetic operators 271+, -, /, *, the ternary operator ? :, and parentheses. 272 273The conditional blocks end by %endif. Inside the conditional block %elif, 274%elifarch, %elifos or %else can be optionally used. Conditionals %endif and 275%else should not be followed by any text. Conditionals may be nested within 276other conditionals. 277 278%if-conditionals are not macros, and are unlikely to yield expected results 279if used in them. 280 281*/ 282