1RPKG(MACRO)                                                        RPKG(MACRO)
2
3
4

NAME

6       Rpkg macro reference
7
8       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

EXAMPLES

20       Example spec file with the rpkg macros used:
21
22          Name:       {{{ git_dir_name }}}
23          Version:    {{{ git_dir_version }}}
24          Release:    1%{?dist}
25
26          Summary:    This is a test package.
27          VCS:        {{{ git_dir_vcs }}}
28
29          License:    GPLv2+
30          URL:        https://someurl.org
31
32          Source0:    {{{ git_dir_pack }}}
33
34          %description
35          This is a test package.
36
37          %prep
38          {{{ git_dir_setup_macro }}}
39
40          %changelog
41          {{{ git_dir_changelog }}}
42
43       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
47       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

BASE GIT MACROS

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
57       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
67       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
73       E.g.
74          git_version [name="${OUTPUT[git_name]}"] [lead=0] [follow=]
75
76       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
83       "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
87
88                                        ----
89
90
91
92          git_name [name=] [prepend=] [append=]
93
94       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
98          Optional arguments:
99
100                 name   the base name to be output
101
102                 prepend
103                        string to be prepended to the base name
104
105                 append string to be appended to the base name
106
107
108                                        ----
109
110
111
112          git_version [name="${OUTPUT[git_name]}"] [lead=0] [follow=]
113
114       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
124       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
129       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
133       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
138       follow is a minor version substring. It can contain only a single  com‐
139       ponent (i.e. it cannot contain any dots).
140
141       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
145       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
149       commit_count is a number of commits from the latest tag to the  current
150       commit for the given subpackage.
151
152       current_commit_short_hash is a short (8-chars long) hash of the current
153       commit.
154
155       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
159       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
164          Optional arguments:
165
166                 name   name of a subpackage
167
168                 lead   major version substring, dynamically derived if set to
169                        empty
170
171                 follow minor  version  substring,  dynamically derived if not
172                        specified
173
174          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
178                 If   follow   is   specified   by   user  explicitly,  output
179                 ${lead}.${follow}.
180
181                 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
188                 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
192       ** "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
200
201                                        ----
202
203
204
205          git_release [name="${OUTPUT[git_name]}"] [lead=] [follow=]
206
207       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
211       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
216       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
223       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
227          Optional arguments:
228
229                 name   name of a subpackage
230
231                 lead   major version substring, dynamically  derived  if  not
232                        specified
233
234                 follow minor  version  substring,  dynamically derived if not
235                        specified
236
237          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
244                 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
248
249                                        ----
250
251
252
253          git_release_branched
254
255       Uses the current branch name as  lead  parameter  for  git_release.  In
256       other words, equivalent of:
257
258          git_release lead="$GIT_BRANCH"
259
260       NOTE:  the  output  value  will  be cached under git_release, not under
261       git_release_branched.
262
263
264                                        ----
265
266
267
268          git_changelog [name="${OUTPUT[git_name]}"] [since_tag=] [until_tag=] [header_locale=POSIX] [header_date_format="%a %b %d %Y"] [body_wrap=80]
269
270       Outputs rpm spec changelog as generated from tag messages for the  sub‐
271       package given by name.
272
273          Optional arguments:
274
275                 name   name of the subpackage to generate the changelog for
276
277                 since_tag
278                        start the changelog records with this tag
279
280                 until_tag
281                        end the changelog records with this tag
282
283                 header_locale
284                        locale  to be used when changelog record date is being
285                        generated
286
287                 header_date_format
288                        date format to be used in the changelog record headers
289
290                 body_wrap
291                        maximum allowed line length for changelog body
292
293       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
296
297                                        ----
298
299
300
301          git_vcs path=
302
303       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
308       Example output:
309          git+https://pagure.io/test-project.git#dadef2a8b9554e94797a7336261192e02d5d9351:sub‐
310          dir
311
312          Required arguments:
313
314                 path   path to a subtree to generate the URL for
315
316
317                                        ----
318
319
320
321          git_pack path= [dir_name=] [source_name=]
322
323       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
332       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
343          Required arguments:
344
345                 path   path to a specific subdirectory to be packed
346
347          Optional arguments:
348
349                 dir_name
350                        top-level directory name in the created tarball
351
352                 source_name
353                        filename of the created source tarball
354
355          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
360                 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
364
365                                        ----
366
367
368
369          git_archive path= [dir_name=] [source_name=]
370
371       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
377          Required arguments:
378
379                 path   path to a specific subdirectory to be packed
380
381          Optional arguments:
382
383                 dir_name
384                        top-level directory name in the created tarball
385
386                 source_name
387                        filename of the created source tarball
388
389          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
394                 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
398
399                                        ----
400
401
402
403          git_setup_macro [dir_name=] [path=] [source_indices=0]
404
405       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
411       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
415          Optional arguments:
416
417                 dir_name
418                        name of the top-level directory in the source-tarball
419
420                 path   path from which dir_name is derived if it is not spec‐
421                        ified
422
423                 source_indices
424                        Source numbers separated  by  comma  to  generate  the
425                        %setup macro for, by default 0
426

