1RPKG(MACRO) RPKG(MACRO)
2
6 Rpkg macro reference
7 NOTE:
9 rpkg macro is a bash function that outputs to stdout certain part of
10 rpm spec file. Don't confuse it with rpm macro which is part of the
11 rpm spec file syntax itself. Essentially, rpkg macro is something
12 that can output an rpm macro (or even a sequence of them) to stdout.
13 rpkg macros are intended to be translated into their respective std‐
14 outs (in other words, "executed") by preproc utility and you will
15 therefore see them in a spec file enclosed triple braces (e.g. {{{
16 <macro_name> }}}) which are the preproc specific tags used to dif‐
17 ferentiate macro invocations from the normal text.
18
20 Example spec file with the rpkg macros used:
21 Name: {{{ git_dir_name }}}
23 Version: {{{ git_dir_version }}}
24 Release: 1%{?dist}
25 Summary: This is a test package.
27 VCS: {{{ git_dir_vcs }}}
28 License: GPLv2+
30 URL: https://someurl.org
31 Source0: {{{ git_dir_pack }}}
33 %description
35 This is a test package.
36 %prep
38 {{{ git_dir_setup_macro }}}
39 %changelog
41 {{{ git_dir_changelog }}}
42 Other examples can be found online at the addresses below. You can
44 experiment with those by using rpkg tool which understands those spec
45 files and can translate them to regular spec files.
46 https://pagure.io/hello_rpkg/blob/master/f/hello_rpkg.spec.rpkg
48 https://pagure.io/hello_rpkg_release/blob/master/f/hello_rpkg.spec.rpkg
49
51 Those macros provide the base implementation for other macro types like
52 e.g. git_dir macros (see later in this document). They can be, however,
53 used directly as well. Unless otherwise specified in their description,
54 they operate on git repository top-level for the current working direc‐
55 tory.
56 Output of every base git macro call is cached and other macros are made
58 to take those cached values into account by default. You can see that a
59 macro uses a cached value as an input parameter default value by look‐
60 ing at its function header definition and searching for the OUTPUT key‐
61 word.
62 E.g.
64 git_version [name="${OUTPUT[git_name]}"] [lead=0] [follow=]
65 Default value for name in this definition is derived from the cached
67 output of the previously invoked git_name macro or its derivative, e.g.
68 git_dir_name (in which case, the cache key is still git_name). If
69 git_name macro or its derivative has not been invoked or if its output
70 was an empty string, the default value for the name= parameter above
71 will be also an empty string.
72 "Subpackage" in the definitions below is a set of annotated tags with a
74 common Name. Such set of tags in a git project usually corresponds to a
75 certain (sub)directory with a spec file in it.
76 ----
79 git_name [name=] [prepend=] [append=]
83 Without any parameters, looks up remote URL for the currently active
85 branch and outputs its basename with .git suffix stripped. If the
86 remote URL could not be determined, "origin" remote URL is used
87 instead.
88 Optional arguments:
90 name the base name to be output
92 prepend
94 string to be prepended to the base name
95 append string to be appended to the base name
97 ----
100 git_version [name="${OUTPUT[git_name]}"] [lead=0] [follow=]
104 Outputs version of a subpackage given by name. The version is computed
106 from the current commit, state of the work tree, and also from the lat‐
107 est** reachable annotated tag of N-V-R form (N-V-R stands for the
108 Name-Version-Release rpm triplet) with a matching Name (i.e. equal to
109 ${name}) and Lead (but only if lead parameter is non-empty). Lead is
110 defined as a substring of Version before the last dot (note that for
111 the git_release macro below, it is defined as substring of Release
112 before the last dot, instead). Complementary to Lead, there is Follow
113 which is the version part of the tag after the last dot.
114 The version string that git_version produces is generally composed of
116 the following parts (some of those parts might end up empty in certain
117 cases):
118 ${lead}.${follow}${commit_count_appendix}${dirty_appendix}
119 lead is a major version substring. By default, it is set to zero. It is
121 intended to be manually incremented on API/ABI changes. It can contain
122 multiple components separated by dot (e.g. 2.1).
123 If lead parameter is set to empty, its value will be automatically
125 derived from Lead of the latest (reachable) annotated tag for the sub‐
126 package given by name. If there is no such tag, lead will be empty and
127 the dot after it will not be rendered.
128 follow is a minor version substring. It can contain only a single com‐
130 ponent (i.e. it cannot contain any dots).
131 If follow parameter is empty, it will be obtained from Follow of the
133 latest tag of a matching Name and also Lead if lead parameter is
134 non-empty. If there is no such tag, the resulting follow will be 0.
135 commit_count_appendix is generated only if the current commit is not
137 tagged for the given subpackage. It is composed of the following parts:
138 .git.${commit_count}.${current_commit_short_hash}
139 commit_count is a number of commits from the latest tag to the current
141 commit for the given subpackage.
142 current_commit_short_hash is a short (8-chars long) hash of the current
144 commit.
145 dirty_appendix is generated only if the currently checked out work tree
147 is dirty. It is composed of the following parts:
148 .dirty.${encoded_latest_file_status_change_time}
149 encoded_latest_file_status_change_time is an encoded time of the latest
151 file status change that happened in the work tree. That way we can have
152 the version increased each time we make a change in our work tree with‐
153 out committing.
154 Optional arguments:
156 name name of a subpackage
158 lead major version substring, dynamically derived if set to
160 empty
161 follow minor version substring, dynamically derived if not
163 specified
164 Environment variables:
166 VERSION_BUMP: if set to a non-empty value, the following pro‐
167 cedure is applied to get the version string:
168 If follow is specified by user explicitly, output
170 ${lead}.${follow}.
171 Otherwise, extract follow from the latest tag of a matching
173 Name and Lead (if lead is non-empty) as the last version com‐
174 ponent (the component after the last dot of Version) and out‐
175 put ${lead}.${follow}+1. If the extracted ${follow} is not a
176 number, throw an error (manual setting of follow is needed in
177 this case).
178 NOTE: rpkg command-line utility sets the VERSION_BUMP vari‐
180 able into the preprocessing environment during execution of
181 rpkg tag subcommand. Otherwise, it is unset.
182 ** "latest" is defined by a topological sort as the first criterion and
184 rpm version sort as the second (supplementary) criterion where the
185 topological sort is not enough to decide. The tool that implements this
186 sorting algorithm is called rpm-git-tag-sort. Note that in this arti‐
187 cle, we sometimes say only "the latest tag" while the real meaning is
188 "the latest reachable annotated tag" (i.e. "reachable" and "annotated"
189 is always implied).
190 ----
193 git_release [name="${OUTPUT[git_name]}"] [lead=] [follow=]
197 Outputs release of a subpackage given by ${name}. The release string
199 contains the same parts as the version string for git_version:
200 ${lead}.${follow}${commit_count_appendix}${dirty_appendix}
201 and is computed in a similar fashion to the version string, i.e. based
203 on the current commit, state of the work tree, and based on the latest
204 reachable annotated tag of N-V-R form with a matching Name and Lead if
205 lead is non-empty.
206 For git_release, however, we extract all the information from the
208 Release part of that tag. In other words, Lead, lead, and follow
209 relate to Release for this macro but otherwise their meaning stays the
210 same as for git_version (i.e. Lead is the part of a version string
211 before the last dot, lead is used to match against Lead, follow, if
212 specified, is used instead of Follow of the latest tag).
213 Additionally, lead (the input parameter, therefore lowercase 'l', as
215 opposed to Lead - the tag substring) is empty by default for
216 git_release.
217 Optional arguments:
219 name name of a subpackage
221 lead major version substring, dynamically derived if not
223 specified
224 follow minor version substring, dynamically derived if not
226 specified
227 Environment variables:
229 RELEASE_BUMP: if set to a non-empty value, the same procedure
230 is applied to get a bumped value as for git_version except we
231 again apply the terms Lead, lead, and follow to Release
232 instead of Version. Please, see git_version above for more
233 information.
234 NOTE: rpkg utility sets the RELEASE_BUMP variable into the
236 preprocessing environment during execution of rpkg tag sub‐
237 command. Otherwise, it is unset.
238 ----
241 git_release_branched
245 Uses the current branch name as lead parameter for git_release. In
247 other words, equivalent of:
248 git_release lead="$GIT_BRANCH"
250 NOTE: the output value will be cached under git_release, not under
252 git_release_branched.
253 ----
256 git_changelog [name="${OUTPUT[git_name]}"] [since_tag=] [until_tag=] [header_locale=POSIX] [header_date_format="%a %b %d %Y"] [body_wrap=80]
260 Outputs rpm spec changelog as generated from tag messages for the sub‐
262 package given by name.
263 Optional arguments:
265 name name of the subpackage to generate the changelog for
267 since_tag
269 start the changelog records with this tag
270 until_tag
272 end the changelog records with this tag
273 header_locale
275 locale to be used when changelog record date is being
276 generated
277 header_date_format
279 date format to be used in the changelog record headers
280 body_wrap
282 maximum allowed line length for changelog body
283 NOTE: When rpkg tag is called, it allows you to specify a tag message.
285 This is the message that will be used as a changelog record body.
286 ----
289 git_vcs path=
293 Outputs pseudo repository URL pointing to the respective path in the
295 currently checked out tree. Ideally, the output should contain a pub‐
296 licly available clone URL as a substring when this macro is used for
297 production purposes.
298 Example output:
300 git+https://pagure.io/test-project.git#dadef2a8b9554e94797a7336261192e02d5d9351:sub‐
301 dir
302 Required arguments:
304 path path to a subtree to generate the URL for
306 ----
309 git_pack path= [dir_name=] [source_name=]
313 Packs the whole work tree content into a gzipped source tarball and
315 outputs ${source_name} which is a filename of the created tarball. It
316 omits submodules, untracked and also git-ignored content. While submod‐
317 ules are being omitted when on subpath of the given path, you can actu‐
318 ally point the path into a submodule (e.g. into its top-level direc‐
319 tory), in which case, the submodule content will be packed obeying the
320 same rules as when the parent's git repository own path would be
321 packed.
322 If work tree is dirty, it uses GNU tar to do the job but if the tree is
324 clean, git_pack actually becomes a proxy to git_archive macro below and
325 instead treeish from the current commit is used as the source content
326 instead of the work tree (the two contents are the same at this point,
327 however). The reason is that git archive packing method has an advan‐
328 tage that the resulting tarball will have a PAX header identifying the
329 source commit (see man git-get-tar-commit-id), which can be later used
330 for package verification and further processing. This method allows
331 packing from a dirty tree for testing purposes while producing track‐
332 able, production-ready archives when work tree is clean.
333 Required arguments:
335 path path to a specific subdirectory to be packed
337 Optional arguments:
339 dir_name
341 top-level directory name in the created tarball
342 source_name
344 filename of the created source tarball
345 Environment variables:
347 OUTDIR: if empty, git_pack will not generate any sources,
348 only the source filename will be output, otherwise determines
349 where to put the generated tarball
350 NOTE: rpkg utility sets OUTDIR, only if the tarball is actu‐
352 ally needed to be generated. It does not set it when just
353 rpkg spec is called (without any additional arguments).
354 ----
357 git_archive path= [dir_name=] [source_name=]
361 Packs the latest commit tree content into a gzipped source tarball and
363 output ${source_name}, which is a filename of the created tarball. Uses
364 git archive to do the job. The result will contain a PAX header with
365 the commit ID from which the tarball was created. This information can
366 be later extracted by git-get-tar-commit-id.
367 Required arguments:
369 path path to a specific subdirectory to be packed
371 Optional arguments:
373 dir_name
375 top-level directory name in the created tarball
376 source_name
378 filename of the created source tarball
379 Environment variables:
381 OUTDIR: if empty, git_archive will not generate any sources,
382 only the source filename will be output, otherwise determines
383 where to put the generated tarball
384 NOTE: rpkg utility sets OUTDIR, only if the tarball is actu‐
386 ally needed to be generated. It does not set it when rpkg
387 spec is called (without any additional arguments).
388 ----
391 git_setup_macro [dir_name=] [path=] [source_indices=0]
395 Outputs %setup rpm macro call with the appropriate parameters for the
397 given path or dir_name. This will unpack one or multiple source tar‐
398 balls defined by the Source definitions in a spec file. This macro is
399 primarily designed to be called in %prep section of spec file to unpack
400 sources for %build phase.
401 Either dir_name or path needs to be specified. This macro is complemen‐
403 tary to git_pack and git_archive macros and is assumed to be used if
404 one of those macros is used in a spec file.
405 Optional arguments:
407 dir_name
409 name of the top-level directory in the source-tarball
410 path path from which dir_name is derived if it is not spec‐
412 ified
413 source_indices
415 Source numbers separated by comma to generate the
416 %setup macro for, by default 0
417
419 These macros operate on a directory level. In particular, on a direc‐
420 tory where the input spec file is located. The location of the spec
421 file is assumed to be stored in INPUT_PATH environment variable. There
422 is also INPUT_DIR_PATH which stores path to the directory where the
423 spec file is located (i.e. INPUT_PATH with the last component
424 stripped).
425 In essence, the git_dir macros are tiny wrappers over the base git
427 macros which are being invoked with some input parameters set specifi‐
428 cally for the spec-file's subdirectory operation.
429 The git_dir macros have the same input parameters as the respective
431 base git macros and the values specified by user are directly passed
432 down to the base macros and will also override values of those parame‐
433 ters that the derived macro sets itself (you will see those parameters
434 in the definitions below).
435 NOTE: the git_dir macros are the recommended ones to use from all the
437 macro types. Use them unless you would need to override a value that
438 the the macro sets itself. In that case, the base git macros are a bet‐
439 ter choice.
440 NOTE: rpkg utility allows you to specify the INPUT_PATH environment
442 variable through --spec <path> argument for certain rpkg subcommands
443 that support it.
444 Below you can see to what the git_dir macros expand. Passing all input
446 parameters down to the base git macro, if any are specified, is
447 implicit (i.e. not mentioned below).
448 ----
451 git_dir_name
455 git_name append="$(git_prefix "$INPUT_DIR_PATH" | git_prefix_to_name_suffix)"
457 Outputs remote URL basename appended with the path (after slash to dash
459 substitution) from the repository root to the spec file's directory.
460 ----
463 git_dir_version
467 git_version name="$(git_dir_name)"
469 Outputs version of a subpackage by name $(git_dir_name).
471 ----
474 git_dir_release
478 git_release name="$(git_dir_name)"
480 Outputs release of a subpackage by name $(git_dir_name).
482 ----
485 git_dir_release_branched
489 git_release_branched name="$(git_dir_name)"
491 Outputs branched release of a subpackage by name $(git_dir_name).
493 ----
496 git_dir_changelog
500 git_changelog name="$(git_dir_name)"
502 Outputs changelog of a subpackage by name $(git_dir_name).
504 ----
507 git_dir_vcs
511 git_vcs path="$INPUT_DIR_PATH"
513 Outputs VCS pseudo URL pointing to the spec file's subdirectory.
515 ----
518 git_dir_pack
522 git_pack path="$INPUT_DIR_PATH"
524 Packs spec file's subdirectory by using GNU tar (for a dirty repo) or
526 git archive (for a clean repo).
527 ----
530 git_dir_archive
534 git_archive path="$INPUT_DIR_PATH"
536 Packs spec file's subdirectory by using git archive.
538 ----
541 git_dir_setup_macro
545 git_setup_macro path="$INPUT_DIR_PATH"
547 Outputs rpm's %setup macro with dir_name (-n argument of %setup) gener‐
549 ated according to the remote URL basename and the spec file's subdirec‐
550 tory path. If you used git_dir_pack or git_dir_archive for packing, use
551 this macro in %prep spec file section for preparing the sources for rpm
552 build.
553
555 Similarly to git_dir macros, these macros operate on a directory level.
556 In this case, it is the current working directory (obtained from PWD
557 environment variable). These macros are, in fact, just tiny wrappers
558 over the base git macros with some input parameters specifically set
559 for operation on the current working directory.
560 NOTE: With rpkg utility, you can influence the working dir from the
562 command line by explicitly specifying its --path argument.
563 Below you can see to what the git_cwd macros expand. Passing all input
565 parameters down to the base git macro, if any are specified, is
566 implicit (i.e. not mentioned below).
567 ----
570 git_cwd_name
574 git_name append="$(git_prefix "$PWD" | git_prefix_to_name_suffix)"
576 Outputs remote URL basename appended with the path from the repository
578 root to the current working directory (after slash to dash substitu‐
579 tion).
580 ----
583 git_cwd_version
587 git_version name="$(git_cwd_name)"
589 Outputs version of a subpackage by name $(git_cwd_name).
591 ----
594 git_cwd_release
598 git_release name="$(git_cwd_name)"
600 Outputs release of a subpackage by name $(git_cwd_name).
602 ----
605 git_cwd_release_branched
609 git_release_branched name="$(git_cwd_name)"
611 Outputs branched release of a subpackage by name $(git_cwd_name).
613 ----
616 git_cwd_changelog
620 git_changelog name="$(git_cwd_name)"
622 Outputs changelog of a subpackage by name $(git_cwd_name).
624 ----
627 git_cwd_vcs
631 git_vcs path="$PWD"
633 Outputs VCS pseudo URL pointing to the current working directory.
635 ----
638 git_cwd_pack
642 git_pack path="$PWD"
644 Packs working directory by using GNU tar (for a dirty repo) or git ar‐
646 chive (for a clean repo).
647 ----
650 git_cwd_archive
654 git_archive path="$PWD"
656 Packs working directory by using git archive.
658 ----
661 git_cwd_setup_macro
665 git_setup_macro path="$PWD"
667 Outputs rpm's %setup macro with dir_name (-n argument of %setup) auto‐
669 matically generated according to the remote URL basename and the cur‐
670 rent working directory path. If you used git_cwd_pack or git_cwd_ar‐
671 chive for packing, use this macro in %prep spec file section for pre‐
672 paring the sources for rpm build.
673
675 These macros operate on the root (top-level) directory of the current
676 git repository. Path to that directory is stored in GIT_ROOT environ‐
677 ment variable. Implementation-wise, these macros are just tiny wrappers
678 over the git base macros with some input values set specifically for
679 repository-wide operation.
680 WARNING:
682 If your local git repository is not properly initialized or if, for
683 example, the .git metadata directory in your local tree has been
684 renamed or removed, operation of the repo macros can get out of the
685 intended scope. It is therefore recommended to use more specific
686 git_dir_* macros wherever possible, which are always bound to the
687 directory where the input spec file is located. This is especially
688 important for the tarball creating macros (i.e. *_pack and *_archive
689 ones).
690 Below you can see to what the git_repo macros expand. Passing all input
692 parameters down to the base git macro, if any are specified, is
693 implicit (i.e. not mentioned below).
694 ----
697 git_repo_name
701 git_name
703 Outputs remote URL basename with .git suffix stripped. git_repo_name
705 and git_name are direct equivalents.
706 ----
709 git_repo_version
713 git_version name="$(git_repo_name)"
715 Outputs version of a subpackage by name $(git_repo_name).
717 ----
720 git_repo_release
724 git_release name="$(git_repo_name)"
726 Outputs release of a subpackage by name $(git_repo_name).
728 ----
731 git_repo_release_branched
735 git_release_branched name="$(git_repo_name)"
737 Outputs branched release of a subpackage by name $(git_repo_name).
739 ----
742 git_repo_changelog
746 git_changelog name="$(git_repo_name)"
748 Outputs changelog of a subpackage by name $(git_repo_name).
750 ----
753 git_repo_vcs
757 git_vcs path="$GIT_ROOT"
759 Outputs VCS pseudo URL pointing to the repository.
761 ----
764 git_repo_pack
768 git_pack path="$GIT_ROOT"
770 Packs the whole repository (with the standard omissions like
772 git-ignored content or git submodules, see documentation for git_pack
773 regarding this) by using GNU tar (for a dirty repo) or git archive (for
774 a clean repo).
775 ----
778 git_repo_archive
782 git_archive path="$GIT_ROOT"
784 Packs the git repository content by using git archive.
786 ----
789 git_repo_setup_macro
793 git_setup_macro path="$GIT_ROOT"
795 Outputs rpm's %setup macro with dir_name (-n argument of %setup) gener‐
797 ated from basename of the repository remote URL. If you used
798 git_repo_pack or git_repo_archive for packing, use this macro in %prep
799 spec file section for preparing the sources for rpm build.
800 REFERENCE RPKG(MACRO)