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 ex‐
44 periment 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 (derived) macro
52 types like e.g. git_dir macros (see later in this document). They can
53 be, however, used directly as well. Unless otherwise specified in their
54 description, they operate on git repository top-level for the directory
55 where the input spec file is located.
56 The directory location of the input spec file should be provided by
58 user or upper tooling through INPUT_DIR_PATH environment variable (it
59 should be provided even if the derived macros are used instead of the
60 base ones). If this variable is not provided, its value will be derived
61 from INPUT_PATH environment variable by stripping the last path compo‐
62 nent. If neither INPUT_DIR_PATH nor INPUT_PATH are provided, the IN‐
63 PUT_DIR_PATH variable will be set automatically to ., i.e. the current
64 working directory (the only purpose of this default is to allow for
65 easy experimentation with the macros on command-line).
66 Output of every base git macro call is cached and other macros are made
68 to take those cached values into account by default. You can see that a
69 macro uses a cached value as an input parameter default value by look‐
70 ing at its function header definition and searching for the OUTPUT key‐
71 word.
72 E.g.
74 git_version [name="${OUTPUT[git_name]}"] [lead=0] [follow=]
75 Default value for name in this definition is obtained from the cached
77 output of the previously invoked git_name macro or its derivative, e.g.
78 git_dir_name (in which case, the cache key is still git_name). If
79 git_name macro or its derivative has not been invoked or if its output
80 was an empty string, the default value for the name= parameter above
81 will be also an empty string.
82 "Subpackage" in the definitions below is a set of annotated tags with a
84 common Name. Such set of tags in a git project usually corresponds to a
85 certain (sub)directory with a spec file in it.
86 ----
89 git_name [name=] [prepend=] [append=]
93 Without any parameters, looks up remote URL for the currently active
95 branch and outputs its basename with .git suffix stripped. If the re‐
96 mote URL could not be determined, "origin" remote URL is used instead.
97 Optional arguments:
99 name the base name to be output
101 prepend
103 string to be prepended to the base name
104 append string to be appended to the base name
106 ----
109 git_version [name="${OUTPUT[git_name]}"] [lead=0] [follow=]
113 Outputs version of a subpackage given by name. The version is computed
115 from the current commit, state of the work tree, and also from the lat‐
116 est** reachable annotated tag of N-V-R form (N-V-R stands for the
117 Name-Version-Release rpm triplet) with a matching Name (i.e. equal to
118 ${name}) and Lead (but only if lead parameter is non-empty). Lead is
119 defined as a substring of Version before the last dot (note that for
120 the git_release macro below, it is defined as substring of Release be‐
121 fore the last dot, instead). Complementary to Lead, there is Follow
122 which is the version part of the tag after the last dot.
123 The version string that git_version produces is generally composed of
125 the following parts (some of those parts might end up empty in certain
126 cases):
127 ${lead}.${follow}${commit_count_appendix}${dirty_appendix}
128 lead is a major version substring. By default, it is set to zero. It is
130 intended to be manually incremented on API/ABI changes. It can contain
131 multiple components separated by dot (e.g. 2.1).
132 If lead parameter is set to empty, its value will be automatically de‐
134 rived from Lead of the latest (reachable) annotated tag for the sub‐
135 package given by name. If there is no such tag, lead will be empty and
136 the dot after it will not be rendered.
137 follow is a minor version substring. It can contain only a single com‐
139 ponent (i.e. it cannot contain any dots).
140 If follow parameter is empty, it will be obtained from Follow of the
142 latest tag of a matching Name and also Lead if lead parameter is
143 non-empty. If there is no such tag, the resulting follow will be 0.
144 commit_count_appendix is generated only if the current commit is not
146 tagged for the given subpackage. It is composed of the following parts:
147 .git.${commit_count}.${current_commit_short_hash}
148 commit_count is a number of commits from the latest tag to the current
150 commit for the given subpackage.
151 current_commit_short_hash is a short (8-chars long) hash of the current
153 commit.
154 dirty_appendix is generated only if the currently checked out work tree
156 is dirty. It is composed of the following parts:
157 .dirty.${encoded_latest_file_status_change_time}
158 encoded_latest_file_status_change_time is an encoded time of the latest
160 file status change that happened in the work tree. That way we can have
161 the version increased each time we make a change in our work tree with‐
162 out committing.
163 Optional arguments:
165 name name of a subpackage
167 lead major version substring, dynamically derived if set to
169 empty
170 follow minor version substring, dynamically derived if not
172 specified
173 Environment variables:
175 VERSION_BUMP: if set to a non-empty value, the following pro‐
176 cedure is applied to get the version string:
177 If follow is specified by user explicitly, output
179 ${lead}.${follow}.
180 Otherwise, extract follow from the latest tag of a matching
182 Name and Lead (if lead is non-empty) as the last version com‐
183 ponent (the component after the last dot of Version) and out‐
184 put ${lead}.${follow}+1. If the extracted ${follow} is not a
185 number, throw an error (manual setting of follow is needed in
186 this case).
187 NOTE: rpkg command-line utility sets the VERSION_BUMP vari‐
189 able into the preprocessing environment during execution of
190 rpkg tag subcommand. Otherwise, it is unset.
191 ** "latest" is defined by a topological sort as the first criterion and
193 rpm version sort as the second (supplementary) criterion where the
194 topological sort is not enough to decide. The tool that implements this
195 sorting algorithm is called rpm-git-tag-sort. Note that in this arti‐
196 cle, we sometimes say only "the latest tag" while the real meaning is
197 "the latest reachable annotated tag" (i.e. "reachable" and "annotated"
198 is always implied).
199 ----
202 git_release [name="${OUTPUT[git_name]}"] [lead=] [follow=]
206 Outputs release of a subpackage given by ${name}. The release string
208 contains the same parts as the version string for git_version:
209 ${lead}.${follow}${commit_count_appendix}${dirty_appendix}
210 and is computed in a similar fashion to the version string, i.e. based
212 on the current commit, state of the work tree, and based on the latest
213 reachable annotated tag of N-V-R form with a matching Name and Lead if
214 lead is non-empty.
215 For git_release, however, we extract all the information from the Re‐
217 lease part of that tag. In other words, Lead, lead, and follow relate
218 to Release for this macro but otherwise their meaning stays the same as
219 for git_version (i.e. Lead is the part of a version string before the
220 last dot, lead is used to match against Lead, follow, if specified, is
221 used instead of Follow of the latest tag).
222 Additionally, lead (the input parameter, therefore lowercase 'l', as
224 opposed to Lead - the tag substring) is empty by default for git_re‐
225 lease.
226 Optional arguments:
228 name name of a subpackage
230 lead major version substring, dynamically derived if not
232 specified
233 follow minor version substring, dynamically derived if not
235 specified
236 Environment variables:
238 RELEASE_BUMP: if set to a non-empty value, the same procedure
239 is applied to get a bumped value as for git_version except we
240 again apply the terms Lead, lead, and follow to Release in‐
241 stead of Version. Please, see git_version above for more in‐
242 formation.
243 NOTE: rpkg utility sets the RELEASE_BUMP variable into the
245 preprocessing environment during execution of rpkg tag sub‐
246 command. Otherwise, it is unset.
247 ----
250 git_release_branched
254 Uses the current branch name as lead parameter for git_release. In
256 other words, equivalent of:
257 git_release lead="$GIT_BRANCH"
259 NOTE: the output value will be cached under git_release, not under
261 git_release_branched.
262 ----
265 git_changelog [name="${OUTPUT[git_name]}"] [since_tag=] [until_tag=] [header_locale=POSIX] [header_date_format="%a %b %d %Y"] [body_wrap=80]
269 Outputs rpm spec changelog as generated from tag messages for the sub‐
271 package given by name.
272 Optional arguments:
274 name name of the subpackage to generate the changelog for
276 since_tag
278 start the changelog records with this tag
279 until_tag
281 end the changelog records with this tag
282 header_locale
284 locale to be used when changelog record date is being
285 generated
286 header_date_format
288 date format to be used in the changelog record headers
289 body_wrap
291 maximum allowed line length for changelog body
292 NOTE: When rpkg tag is called, it allows you to specify a tag message.
294 This is the message that will be used as a changelog record body.
295 ----
298 git_vcs path=
302 Outputs pseudo repository URL pointing to the respective path in the
304 currently checked out tree. Ideally, the output should contain a pub‐
305 licly available clone URL as a substring when this macro is used for
306 production purposes.
307 Example output:
309 git+https://pagure.io/test-project.git#dadef2a8b9554e94797a7336261192e02d5d9351:sub‐
310 dir
311 Required arguments:
313 path path to a subtree to generate the URL for
315 ----
318 git_pack path= [dir_name=] [source_name=]
322 Packs the whole work tree content into a gzipped source tarball and
324 outputs ${source_name} which is a filename of the created tarball. It
325 omits submodules, untracked and also git-ignored content. While submod‐
326 ules are being omitted when on subpath of the given path, you can actu‐
327 ally point the path into a submodule (e.g. into its top-level direc‐
328 tory), in which case, the submodule content will be packed obeying the
329 same rules as when the parent's git repository own path would be
330 packed.
331 If work tree is dirty, it uses GNU tar to do the job but if the tree is
333 clean, git_pack actually becomes a proxy to git_archive macro below and
334 instead treeish from the current commit is used as the source content
335 instead of the work tree (the two contents are the same at this point,
336 however). The reason is that git archive packing method has an advan‐
337 tage that the resulting tarball will have a PAX header identifying the
338 source commit (see man git-get-tar-commit-id), which can be later used
339 for package verification and further processing. This method allows
340 packing from a dirty tree for testing purposes while producing track‐
341 able, production-ready archives when work tree is clean.
342 Required arguments:
344 path path to a specific subdirectory to be packed
346 Optional arguments:
348 dir_name
350 top-level directory name in the created tarball
351 source_name
353 filename of the created source tarball
354 Environment variables:
356 OUTDIR: if empty, git_pack will not generate any sources,
357 only the source filename will be output, otherwise determines
358 where to put the generated tarball
359 NOTE: rpkg utility sets OUTDIR, only if the tarball is actu‐
361 ally needed to be generated. It does not set it when just
362 rpkg spec is called (without any additional arguments).
363 ----
366 git_archive path= [dir_name=] [source_name=]
370 Packs the latest commit tree content into a gzipped source tarball and
372 output ${source_name}, which is a filename of the created tarball. Uses
373 git archive to do the job. The result will contain a PAX header with
374 the commit ID from which the tarball was created. This information can
375 be later extracted by git-get-tar-commit-id.
376 Required arguments:
378 path path to a specific subdirectory to be packed
380 Optional arguments:
382 dir_name
384 top-level directory name in the created tarball
385 source_name
387 filename of the created source tarball
388 Environment variables:
390 OUTDIR: if empty, git_archive will not generate any sources,
391 only the source filename will be output, otherwise determines
392 where to put the generated tarball
393 NOTE: rpkg utility sets OUTDIR, only if the tarball is actu‐
395 ally needed to be generated. It does not set it when rpkg
396 spec is called (without any additional arguments).
397 ----
400 git_setup_macro [dir_name=] [path=] [source_indices=0]
404 Outputs %setup rpm macro call with the appropriate parameters for the
406 given path or dir_name. This will unpack one or multiple source tar‐
407 balls defined by the Source definitions in a spec file. This macro is
408 primarily designed to be called in %prep section of spec file to unpack
409 sources for %build phase.
410 Either dir_name or path needs to be specified. This macro is complemen‐
412 tary to git_pack and git_archive macros and is assumed to be used if
413 one of those macros is used in a spec file.
414 Optional arguments:
416 dir_name
418 name of the top-level directory in the source-tarball
419 path path from which dir_name is derived if it is not spec‐
421 ified
422 source_indices
424 Source numbers separated by comma to generate the
425 %setup macro for, by default 0
426
428 These macros operate on a directory level. In particular, on a direc‐
429 tory where the input spec file is located. The location of the spec
430 file is assumed to be stored in INPUT_PATH environment variable. There
431 is also INPUT_DIR_PATH which stores path to the directory where the
432 spec file is located (i.e. INPUT_PATH with the last component
433 stripped).
434 In essence, the git_dir macros are tiny wrappers over the base git
436 macros which are being invoked with some input parameters set specifi‐
437 cally for the spec-file's subdirectory operation.
438 The git_dir macros have the same input parameters as the respective
440 base git macros and the values specified by user are directly passed
441 down to the base macros and will also override values of those parame‐
442 ters that the derived macro sets itself (you will see those parameters
443 in the definitions below).
444 NOTE: the git_dir macros are the recommended ones to use from all the
446 macro types. Use them unless you would need to override a value that
447 the the macro sets itself. In that case, the base git macros are a bet‐
448 ter choice.
449 NOTE: rpkg utility allows you to specify the INPUT_PATH environment
451 variable through --spec <path> argument for certain rpkg subcommands
452 that support it.
453 Below you can see to what the git_dir macros expand. Passing all input
455 parameters down to the base git macro, if any are specified, is im‐
456 plicit (i.e. not mentioned below).
457 ----
460 git_dir_name
464 git_name append="$(git_prefix "$INPUT_DIR_PATH" | git_prefix_to_name_suffix)"
466 Outputs remote URL basename appended with the path (after slash to dash
468 substitution) from the repository root to the spec file's directory.
469 ----
472 git_dir_version
476 git_version name="$(git_dir_name)"
478 Outputs version of a subpackage by name $(git_dir_name).
480 ----
483 git_dir_release
487 git_release name="$(git_dir_name)"
489 Outputs release of a subpackage by name $(git_dir_name).
491 ----
494 git_dir_release_branched
498 git_release_branched name="$(git_dir_name)"
500 Outputs branched release of a subpackage by name $(git_dir_name).
502 ----
505 git_dir_changelog
509 git_changelog name="$(git_dir_name)"
511 Outputs changelog of a subpackage by name $(git_dir_name).
513 ----
516 git_dir_vcs
520 git_vcs path="$INPUT_DIR_PATH"
522 Outputs VCS pseudo URL pointing to the spec file's subdirectory.
524 ----
527 git_dir_pack
531 git_pack path="$INPUT_DIR_PATH"
533 Packs spec file's subdirectory by using GNU tar (for a dirty repo) or
535 git archive (for a clean repo).
536 ----
539 git_dir_archive
543 git_archive path="$INPUT_DIR_PATH"
545 Packs spec file's subdirectory by using git archive.
547 ----
550 git_dir_setup_macro
554 git_setup_macro path="$INPUT_DIR_PATH"
556 Outputs rpm's %setup macro with dir_name (-n argument of %setup) gener‐
558 ated according to the remote URL basename and the spec file's subdirec‐
559 tory path. If you used git_dir_pack or git_dir_archive for packing, use
560 this macro in %prep spec file section for preparing the sources for rpm
561 build.
562
564 Similarly to git_dir macros, these macros operate on a directory level.
565 In this case, it is the current working directory (obtained from PWD
566 environment variable). These macros are, in fact, just tiny wrappers
567 over the base git macros with some input parameters specifically set
568 for operation on the current working directory.
569 NOTE: With rpkg utility, you can influence the working dir from the
571 command line by explicitly specifying its --path argument.
572 Below you can see to what the git_cwd macros expand. Passing all input
574 parameters down to the base git macro, if any are specified, is im‐
575 plicit (i.e. not mentioned below).
576 ----
579 git_cwd_name
583 git_name append="$(git_prefix "$PWD" | git_prefix_to_name_suffix)"
585 Outputs remote URL basename appended with the path from the repository
587 root to the current working directory (after slash to dash substitu‐
588 tion).
589 ----
592 git_cwd_version
596 git_version name="$(git_cwd_name)"
598 Outputs version of a subpackage by name $(git_cwd_name).
600 ----
603 git_cwd_release
607 git_release name="$(git_cwd_name)"
609 Outputs release of a subpackage by name $(git_cwd_name).
611 ----
614 git_cwd_release_branched
618 git_release_branched name="$(git_cwd_name)"
620 Outputs branched release of a subpackage by name $(git_cwd_name).
622 ----
625 git_cwd_changelog
629 git_changelog name="$(git_cwd_name)"
631 Outputs changelog of a subpackage by name $(git_cwd_name).
633 ----
636 git_cwd_vcs
640 git_vcs path="$PWD"
642 Outputs VCS pseudo URL pointing to the current working directory.
644 ----
647 git_cwd_pack
651 git_pack path="$PWD"
653 Packs working directory by using GNU tar (for a dirty repo) or git ar‐
655 chive (for a clean repo).
656 ----
659 git_cwd_archive
663 git_archive path="$PWD"
665 Packs working directory by using git archive.
667 ----
670 git_cwd_setup_macro
674 git_setup_macro path="$PWD"
676 Outputs rpm's %setup macro with dir_name (-n argument of %setup) auto‐
678 matically generated according to the remote URL basename and the cur‐
679 rent working directory path. If you used git_cwd_pack or git_cwd_ar‐
680 chive for packing, use this macro in %prep spec file section for pre‐
681 paring the sources for rpm build.
682
684 These macros operate on the root (top-level) directory of the current
685 git repository. Path to that directory is stored in GIT_ROOT environ‐
686 ment variable. Implementation-wise, these macros are just tiny wrappers
687 over the git base macros with some input values set specifically for
688 repository-wide operation.
689 WARNING:
691 If your local git repository is not properly initialized or if, for
692 example, the .git metadata directory in your local tree has been re‐
693 named or removed, operation of the repo macros can get out of the
694 intended scope. It is therefore recommended to use more specific
695 git_dir_* macros wherever possible, which are always bound to the
696 directory where the input spec file is located. This is especially
697 important for the tarball creating macros (i.e. *_pack and *_archive
698 ones).
699 Below you can see to what the git_repo macros expand. Passing all input
701 parameters down to the base git macro, if any are specified, is im‐
702 plicit (i.e. not mentioned below).
703 ----
706 git_repo_name
710 git_name
712 Outputs remote URL basename with .git suffix stripped. git_repo_name
714 and git_name are direct equivalents.
715 ----
718 git_repo_version
722 git_version name="$(git_repo_name)"
724 Outputs version of a subpackage by name $(git_repo_name).
726 ----
729 git_repo_release
733 git_release name="$(git_repo_name)"
735 Outputs release of a subpackage by name $(git_repo_name).
737 ----
740 git_repo_release_branched
744 git_release_branched name="$(git_repo_name)"
746 Outputs branched release of a subpackage by name $(git_repo_name).
748 ----
751 git_repo_changelog
755 git_changelog name="$(git_repo_name)"
757 Outputs changelog of a subpackage by name $(git_repo_name).
759 ----
762 git_repo_vcs
766 git_vcs path="$GIT_ROOT"
768 Outputs VCS pseudo URL pointing to the repository.
770 ----
773 git_repo_pack
777 git_pack path="$GIT_ROOT"
779 Packs the whole repository (with the standard omissions like git-ig‐
781 nored content or git submodules, see documentation for git_pack regard‐
782 ing this) by using GNU tar (for a dirty repo) or git archive (for a
783 clean repo).
784 ----
787 git_repo_archive
791 git_archive path="$GIT_ROOT"
793 Packs the git repository content by using git archive.
795 ----
798 git_repo_setup_macro
802 git_setup_macro path="$GIT_ROOT"
804 Outputs rpm's %setup macro with dir_name (-n argument of %setup) gener‐
806 ated from basename of the repository remote URL. If you used
807 git_repo_pack or git_repo_archive for packing, use this macro in %prep
808 spec file section for preparing the sources for rpm build.
809 REFERENCE RPKG(MACRO)