GIT_DIR MACROS

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
435       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
439       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
445       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
450       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
454       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
458
459                                        ----
460
461
462
463          git_dir_name
464
465              git_name append="$(git_prefix "$INPUT_DIR_PATH" | git_prefix_to_name_suffix)"
466
467       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
470
471                                        ----
472
473
474
475          git_dir_version
476
477              git_version name="$(git_dir_name)"
478
479       Outputs version of a subpackage by name $(git_dir_name).
480
481
482                                        ----
483
484
485
486          git_dir_release
487
488              git_release name="$(git_dir_name)"
489
490       Outputs release of a subpackage by name $(git_dir_name).
491
492
493                                        ----
494
495
496
497          git_dir_release_branched
498
499              git_release_branched name="$(git_dir_name)"
500
501       Outputs branched release of a subpackage by name $(git_dir_name).
502
503
504                                        ----
505
506
507
508          git_dir_changelog
509
510              git_changelog name="$(git_dir_name)"
511
512       Outputs changelog of a subpackage by name $(git_dir_name).
513
514
515                                        ----
516
517
518
519          git_dir_vcs
520
521              git_vcs path="$INPUT_DIR_PATH"
522
523       Outputs VCS pseudo URL pointing to the spec file's subdirectory.
524
525
526                                        ----
527
528
529
530          git_dir_pack
531
532              git_pack path="$INPUT_DIR_PATH"
533
534       Packs spec file's subdirectory by using GNU tar (for a dirty  repo)  or
535       git archive (for a clean repo).
536
537
538                                        ----
539
540
541
542          git_dir_archive
543
544              git_archive path="$INPUT_DIR_PATH"
545
546       Packs spec file's subdirectory by using git archive.
547
548
549                                        ----
550
551
552
553          git_dir_setup_macro
554
555              git_setup_macro path="$INPUT_DIR_PATH"
556
557       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

GIT_CWD MACROS

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
570       NOTE:  With  rpkg  utility,  you can influence the working dir from the
571       command line by explicitly specifying its --path argument.
572
573       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
577
578                                        ----
579
580
581
582          git_cwd_name
583
584              git_name append="$(git_prefix "$PWD" | git_prefix_to_name_suffix)"
585
586       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
590
591                                        ----
592
593
594
595          git_cwd_version
596
597              git_version name="$(git_cwd_name)"
598
599       Outputs version of a subpackage by name $(git_cwd_name).
600
601
602                                        ----
603
604
605
606          git_cwd_release
607
608              git_release name="$(git_cwd_name)"
609
610       Outputs release of a subpackage by name $(git_cwd_name).
611
612
613                                        ----
614
615
616
617          git_cwd_release_branched
618
619              git_release_branched name="$(git_cwd_name)"
620
621       Outputs branched release of a subpackage by name $(git_cwd_name).
622
623
624                                        ----
625
626
627
628          git_cwd_changelog
629
630              git_changelog name="$(git_cwd_name)"
631
632       Outputs changelog of a subpackage by name $(git_cwd_name).
633
634
635                                        ----
636
637
638
639          git_cwd_vcs
640
641              git_vcs path="$PWD"
642
643       Outputs VCS pseudo URL pointing to the current working directory.
644
645
646                                        ----
647
648
649
650          git_cwd_pack
651
652              git_pack path="$PWD"
653
654       Packs working directory by using GNU tar (for a dirty repo) or git  ar‐
655       chive (for a clean repo).
656
657
658                                        ----
659
660
661
662          git_cwd_archive
663
664              git_archive path="$PWD"
665
666       Packs working directory by using git archive.
667
668
669                                        ----
670
671
672
673          git_cwd_setup_macro
674
675              git_setup_macro path="$PWD"
676
677       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

GIT_REPO MACROS

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
690       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
700       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
704
705                                        ----
706
707
708
709          git_repo_name
710
711              git_name
712
713       Outputs remote URL basename with .git  suffix  stripped.  git_repo_name
714       and git_name are direct equivalents.
715
716
717                                        ----
718
719
720
721          git_repo_version
722
723              git_version name="$(git_repo_name)"
724
725       Outputs version of a subpackage by name $(git_repo_name).
726
727
728                                        ----
729
730
731
732          git_repo_release
733
734              git_release name="$(git_repo_name)"
735
736       Outputs release of a subpackage by name $(git_repo_name).
737
738
739                                        ----
740
741
742
743          git_repo_release_branched
744
745              git_release_branched name="$(git_repo_name)"
746
747       Outputs branched release of a subpackage by name $(git_repo_name).
748
749
750                                        ----
751
752
753
754          git_repo_changelog
755
756              git_changelog name="$(git_repo_name)"
757
758       Outputs changelog of a subpackage by name $(git_repo_name).
759
760
761                                        ----
762
763
764
765          git_repo_vcs
766
767              git_vcs path="$GIT_ROOT"
768
769       Outputs VCS pseudo URL pointing to the repository.
770
771
772                                        ----
773
774
775
776          git_repo_pack
777
778              git_pack path="$GIT_ROOT"
779
780       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
785
786                                        ----
787
788
789
790          git_repo_archive
791
792              git_archive path="$GIT_ROOT"
793
794       Packs the git repository content by using git archive.
795
796
797                                        ----
798
799
800
801          git_repo_setup_macro
802
803              git_setup_macro path="$GIT_ROOT"
804
805       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
810
811
812
813                                   REFERENCE                       RPKG(MACRO)
Impressum