Debian Codegraph @

upstream/debian-unstable/man7/rpm-macros.7

raw
1 .\" Generated by scdoc 1.11.4
2 .\" Complete documentation for this program is not available as a GNU info page
3 .ie \n(.g .ds Aq \(aq
4 .el .ds Aq '
5 .nh
6 .ad l
7 .\" Begin generated content:
8 .TH "RPM-MACROS" "7" "2026-04-10" "RPM 6.0.1"
9 .PP
10 .SH NAME
11 rpm-macros - RPM macro processor
12 .PP
13 .SH SYNOPSIS
14 .SS Defining
15 \fB%\fR\fINAME\fR \fIBODY\fR
16 .PP
17 \fB%\fR\fINAME\fR\fB(\fR[\fIOPTIONS\fR]\fB)\fR \fIBODY\fR
18 .PP
19 .SS Expanding
20 \fB%\fR\fINAME\fR
21 .PP
22 \fB%\fR\fINAME\fR [\fIOPTIONS\fR] [\fIARGUMENTS\fR]
23 .PP
24 \fB%{\fR\fINAME\fR\fB}\fR
25 .PP
26 \fB%{\fR\fINAME\fR [\fIOPTIONS\fR] \fIARGUMENTS\fR\fB}\fR
27 .PP
28 \fB%{\fR\fINAME\fR\fB:\fR\fIARGUMENT\fR\fB}\fR
29 .PP
30 \fB%{?\&\fR\fINAME\fR\fB}\fR
31 .PP
32 \fB%{?\&\fR\fINAME\fR\fB:\fR\fIVALUE-IF-DEFINED\fR\fB}\fR
33 .PP
34 \fB%{!\&?\&\fR\fINAME\fR\fB:\fR\fIVALUE-IF-NOT-DEFINED\fR\fB}\fR
35 .PP
36 \fB%(\fR\fISHELL-COMMAND\fR\fB)\fR
37 .PP
38 \fB%[\fR\fIEXPRESSION\fR\fB]\fR
39 .PP
40 \fB%[\fR\fIEXPRESSION\fR \fB?\&\fR \fIVALUE-IF-TRUE\fR \fB:\fR \fIVALUE-IF-FALSE\fR\fB]\fR
41 .PP
42 \fB%{lua:\fR\fILUA-CODE\fR\fB}\fR
43 .PP
44 .SH DESCRIPTION
45 .PP
46 RPM has a powerful built-in macro processor.\& The primary uses of macros
47 are configuration and other utility functions for RPM itself,
48 and as a packaging aid in spec files.\&
49 .PP
50 In addition to simple text substitution, the macro processor supports
51 the following facilities:
52 .PD 0
53 .IP \(bu 4
54 function-like \fBPARAMETRIC MACROS\fR with options and arguments processing
55 and locally scoped automatic and user-defined macros
56 .IP \(bu 4
57 \fBShell expansion\fR
58 .IP \(bu 4
59 \fBExpression expansion\fR
60 .IP \(bu 4
61 \fBLua expansion\fR for embedded Lua processing
62 .IP \(bu 4
63 various \fBBUILT-IN MACROS\fR for string processing and OS interaction
64 .PD
65 .PP
66 The syntax for defining simple macros is:
67 .PP
68 .RS 4
69 \fINAME\fR \fIBODY\fR
70 .PP
71 .RE
72 All whitespace surrounding \fIBODY\fR is removed.\& \fINAME\fR may be composed
73 of alphanumeric characters and the underscore (\fB_\fR), and must be at least
74 two characters in length.\& The body is (re-)expanded on each macro invocation.\&
75 Macro names and options are case-sensitive.\&
76 .PP
77 See \fBPARAMETRIC MACROS\fR for the more advanced macro variant with options
78 and arguments processing.\&
79 .PP
80 Macros can be defined via \fBrpm-macrofile\fR(5) files, and fully managed with
81 macro primitives \fB%define\fR, \fB%global\fR and \fB%undefine\fR, RPM command-line
82 described in \fBrpm-common\fR(8) and the API (C, Python, Lua).\&
83 .PP
84 Except for those defined inside parametric macros, macros are always global
85 in scope.\&
86 .PP
87 RPM macros are stacked, ie.\& when redefining an already existing
88 macro, it shadows the previous definition instead of replacing it, and
89 undefining a macro only pops the topmost definition, thus activating
90 the previous macro definition.\&
91 .PP
92 Note that this manual only describes the macro processor engine itself.\&
93 On a normal RPM based system, there are a vast number of other macros
94 defined through \fBrpm-macrofile\fR(5) files that will not be covered here.\&
95 .PP
96 .SH EXPANSION
97 To expand a macro, place \fB%\fR in front of it.\& Several forms are supported:
98 .PP
99 \fB%\fR\fINAME\fR
100 .RS 4
101 Expand the macro \fINAME\fR.\&
102 .PP
103 .RE
104 \fB%{\fR\fINAME\fR\fB}\fR
105 .RS 4
106 Expand the macro \fINAME\fR, allowing placement
107 adjacent to other text (similar to \fB${ENV}\fR in shell).\&
108 .PP
109 .RE
110 \fB%\fR\fINAME\fR [\fIOPTIONS\fR] [\fIARGUMENTS\fR]
111 .RS 4
112 Expand the parametric/built-in macro \fINAME\fR, using options
113 and arguments parsed up to the string end or next newline.\&
114 .PP
115 \fB--\fR can be used to separate options from arguments.\&
116 .PP
117 .RE
118 \fB%{\fR\fINAME\fR [\fIOPTIONS\fR] [\fIARGUMENTS\fR]\fB}\fR
119 .RS 4
120 Expand the parametric/built-in macro \fINAME\fR, using options
121 and arguments parsed up to the closing \fB}\fR.\&
122 Allows usage adjacent to other text.\&
123 .PP
124 .RE
125 \fB%{\fR\fINAME\fR\fB:\fR\fIARGUMENT\fR\fB}\fR
126 .RS 4
127 Expand the parametric/built-in macro \fINAME\fR, using the string after \fB:\fR
128 as the sole argument.\& Allows usage adjacent to other text.\&
129 .PP
130 .RE
131 Note: The syntaxes for calling parametric and built-in macros are generally
132 interchangeable now, but prior to 4.\&18, the \fB%{\fR\fINAME\fR\fB:\fR\fIARGUMENT\fR\fB}\fR
133 syntax was exclusive to built-in macros.\&
134 .PP
135 Macro expansion can be escaped by placing a second \fB%\fR in front of the
136 macro, for example \fB%%{name}\fR would be expanded to \fB%{name}\fR.\&
137 .PP
138 Attempting to expand an undefined macro expands to the
139 literal invocation, e.\&g.\& \fB%_undefined\fR expands to \fB%_undefined\fR.\&
140 If this is not desired, use conditionals.\&
141 .PP
142 Macro expansions can recurse up to 64 levels.\&
143 .PP
144 .SS Shell expansion
145 Shell expansion can be performed using \fB%(\fR\fIshell command\fR\fB)\fR.\&
146 \fIshell_command\fR is expanded before executing it with \fI/bin/sh\fR, whose output
147 becomes the expansion of the macro.\& The trailing newline is deleted.\&
148 .PP
149 Example:
150 .nf
151 .RS 4
152 %(echo aa-bb-cc | tr \&'-\&' \&'\&.\&')
153 .fi
154 .RE
155 .PP
156 .SS Conditional expansion
157 The macro processor supports testing whether a macro is defined or not.\&
158 .PP
159 \fB%{?\&\fR\fINAME\fR\fB:\fR\fIVALUE\fR\fB}\fR
160 .RS 4
161 Expands to the expansion of \fIVALUE\fR if \fINAME\fR is defined, otherwise
162 to an empty string.\&
163 .PP
164 .RE
165 \fB%{!\&?\&\fR\fINAME\fR\fB:\fR\fIVALUE\fR\fB}\fR
166 .RS 4
167 Expands to the expansion of \fIVALUE\fR if \fINAME\fR is \fInot\fR defined,
168 otherwise it expands to an empty string.\&
169 .PP
170 .RE
171 \fB%{?\&\fR\fINAME\fR\fB}\fR
172 .RS 4
173 Shorthand for \fB%{?\&\fR\fINAME\fR\fB:%{\fR\fINAME\fR\fB}}\fR.\&
174 .PP
175 .RE
176 For more complex tests, use \fBExpression expansion\fR or \fBLua expansion\fR.\&
177 Note that \fB%if\fR, \fB%ifarch\fR and the like are not macros, they are spec
178 directives and only usable in that context.\&
179 .PP
180 Note that in RPM >= 4.\&17, conditionals on built-in macros simply test for
181 existence of that built-in, just like with any other macros.\&
182 In older versions, the behavior of conditionals on built-ins is undefined.\&
183 .PP
184 .SS Expression expansion
185 Expression expansion can be performed using \fB%[\fR\fIEXPRESSION\fR\fB]\fR.\& An
186 expression consists of terms that can be combined using
187 operators.\&
188 .PP
189 RPM supports three kinds of terms:
190 .PD 0
191 .IP \(bu 4
192 numbers made up from digits
193 .IP \(bu 4
194 strings enclosed in double quotes (e.\&g \fB"somestring"\fR)
195 .IP \(bu 4
196 versions enclosed in double quotes preceded by \fBv\fR (e.\&g \fBv"3:1.\&2-1"\fR)
197 .PD
198 .PP
199 RPM will expand macros when evaluating terms.\&
200 .PP
201 You can use the standard operators to combine terms:
202 .PD 0
203 .IP \(bu 4
204 logical operators \fB&&\fR, \fB||\fR, \fB!\&\fR
205 .IP \(bu 4
206 relational operators \fB!\&=\fR, \fB==\fR, \fB<\fR, \fB>\fR, \fB<=\fR, \fB>=\fR
207 .IP \(bu 4
208 arithmetic operators \fB+\fR, \fB-\fR, \fB/\fR, \fB*\fR,
209 .IP \(bu 4
210 the ternary operator \fB?\& :\fR
211 .IP \(bu 4
212 parentheses
213 .PD
214 .PP
215 For example, \fB%[ 3 + 4 * (1 + %two) ]\fR will expand
216 to \fB15\fR if \fB%two\fR expands to \fB2\fR.\& Version terms are compared using
217 RPM version ([\fIepoch\fR:]\fIversion\fR[-\fIrelease\fR]) comparison algorithm,
218 rather than regular string comparison.\&
219 .PP
220 Note that the \fB%[\fR\fIEXPRESSION\fR\fB]\fR expansion is different to the
221 \fB%{expr:\fR\fIEXPRESSION\fR\fB}\fR macro.\& With the latter, the macros in the
222 expression are expanded first and then the expression is
223 evaluated (without re-expanding the terms).\& Thus
224 .PP
225 .nf
226 .RS 4
227 rpm --define \&'foo 1 + 2\&' --eval \&'%{expr:%foo}\&'
228 .fi
229 .RE
230 .PP
231 will print \fB3\fR.\& Using \fB%[%foo]\fR instead will result in the
232 error that "1 + 2" is not a number.\&
233 .PP
234 Doing the macro expansion when evaluating the terms has two
235 advantages.\& First, it allows RPM to do correct short-circuit
236 processing when evaluating logical operators.\& Second, the
237 expansion result does not influence the expression parsing,
238 e.\&g.\& \fB%["%file"]\fR will even work if the \fB%file\fR macro expands
239 to a string that contains a double quote.\&
240 .PP
241 Added: 4.\&16.\&0
242 .PP
243 .SS Lua expansion
244 The most powerful of the macro expansion methods is using RPM'\&s embedded Lua
245 interpreter:
246 .PP
247 \fB%{lua:\fR\fILUA-CODE\fR\fB}\fR
248 .RS 4
249 Execute \fILUA-CODE\fR using RPM'\&s embedded Lua interpreter, expanding
250 to the code'\&s \fBprint()\fR'\&ed output.\&
251 .PP
252 .RE
253 See \fBrpm-lua\fR(7) for the details.\&
254 .PP
255 .SH PARAMETRIC MACROS
256 Parametric macros are a powerful mechanism that allows building function-like
257 utility macros with option processing and accepting a variable number of
258 arguments, much like common shell tools.\&
259 .PP
260 The syntax for defining parametric macros is:
261 .PP
262 .RS 4
263 \fINAME\fR([\fIOPTIONS\fR]) \fIBODY\fR
264 .PP
265 .RE
266 If present, the \fIOPTIONS\fR (i.\&e.\& the string between parentheses) are passed
267 exactly as is to \fBgetopt\fR(3) for argc/argv processing at the beginning of
268 a macro invocation.\& Only short options are supported.\&
269 .PP
270 \fB-\fR as the sole \fIOPTIONS\fR field disables RPM'\&s option processing.\&
271 This allows macros to fully decide how to handle their input, e.\&g.\&
272 if the arguments of the macro only/mostly consist of items starting
273 with \fB-\fR, the default processing only gets in the way.\&
274 .PP
275 .SS Automatic macros
276 While a parameterized macro is being expanded, the following shell-like
277 automatic macros are available:
278 .PP
279 .TS
280 allbox;l lx
281 l lx
282 l lx
283 l lx
284 l lx
285 l lx
286 l lx
287 l lx.
288 T{
289 \fBMacro\fR
290 T} T{
291 \fBDescription\fR
292 T}
293 T{
294 \fB%0\fR
295 T} T{
296 the name of the macro being invoked
297 T}
298 T{
299 \fB%*\fR
300 T} T{
301 all arguments (unlike shell, not including any processed flags)
302 T}
303 T{
304 \fB%**\fR
305 T} T{
306 all arguments (including any processed flags)
307 T}
308 T{
309 \fB%#\fR
310 T} T{
311 the number of arguments
312 T}
313 T{
314 \fB%{-f}\fR
315 T} T{
316 if present at invocation, the last occurrence of flag \fBf\fR (flag and argument)
317 T}
318 T{
319 \fB%{-f*}\fR
320 T} T{
321 if present at invocation, the argument to the last occurrence of flag \fBf\fR
322 T}
323 T{
324 \fB%1\fR, \fB%2\fR, .\&.\&.\&
325 T} T{
326 the arguments themselves (after \fBgetopt\fR(3) processing)
327 T}
328 .TE
329 .sp 1
330 If the built-in option processing was disabled with \fB-\fR as the \fIOPTIONS\fR
331 field, only the following automatic macros are available:
332 .PP
333 .TS
334 allbox;l lx
335 l lx
336 l lx
337 l lx
338 l lx.
339 T{
340 \fBMacro\fR
341 T} T{
342 \fBDescription\fR
343 T}
344 T{
345 \fB%0\fR
346 T} T{
347 the name of the macro being invoked
348 T}
349 T{
350 \fB%*\fR, \fB%**\fR
351 T} T{
352 all arguments
353 T}
354 T{
355 \fB%#\fR
356 T} T{
357 the number of arguments
358 T}
359 T{
360 \fB%1\fR, \fB%2\fR, .\&.\&.\&
361 T} T{
362 the arguments themselves
363 T}
364 .TE
365 .sp 1
366 Automatic macros are automatically defined and undefined on parametric
367 macro entry and exit.\&
368 .PP
369 .SS Accessing options
370 Within the body of a parametric macro, there are several constructs that
371 permit testing for the presence of optional parameters.\& The simplest construct
372 is \fB%{-f}\fR which expands (literally) to \fB-f\fR if \fB-f\fR was mentioned when the
373 macro was invoked.\& There are also provisions for including text if a flag
374 was present using \fB%{-f:X}\fR.\& This macro expands to (the expansion of) \fBX\fR
375 if the flag was present.\& The negative form, \fB%{!\&-f:Y}\fR, expanding to (the
376 expansion of)\fB Y\fR if \fB-f\fR was \fBnot\fR present, is also supported.\&
377 .PP
378 .SS Scope and visibility
379 In general, macros have a global scope, regardless of where and how they were
380 defined.\& However, macros defined inside parametric macros have non-global
381 scope as follows:
382 .PD 0
383 .IP \(bu 4
384 automatic macros have local scope, ie.\& are only visible on the call-level
385 of the macro itself
386 .IP \(bu 4
387 user-defined local macros have nested scope, ie.\& are visible on the
388 call-level of the macro itself and deeper
389 .PD
390 .PP
391 That is, a parametric macro cannot see the options or arguments of another one,
392 but a user-defined local macro in a calling macro can be accessed in the
393 callee(s).\&
394 .PP
395 To define a global macro inside a parametric macro, you \fImust\fR use \fB%global\fR
396 instead of \fB%define\fR.\& Also note that because such a macro may be referring
397 to other macros only visible in the current scope, \fB%global\fR \fIexpands the
398 macro body once at the time of definition\fR.\&
399 .PP
400 .SS Calling convention
401 When a parametric macro is expanded, the following calling convention is used:
402 .PD 0
403 .IP 1. 4
404 any arguments to the macro are expanded on the call-level of the callee
405 .IP 2. 4
406 any options to the macro are processed
407 .IP 3. 4
408 automatic macros are set up for the options and the arguments
409 .IP 4. 4
410 the macro body is recursively expanded
411 .IP 5. 4
412 all macros defined on this call-level are discarded
413 .PD
414 .PP
415 .SH BUILT-IN MACROS
416 RPM supports the following built-in macros for various operations.\&
417 Built-in macros cannot be undefined or overridden.\&
418 .PP
419 Note: The \fB%{name:arg}\fR style is used here as it'\&s the most backwards
420 compatible and does not require quoting for whitespace, but it can generally
421 be replaced with the other expansion forms too.\& Built-ins taking multiple
422 arguments must use other styles, as indicated below.\&
423 .PP
424 .SS Macro manipulation
425 The macro primitives are used for macro manipulation in spec files
426 and other macros.\& Note that all these operate on the macro name \fIwithout\fR
427 the preceding \fB%\fR-character.\&
428 .PP
429 \fB%define\fR \fINAME\fR[([\fIOPTIONS\fR])] \fIBODY\fR
430 .RS 4
431 This is the primary way to define macros.\&
432 A \fB%define\fR is always fully declarative: no macro expansion takes place,
433 and it has no side-effects.\& Macros defined with it are in global scope,
434 unless the definition occurs inside a parametric macro.\&
435 .PP
436 Example:
437 .nf
438 .RS 4
439 %define mypath /usr/bin/mine
440 .fi
441 .RE
442 .PP
443 .RE
444 \fB%global\fR \fINAME\fR[([\fIOPTIONS\fR])] \fIBODY\fR
445 .RS 4
446 The \fB%global\fR primitive is identical in syntax to \fB%define\fR, but has
447 two critically important behavioral differences: as it'\&s name suggests,
448 a macro defined with \fB%global\fR always has a global scope regardless
449 of where it'\&s used.\&
450 .PP
451 The second difference is that the \fIBODY\fR is expanded once at the time
452 of definition and the expansion becomes the actual macro body.\&
453 Thus, arbitrary code execution and side-effects may
454 occur when \fB%global\fR is used, depending on the contents and the
455 other macros used in \fIBODY\fR.\& The latter can be handy for avoiding
456 redundant, possibly expensive macro expansions if the value does not
457 change, but be aware of the side-effects.\&
458 .PP
459 Note that while \fB%global\fR technically accepts an \fIOPTIONS\fR field,
460 it is ill-suited for defining parametric macros because of the
461 \fIBODY\fR expansion behavior.\&
462 .PP
463 Example:
464 .nf
465 .RS 4
466 %global snapver 0-0\&.48\&.20240616git
467 .fi
468 .RE
469 .PP
470 .RE
471 \fB%undefine\fR \fINAME\fR
472 .RS 4
473 Note that \fB%undefine\fR only pops a macro definition from the stack, so
474 using it does \fInot\fR guarantee that \fINAME\fR is undefined after calling
475 \fB%undefine\fR on it.\&
476 Automatic macros and built-in macros cannot be undefined.\&
477 .PP
478 Example:
479 .nf
480 .RS 4
481 %undefine mypath
482 .fi
483 .RE
484 .PP
485 .RE
486 \fB%{load:\fR\fIFILE\fR\fB}\fR
487 .RS 4
488 Load an \fBrpm-macrofile\fR(5) file.\& (Added: 4.\&12.\&0)
489 .PP
490 Example:
491 .nf
492 .RS 4
493 %{load:/some/dir/macros\&.foo}
494 .fi
495 .RE
496 .PP
497 .RE
498 .SS Macro expansion
499 \fB%{expand:\fR\fIBODY\fR\fB}\fR
500 .RS 4
501 Expand \fIBODY\fR as if it were a macro body.\& Useful for increased
502 indirection, such as to expand a macro name constructed from
503 two or more macros.\&
504 .PP
505 Example:
506 .nf
507 .RS 4
508 %{expand:%{foo_prefix}%{foo_suffix}}
509 .fi
510 .RE
511 .PP
512 .RE
513 \fB%{expr:\fR\fIEXPRESSION\fR}
514 .RS 4
515 Expand \fIEXPRESSION\fR.\& See \fBExpression expansion\fR.\& (Added: 4.\&15.\&0)
516 .PP
517 Example:
518 .nf
519 .RS 4
520 %{expr:5*1024}
521 .fi
522 .RE
523 .PP
524 .RE
525 \fB%{lua:\fR\fILUA-CODE\fR\fB}\fR
526 .RS 4
527 Expand to output of \fILUA-CODE\fR using the embedded Lua interpreter.\&
528 See \fBLua expansion\fR.\&
529 .PP
530 Example:
531 .nf
532 .RS 4
533 %{lua:for i=65,90 do print(string\&.char(i)) end}
534 .fi
535 .RE
536 .PP
537 .RE
538 \fB%{macrobody:\fR\fINAME\fR\fB}\fR
539 .RS 4
540 Expand to the literal body of the macro \fINAME\fR.\& (Added: 4.\&16.\&0)
541 .PP
542 Example:
543 .nf
544 .RS 4
545 %{macrobody:_libdir}
546 .fi
547 .RE
548 .PP
549 .RE
550 .SS String operations
551 \fB%dnl\fR
552 .RS 4
553 Discard to next line (without expanding anything).\&
554 \fB%dnl\fR is the recommended way to comment out things in spec files
555 because it works everywhere and disables macro processing for
556 that line.\& (Added: 4.\&15.\&0)
557 .PP
558 Example:
559 .nf
560 .RS 4
561 %dnl This is a comment on %{mymacro} behavior
562 .fi
563 .RE
564 .PP
565 .RE
566 \fB%{gsub \fR\fISTRING\fR, \fIPATTERN\fR, \fIREPL\fR [,\fIN\fR]\fB}\fR
567 .RS 4
568 Replace all (or \fIN\fR first if given) occurrences of \fIPATTERN\fR in
569 \fISTRING\fR by \fIREPL\fR.\&
570 .PP
571 Added: 4.\&19.\&0
572 .PP
573 Example:
574 .nf
575 .RS 4
576 %{gsub aabbaacc aa dd 1}
577 .fi
578 .RE
579 .PP
580 .RE
581 \fB%{len:\fR\fISTRING\fR\fB}\fR
582 .RS 4
583 Expand to length of \fISTRING\fR.\& (Added: 4.\&19.\&0)
584 .PP
585 Example:
586 .nf
587 .RS 4
588 %{len:9bf7da058a7c582878310e75be3d56a5a8b67f95}
589 .fi
590 .RE
591 .PP
592 .RE
593 \fB%{lower:\fR\fISTRING\fR\fB}\fR
594 .RS 4
595 Expand to lowercase \fISTRING\fR.\& (Added: 4.\&19.\&0)
596 .PP
597 Example:
598 .nf
599 .RS 4
600 %{lower:CamelCase}\&'
601 .fi
602 .RE
603 .PP
604 .RE
605 \fB%{quote:\fR\fISTRING\fR\fB}\fR
606 .RS 4
607 Quote arguments for passing empty strings and strings with
608 embedded whitespace as parametric macro arguments.\& (Added: 4.\&14.\&0)
609 .PP
610 Example:
611 .nf
612 .RS 4
613 %myzip -x %{quote:empty spaces\&.zip}
614 .fi
615 .RE
616 .PP
617 .RE
618 \fB%{rep \fR\fISTRING\fR, \fIN\fR [,\fISEP\fR]\fB}\fR
619 .RS 4
620 Expand to a string that is the concatenation of \fIN\fR copies of
621 \fISTRING\fR, separated by \fISEP\fR (if specified).\&
622 .PP
623 Added: 4.\&19.\&0
624 .PP
625 Example:
626 .nf
627 .RS 4
628 %{rep a 5}
629 .fi
630 .RE
631 .PP
632 .PP
633 .RE
634 \fB%{reverse:\fR\fISTRING\fR\fB}\fR
635 .RS 4
636 Reverse a string.\& (Added: 4.\&19.\&0)
637 .PP
638 Example:
639 .nf
640 .RS 4
641 %{reverse:tac}
642 .fi
643 .RE
644 .PP
645 .RE
646 \fB%{shescape:\fR\fISTRING\fR\fB}\fR
647 .RS 4
648 Single quote \fISTRING\fR with escapes for use in shell.\& (Added: 4.\&18.\&0)
649 .PP
650 Example:
651 .nf
652 .RS 4
653 %{shescape:foo\&'s}
654 .fi
655 .RE
656 .PP
657 .RE
658 \fB%{shrink:\fR\fISTRING\fR\fB}\fR
659 .RS 4
660 Trim leading and trailing whitespace from \fISTRING\fR, reduce
661 intermediate whitespace to a single space.\& (Added: 4.\&14.\&0)
662 .PP
663 Example:
664 .nf
665 .RS 4
666 %{shrink:aa bb ccc }
667 .fi
668 .RE
669 .PP
670 .RE
671 \fB%{span:\fR\fISTRING\fR\fB}\fR
672 .RS 4
673 As-is string, handy for wrapping multiline macros.\& (Added: 6.\&0.\&0)
674 .PP
675 Example:
676 .nf
677 .RS 4
678 %{span:
679 %one thing
680 %another thing
681 }
682 .fi
683 .RE
684 .PP
685 .RE
686 \fB%{sub \fR\fISTRING\fR, \fII\fR, [,\fIJ\fR]\fB}\fR
687 .RS 4
688 Expand to substring of \fISTRING\fR that starts at \fBI\fR and continues
689 until \fBJ\fR.\& \fBI\fR and \fBJ\fR can be negative to index from the string'\&s end.\&
690 If \fBJ\fR is absent, then it is assumed to be equal to \fB-1\fR
691 (ie.\& string end).\&
692 .PP
693 Added: 4.\&19.\&0
694 .PP
695 Example:
696 .nf
697 .RS 4
698 *%{sub myfile\&.zip 3 6}*
699 .fi
700 .RE
701 .PP
702 .RE
703 \fB%{upper:\fR\fISTRING\fR\fB}\fR
704 .RS 4
705 Expand to uppercase \fISTRING\fR.\& (Added: 4.\&19.\&0)
706 .PP
707 Example:
708 .nf
709 .RS 4
710 %{upper:CamelCase}\&'
711 .fi
712 .RE
713 .PP
714 .RE
715 .SS File and path operations
716 \fB%{basename:\fR\fIPATH\fR\fB}\fR
717 .RS 4
718 \fBbasename\fR(1) macro analogue.\&
719 .PP
720 Example:
721 .nf
722 .RS 4
723 %{basename:/some/dir/file\&.suf}
724 .fi
725 .RE
726 .PP
727 .RE
728 \fB%{dirname:\fR\fIPATH\fR\fB}\fR
729 .RS 4
730 \fBdirname\fR(1) macro analogue.\&
731 .PP
732 Example:
733 .nf
734 .RS 4
735 %{dirname:/some/dir/file\&.suf}
736 .fi
737 .RE
738 .PP
739 .RE
740 \fB%{exists:\fR\fIPATH\fR\fB}\fR
741 .RS 4
742 Test file existence, expands to 1/0.\& (Added: 4.\&18.\&0)
743 .PP
744 Example:
745 .nf
746 .RS 4
747 %{exists:%{builddir}/myflag\&.txt}
748 .fi
749 .RE
750 .PP
751 .RE
752 \fB%{suffix:\fR\fIPATH\fR\fB}\fR
753 .RS 4
754 Expand to suffix part of a filename.\&
755 .PP
756 Example:
757 .nf
758 .RS 4
759 %{suffix:myfile\&.zip}
760 .fi
761 .RE
762 .PP
763 .RE
764 \fB%{url2path:\fR\fIURL\fR\fB}\fR
765 .RS 4
766 Convert url to a local path.\&
767 .PP
768 Example:
769 .nf
770 .RS 4
771 %{url2path:http://rpm\&.org/not/there}
772 .fi
773 .RE
774 .PP
775 .RE
776 \fB%{uncompress:\fR\fIPATH\fR\fB}\fR
777 .RS 4
778 Expand to a command for outputting argument \fIPATH\fR to standard output,
779 uncompressing as needed.\&
780 .PP
781 Example:
782 .nf
783 .RS 4
784 %{uncompress /my/source\&.tar\&.gz}
785 .fi
786 .RE
787 .PP
788 .RE
789 \fB%{xdg:\fR\fIKIND\fR\fB}\fR
790 .RS 4
791 Expand to XDG base directory paths.\& Supported values for \fIKIND\fR are:
792 .PD 0
793 .IP \(bu 4
794 \fBcache\fR: user-specific non-essential (cached) data
795 .IP \(bu 4
796 \fBconfig\fR: user-specific configuration files
797 .IP \(bu 4
798 \fBdata\fR: user-specific data files
799 .IP \(bu 4
800 \fBstate\fR: user-specific state data
801 .PD
802 .PP
803 Added: 6.\&0.\&0
804 .PP
805 Example:
806 .nf
807 .RS 4
808 %{xdg config}
809 .fi
810 .RE
811 .PP
812 .RE
813 .SS Environment info
814 \fB%getncpus\fR
815 .RS 4
816 Expand to the number of available CPUs.\& (Added: 4.\&15.\&0)
817 .PP
818 .RE
819 \fB%{getncpus:\fR\fIKIND\fR\fB}\fR
820 .RS 4
821 Expand to the number of available CPUs, supported valued for \fIKIND\fR are
822 .PD 0
823 .IP \(bu 4
824 \fBtotal\fR: total number of available CPUs (same as \fB%getncpus\fR)
825 .IP \(bu 4
826 \fBproc\fR: number of available CPUs for processes
827 .IP \(bu 4
828 \fBthread\fR: number of available CPUs for threads
829 .PD
830 .PP
831 \fBproc\fR and \fBthread\fR account for available memory, including
832 address space limitations for threads.\&
833 .PP
834 Added: 4.\&19.\&0.\&
835 .PP
836 Example:
837 .nf
838 .RS 4
839 %{getncpus proc}
840 .fi
841 .RE
842 .PP
843 .RE
844 \fB%getconfdir\fR
845 .RS 4
846 Expand to RPM "home" directory (typically /usr/lib/rpm).\&
847 .PP
848 .RE
849 \fB%{getenv:\fR\fINAME\fR\fB}\fR
850 .RS 4
851 \fBgetenv\fR(3) macro analogue.\&
852 .PP
853 Example:
854 .nf
855 .RS 4
856 %{getenv:HOME}
857 .fi
858 .RE
859 .PP
860 .RE
861 \fB%rpmversion\fR
862 .RS 4
863 Expand to running RPM version.\&
864 .PP
865 .RE
866 .SS Output
867 \fB%{echo:\fR\fISTRING\fR\fB}\fR
868 .RS 4
869 Print \fISTRING\fR to process standard output.\&
870 .PP
871 Example:
872 .nf
873 .RS 4
874 %{echo:Building with foo}
875 .fi
876 .RE
877 .PP
878 .RE
879 \fB%{warn:\fR\fISTRING\fR\fB}\fR
880 .RS 4
881 Print \fISTRING\fR prefixed with "warning: " to process standard error.\&
882 .PP
883 Example:
884 .nf
885 .RS 4
886 %{warning:Foo is deprecated}
887 .fi
888 .RE
889 .PP
890 .RE
891 \fB%{error:\fR\fISTRING\fR\fB}\fR
892 .RS 4
893 Print \fISTRING\fR prefixed with "error: " to process standard error and
894 flag an error in the macro processor.\&
895 .PP
896 Example:
897 .nf
898 .RS 4
899 %{error:Invalid argument}
900 .fi
901 .RE
902 .PP
903 .RE
904 \fB%verbose\fR
905 .RS 4
906 Expand to 1/0 whether RPM is in verbose mode or not.\& (Added: 4.\&17.\&1)
907 .PP
908 .RE
909 \fB%{verbose:\fR\fISTRING\fR\fB}\fR
910 .RS 4
911 Expand to \fISTRING\fR if RPM is in verbose mode, the empty string if not.\&
912 (Added: 4.\&17.\&1)
913 .PP
914 Example:
915 .nf
916 .RS 4
917 %{verbose:-x}
918 .fi
919 .RE
920 .PP
921 .RE
922 .SS Spec specific macros
923 \fB%{S:\fR\fINUMBER\fR\fB}\fR
924 .RS 4
925 Expand to the filename of the specified Source \fINUMBER\fR.\&
926 \fB%{S:n}\fR is equivalent to \fB%{SOURCEn}\fR.\&
927 .PP
928 .RE
929 \fB%{P:\fR\fINUMBER\fR\fB}\fR
930 .RS 4
931 Expand to the filename of the specified Patch \fINUMBER\fR.\&
932 \fB%{P:n}\fR is equivalent to \fB%{PATCHn}\fR.\&
933 .PP
934 .RE
935 .SS Diagnostics
936 \fB%trace\fR
937 .RS 4
938 Toggle print of debugging information before/after expansion.\&
939 .PP
940 .RE
941 \fB%dump\fR
942 .RS 4
943 Print the active (i.\&e.\& non-covered) macro table.\&
944 .PP
945 .RE
946 \fB%__file_name\fR
947 .RS 4
948 Expand to current filename (if parsing a file).\& (Added: 4.\&15)
949 .PP
950 .RE
951 \fB%__file_lineno\fR
952 .RS 4
953 Expand to current line number in current file (if parsing a file).\&
954 (Added: 4.\&15)
955 .PP
956 .RE
957 .SH EXAMPLES
958 .SS Example 1. Define a simple macro
959 Define macro \fBmylib\fR to a path relative to \fB%{_libdir}\fR macro in a spec:
960 .PP
961 .nf
962 .RS 4
963 %define mylib %{_libdir}/mine
964 .fi
965 .RE
966 .PP
967 .SS Example 2. Define a parametric macro
968 Define parametric macro \fBmyhelper\fR which executes the program
969 specified by \fB%myprog\fR with it'\&s first argument and always passing
970 the option \fB--some-opt\fR to it, and additionally the \fB--xtra\fR option
971 if it received the \fB-x\fR option itself:
972 .PP
973 .nf
974 .RS 4
975 %define myhelper(x) %{myprog} --some-opt %{?-x:--xtra} %{1}
976 .fi
977 .RE
978 .PP
979 .SS Example 3. Define a macro utilizing shell expansion
980 Define macro \fB%today\fR that expands to the current date in \fIYYMMDD\fR
981 format by calling the \fBdate\fR(1) shell utility.\&
982 Note the 2nd \fB%\fR needed to escape the arguments to \fBdate\fR(1):
983 .PP
984 .nf
985 .RS 4
986 %define today %(date +%%y%%m%%d)
987 .fi
988 .RE
989 .PP
990 .SS Example 4. Define a macro conditionally
991 Define macro \fBmypath\fR if it wasn'\&t previously defined:
992 .PP
993 .nf
994 .RS 4
995 %{!?mypath: %define mypath /some/where}
996 .fi
997 .RE
998 .PP
999 .SS Example 5. Conditional expansion
1000 Expands to \fB1\fR if \fBuse_foo\fR is defined and \fB0\fR otherwise:
1001 .PP
1002 .nf
1003 .RS 4
1004 %{?use_foo:1}%{!?use_foo:0}
1005 .fi
1006 .RE
1007 .PP
1008 .SS Example 6. Expressions
1009 Calculate 5 * 1024:
1010 .PP
1011 .nf
1012 .RS 4
1013 %[5 * 1024]
1014 .fi
1015 .RE
1016 .PP
1017 Expand to literal \fBtrue\fR or \fBfalse\fR depending on a condition:
1018 .PP
1019 .nf
1020 .RS 4
1021 %[1 < 2 ? "true" : "false"]
1022 .fi
1023 .RE
1024 .PP
1025 Compare versions, expanding to \fB1\fR or \fB0\fR on true/false:
1026 .PP
1027 .nf
1028 .RS 4
1029 %[ v"3\&.1\&.0-1" < v"1\&.0~alpha-2" ? 1 : 0]
1030 .fi
1031 .RE
1032 .PP
1033 Expands to \fB1\fR if \fB%aa\fR expands to \fB5\fR, otherwise expands to \fB2\fR:
1034 .PP
1035 .nf
1036 .RS 4
1037 %[ "%{aa}" == "5" ? 1 : 2]
1038 .fi
1039 .RE
1040 .PP
1041 .SH DEBUGGING
1042 Some useful tools for working with and troubleshooting macros:
1043 .PP
1044 \fBrpm --eval "\fR\fIVALUE\fR\fB"\fR
1045 .RS 4
1046 Expand \fIVALUE\fR on the command line.\&
1047 .PP
1048 .RE
1049 \fBrpm --define "aa 11" --eval "%aa"\fR
1050 .RS 4
1051 Define and evaluate a macro on the command line.\&
1052 .PP
1053 .RE
1054 \fBrpm --eval "%global unamer %(uname -r)" --eval "%{macrobody:unamer}"\fR
1055 .RS 4
1056 Define and examine macro body using \fB%global\fR on the command line.\&
1057 .PP
1058 .RE
1059 \fBrpm --eval "%define unamer %(uname -r)" --eval "%{macrobody:unamer}"\fR
1060 .RS 4
1061 Define and examine macro body using \fB%define\fR on the command line.\&
1062 .PP
1063 .RE
1064 \fBrpmlua\fR
1065 .RS 4
1066 Run an interactive shell in the embedded Lua environment.\&
1067 .PP
1068 .RE
1069 \fBrpmlua -e '\&print(macros.\&defined("_libdir"))'\&\fR
1070 .RS 4
1071 Using the embedded Lua interpreter in standalone form, print
1072 print 1/0 whether macro \fB_libdir\fR is defined or not.\&
1073 .PP
1074 .RE
1075 \fBrpmspec --shell\fR
1076 .RS 4
1077 Run an interactive shell in the macro environment.\&
1078 .PP
1079 .RE
1080 \fBrpmspec --shell telnet.\&spec\fR
1081 .RS 4
1082 Run an interactive shell in the macro environment after parsing
1083 \fBtelnet.\&spec\fR.\&
1084 .PP
1085 .RE
1086 .SH SEE ALSO
1087 \fBrpm\fR(8) \fBrpm-common\fR(8) \fBrpm-macrofile\fR(5) \fBrpm-config\fR(5) \fBrpm-lua\fR(7)
1088 \fBrpmspec\fR(1) \fBrpmlua\fR(1)