Additional annotated templates

# Minimal Go source code packaging template.
#
# This template documents the minimal set of spec declarations, necessary to
# publish Go source code to other packages. The sister “go-1-source-full”
# template documents less common declarations; read it if your needs exceed
# this file.
#
# All the “go-*-” spec templates complement one another without documentation
# overlaps. Try to read them all.
#
# The master Go import path of the project. Take the time to identify it
# accurately, changing it later will be inconvenient:
#  – it may differ from the repository URL;
#  – generally, the correct value will be the one used by the project in its
#    documentation, coding examples, and build assertions;
#  – use the gopkg import path for all code states when a project uses it.
# If upstream confused itself after multiple forks and renamings, you need to
# fix references to past names in the Go source files, unit tests included.
# Perform this fixing in “prep”.
%global goipath  
#
# “gometa” is a thin Go-specific wrapper around “forgemeta”. Therefore, define
# “version”, “tag”, “commit”… before the “gometa” line, as you would with
# “forgemeta”. Only define the rpm variables actually needed by the spec file.
#  – define “forgeurl”, including “https://” prefixing, if the import path
#    does not match the repository URL; otherwise it is not necessary,
%global forgeurl 
#  – move the Version: line before the “gometa” call if you are packaging a
#    release.
Version:         
%global tag      
%global commit   
#
# Like “forgemeta”, “gometa” accepts a “-i” flag to output the rpm variables it
# reads and sets. Most of those can be overriden before or after the “gometa”
# call. If you use “-i” , remove it before committing and pushing to the
# buildsystem.
# See the “forge” spec templates for detailed “forgemeta” documentation.
%gometa

# A space-separated list of shell globs matching the project license files.
%global golicenses      
# A space-separated list of shell globs matching the project documentation files.
# The Go rpm macros will pick up “.md” files by default without this.
%global godocs          

# A multiline description block shared between subpackages
%global common_description %{expand:
}

# The following lines use “go*” variables computed by gometa as default values.
# You can replace them with manual definitions. For example, replace “gourl”
# with the project homepage if it exists separately from the repository URL. Be
# careful to only replace “go*” variables when it adds value to the specfile
# and you understand the consequences. Otherwise you will just add
# maintenance-intensive discrepancies in the distribution.
Name:    %{goname}
# If not set before
Version: 
Release: 1%{?dist}
Summary: 
URL:     %{gourl}
Source:  %{gosource}
%description
%{common_description}

# Generate package declarations for all known kinds of Go subpackages.
# You can replace if with “godevelpkg” to generate Go devel subpackages only.
%gopkg

%prep
# “goprep” unpacks the Go source archives and creates the project “GOPATH” tree
# used in the rest of the spec file. It removes vendored (bundled) code:
#  – use the “-k” flag if you wish to keep this vendored code, and deal with the
#    consequences in the rest of the spec.
#  – use the “-e” flag if you wish to perform extraction yourself, and just use
#    the “GOPATH” creation logic.
%goprep
#
# “goprep” only performs basic vendoring detection. It will miss inventive ways
# to vendor code. Remove manually missed vendor code, after the “goprep” line.
# “goprep” will not fix upstream sources for you. Since all the macro calls that
# follow “goprep” assume clean problem-free sources, you need to correct them
# just after the “goprep” line:
#  – replace calls to deprecated import paths with their correct value
#  – patch code problems
#  – remove dead code (some upstreams deliberately ship broken source code in
#    the hope someone will get around to fix it)
# Remember to send fixes and problem reports upstream.
# When you package an import path, that participates in a dependency loop, you
# need bootstraping to manage the initial builds:
# https://docs.fedoraproject.org/en-US/packaging-guidelines/#bootstrapping
# For Go code, that means your bootstrap section should:
#  – remove unit tests that import other parts of the loop
#  – remove code that imports other parts of the loop
# Sometimes one can resolve dependency loops just by splitting specific
# subdirectories in a separate -devel subpackage. See also the “go-6-multi”
# template.
#

# Anything outputed in this rpm section will be installed in the build
# environment by mock
%generate_buildrequires
# “go_generate_buildrequires” computes the build dependencies of the packaged
# Go code. Right now, it only knows how to compute version-less dependencies.
# If that is not good enough for you you need to filter and rework its output.
%go_generate_buildrequires

%install
# Perform installation steps for all known kinds of Go subpackages
# You can replace if with “godevelinstall” to process Go devel subpackages only
%gopkginstall

%check
# “gocheck” runs all the unit tests found in the project. This is useful to catch
# API breakage early. Unfortunately, the following kinds of unit tests are
# incompatible with a secure build environment:
#  – tests that call a remote server or API over the Internet,
#  – tests that attempt to reconfigure the system,
#  – tests that rely on a specific app running on the system, like a database
#    or syslog server.
# You can disable those tests with the following exclusion flags, that can be
# repeated:
#  – “-d <directory>”     exclude the files contained in <directory>
#                         not recursive (subdirectories are not excluded)
#  – “-t <tree root>”     exclude the files contained in <tree root>
#                         recursive (subdirectories are excluded)
#  – “-r <regexp>”        exclude files matching <regexp>,
# If a test is broken for some other reason, you can disable it
# the same way. However, you should also report the problem upstream.
# Remember to trace in a comment why each check was disabled, with links to
# eventual upstream problem reports.
%gocheck

# Generate file sections for all known kinds of Go subpackages
# You can replace if with “godevelfiles” to process Go devel subpackages only
%gopkgfiles

%changelog

# Complete Go source code packaging template.
#
# This template complements “go-0-source-minimal”, with less usual spec
# declarations.
#
# All the “go-*-” spec templates complement one another without documentation
# overlaps. Try to read them all.
#
%global goipath  
Version:         
%global tag      
%global commit   
#
# A compatibility id that should be used in the package naming. It will change
# the generated “goname” to something derived from
# compat-golang-goipath-gocid-devel.
# “gocids” are used to disambiguate compatibility packages from the package
# tracking the recommended distribution version. Usual values:
#  – the version major (if different),
#  – a shortened commit tag such as
#    %{lua:print(string.sub(rpm.expand("%{?commit}"), 1, 7))}
%global gocid    
%gometa

# rpm variables used to tweak the generated golang-*devel package.
# Most of them won’t be needed by the average Go spec file.
#
# A space-separated list of Go import paths to include. Unless specified
# otherwise the first element in the list will be used to name the subpackage.
# (by default, “goipath”)
%global goipaths        
# A space-separated list of Go import paths to exclude. Usually, subsets of the
# elements in goipaths.
%global goipathsex      
# A compatibility id that should be used in the package naming.
# (by default, “gocid”)
%global godevelcid      
# A value that will replace the computed subpackage name.
# (by default “gorpmname-devel”)
%global godevelname     
# The subpackage summary.
# (by default, “summary”)
%global godevelsummary  
# A container for additional subpackage declarations.
%global godevelheader %{expand:
Requires:  
Obsoletes: 
}
# The subpackage base description.
# (by default, “common_description”)
%global godeveldescription %{expand:
}
%global golicenses      
# A space-separated list of shell globs matching files you wish to exclude from
# license lists.
%global golicensesex    
%global godocs          
# A space-separated list of shell globs matching files you wish to exclude from
# documentation lists. Only works for “godocs”-specified files.
%global godocsex        
# A space separated list of extentions that should be included in the devel
# package in addition to Go default file extensions.
%global goextensions    
# A space-separated list of shell globs matching other files to include in the
# devel package.
%global gosupfiles      
# A space-separated list of shell globs matching other files ou wish to exclude from
# package lists. Only works with “gosupfiles”-specified files.
%global gosupfilesex    
# The filelist name associated with the subpackage. Setting this should never
# be necessary unless the default name clashes with something else.
%global godevelfilelist 

%global common_description %{expand:
}

Name:    %{goname}
# If not set before
Version: 
Release: 1%{?dist}
Summary: 
URL:     %{gourl}
Source:  %{gosource}
%description
%{common_description}

%gopkg

%prep
%goprep

%generate_buildrequires
%go_generate_buildrequires

%install
%gopkginstall

%check
%gocheck

%gopkgfiles

%changelog

# Minimal Go alternative import path packaging template.
#
# Sometimes Go projects keep importing deprecated import path names, or use
# forks with different names. Ideally, all codebases should be fixed to use the
# current canonical import path, but that is not always possible.
#
# This template documents the minimal set of spec declarations, necessary to
# publish alternative Go import paths to other packages. The sister
# “go-3-alternative import-path-full” template documents less common
# declarations; read it if your needs exceed this file.
#
# All the “go-*-” spec templates complement one another without documentation
# overlaps. Try to read them all.
#
# Simulating other import paths prevents the duplicate packaging of the a
# codebase when packagers do not notice an import path has been renamed. It
# keeps spec files that refer to the old name working. Those should still be
# fixed to use the new name as soon as possible.
#
%global goipath  
Version:         
%global tag      
%global commit   
%gometa

%global golicenses      
%global godocs          

# A space-separated list of import paths to simulate. Without this nothing will
# happen.
%global goaltipaths     

%global common_description %{expand:
}

Name:    %{goname}
# If not set before
Version: 
Release: 1%{?dist}
Summary: 
URL:     %{gourl}
Source:  %{gosource}
%description
%{common_description}

# Generate package declarations for all known kinds of Go subpackages. You can
# replace if with separate “goaltpkg” and “godevelpkg” calls.
%gopkg

%prep
%goprep

%generate_buildrequires
%go_generate_buildrequires

%install
# Perform installation steps for all known kinds of Go subpackages. You can
# replace if with separate “goaltinstall” and “godevelinstall” calls.
%gopkginstall

%check
%gocheck

# Generate file sections for all known kinds of Go subpackages. You can replace
# if with separate “goaltfiles” and “godevelfiles” calls.
%gopkgfiles

%changelog

# Complete Go alternative import path packaging template.
#
# This template complements “go-2-alternative import-path-minimal”, with less
# usual spec declarations.
#
# All the “go-*-” spec templates complement one another without documentation
# overlaps. Try to read them all.
#
%global goipath  
%global forgeurl 
Version:         
%global tag      
%global commit   
%global gocid    
%gometa

%global goipaths        
%global goipathsex      
%global godevelcid      
%global godevelname     
%global godevelsummary  
%global godevelheader %{expand:
Requires:  
Obsoletes: 
}
%global golicenses      
%global golicensesex    
%global godocs          
%global godocsex        
%global goextensions    
%global gosupfiles      
%global gosupfilesex    
%global godevelfilelist 

%global goaltipaths     
#
# rpm variables used to tweak the generated compat-golang-*devel packages.
# Most of them won’t be needed by the average Go spec file.
#
# The import path that will be linked to.
# (by default, “goipath”)
%global gocanonipath    
# A compatibility id that should be used in the package naming.
# (by default, “gocid”)
%global goaltcid        
# The subpackage summary;
# (by default, “summary”)
%global goaltsummary    
# A container for additional subpackage declarations.
%global goaltheader      %{expand:
Requires:  
Obsoletes: 
}
# The subpackage base description;
# (by default, “common_description”)
%global goaltdescription %{expand:
}

%global common_description %{expand:
}

Name:    %{goname}
# If not set before
Version: 
Release: 1%{?dist}
Summary: 
URL:     %{gourl}
Source:  %{gosource}
%description
%{common_description}

%gopkg

%prep
%goprep

%generate_buildrequires
%go_generate_buildrequires

%install
%gopkginstall

%check
%gocheck

%gopkgfiles

%changelog

# Minimal Go binary packaging template.
#
# This template documents the minimal set of spec declarations, necessary to
# package Go projects that produce binaries. The sister “go-5-binary-full”
# template documents less common declarations; read it if your needs exceed
# this file.
#
# All the “go-*-” spec templates complement one another without documentation
# overlaps. Try to read them all.
#
# Building Go binaries is less automated than the rest of our Go packaging and
# requires more manual work.
#
%global goipath  
Version:         
%global tag      
%global commit   
%gometa

%global _docdir_fmt     %{name}

%global golicenses      
%global godocs          
%global godevelheader %{expand:
# The devel package will usually benefit from corresponding project binaries.
Requires:  %{name} = %{version}-%{release}
Obsoletes:
}

%global common_description %{expand:
}

# If one of the produced binaries is widely known it should be used to name the
# package instead of “goname”. Separate built binaries in different subpackages
# if needed.
Name:    %{goname}
Version: 
Release: 1%{?dist}
Summary: 
URL:     %{gourl}
Source:  %{gosource}
%description
%{common_description}

%gopkg

%prep
%goprep

%generate_buildrequires
%go_generate_buildrequires

%build
# You need to identify manually the project parts that can be built, and how to
# name the result. Practically, it’s any directory containing a main() Go
# section. Nice projects put those in “cmd” subdirectories named after the
# command that will be built, which is what we will document here, but it is
# not a general rule. Sometimes the whole “goipath” builds as a single binary.
for cmd in cmd/* ; do
  %gobuild -o %{gobuilddir}/bin/$(basename $cmd) %{goipath}/$cmd
done

%install
%gopkginstall
install -m 0755 -vd                     %{buildroot}%{_bindir}
install -m 0755 -vp %{gobuilddir}/bin/* %{buildroot}%{_bindir}/

%check
%gocheck

%files
%license %{golicenses}
%doc     
%{_bindir}/*

%gopkgfiles

%changelog

# Complete Go binary packaging template.
#
# This template complements “go-5-binary-minimal”, with less usual spec
# declarations.
#
# All the “go-*-” spec templates complement one another without documentation
# overlaps. Try to read them all
#
%global goipath  
%global forgeurl 
Version:         
%global tag      
%global commit   
%global gocid    
%gometa

%global _docdir_fmt     %{name}

%global goipaths        
%global goipathsex      
%global godevelcid      
%global godevelname     
%global godevelsummary  
%global godevelheader %{expand:
Requires:  %{name} = %{version}-%{release}
Obsoletes: 
}
%global golicenses      
%global golicensesex    
%global godocs          
%global godocsex        
%global goextensions    
%global gosupfiles      
%global gosupfilesex    
%global godevelfilelist 

%global goaltipaths     
%global gocannonipath   
%global goaltcid        
%global goaltsummary    
%global goaltheader      %{expand:
Requires:  
Obsoletes: 
}
%global goaltdescription %{expand:
}

%global common_description %{expand:
}


Name:    %{goname}
# If not set before
Version: 
Release: 1%{?dist}
Summary: 
URL:     %{gourl}
Source:  %{gosource}
%description
%{common_description}

%gopkg

%prep
%goprep

%generate_buildrequires
%go_generate_buildrequires

%build
for cmd in cmd/* ; do
  %gobuild -o %{gobuilddir}/bin/$(basename $cmd) %{goipath}/$cmd
done

%install
%gopkginstall
install -m 0755 -vd                     %{buildroot}%{_bindir}
install -m 0755 -vp %{gobuilddir}/bin/* %{buildroot}%{_bindir}/

%check
%gocheck

%files
%license %{golicenses}
%doc     
%{_bindir}/*

%gopkgfiles

%changelog

# This template documents advanced Go packaging with multiples of everything.
# Don’t try it before you understand how simpler Go packaging is done.
#
# All the “go-*-” spec templates complement one another without documentation
# overlaps. Try to read them all.
#
# Don’t hesitate to use “rpmspec -P <specfile>” to check the generated code.
#
# You can refer to several upstream archives using the “-a” “gometa” flag and
# blocks of declarations suffixed by a block number, like with “forgemeta”.
# No suffix or zero suffix refers to the main archive. Refer to the forge-multi
# template for more detailed information.
# IT IS A TERRIBLE IDEA TO TRY THIS UNLESS EVERY SOURCE ARCHIVE IS PERFECTLY
# VERSION-LOCKED WITH THE OTHERS. That will produce broken rpm versionning and
# broken upgrade paths. It is always simpler and safer to package separate
# projects with separate spec files.
#
# Main archive
%global goipath0  
%global forgeurl0 
Version:          
%global tag0      
%global commit0   
%global gocid0    
#
# Second archive
%global goipath1  
%global forgeurl1 
%global version1  
%global tag1      
%global commit1   
%global gocid1    
#
# Continue as necessary…
#
# Alternatively, you can use the “-z <number>” “gometa” argument to process a
# specific declaration block only.
%gometa -a

%global _docdir_fmt     %{name}

# Likewise, you can declare several devel subpackages, either one by source
# archive or with any other import path layout.
#
# First golang-*-devel subpackage.
#
# If unset, and no “goipaths<number>” is defined in the spec, fallbacks to
# “goipath<number>”
%global goipaths0        
%global goipathsex0      
%global godevelcid0      
%global godevelname0     
%global godevelsummary0  
%global godevelheader0 %{expand:
Requires:  
Obsoletes: 
}
%global golicenses0      
%global golicensesex0    
%global godocs0          
%global godocsex0        
%global goextensions0    
%global gosupfiles0      
%global gosupfilesex0    
%global godevelfilelist0 
#
# Second golang-*-devel subpackage.
%global goipaths1        
%global goipathsex1      
%global godevelcid1      
%global godevelname1     
%global godevelsummary1  
%global godevelheader1 %{expand:
Requires:  
Obsoletes: 
}
%global golicenses1      
%global golicensesex1    
%global godocs1          
%global godocsex1        
%global goextensions1    
%global gosupfiles1      
%global gosupfilesex1    
%global godevelfilelist1 
#
# Continue as necessary…


# Likewise, you can declare several alternative name sets that will generate
# the corresponding compat-golang-*-devel subpackages
#
# First compat-golang-*-devel subpackage set.
%global goaltipaths0      
# If unset, and no “gocanonipath<number>” is defined in the spec, fallbacks to
# “goipath<number>”
%global gocanonipath0     
%global goaltsummary0     
%global goaltheader0      %{expand:
Requires:  
Obsoletes: 
}
%global goaltdescription0 %{expand:
}
#
# Second compat-golang-*-devel subpackage set.
%global goaltipaths1      
%global gocanonipath1     
%global goaltsummary1     
%global goaltheader1      %{expand:
Requires:  
Obsoletes: 
}
%global goaltdescription1 %{expand:
}
#
# Continue as necessary…

%global common_description %{expand:
}

# Use usual naming rules when generating binaries.
Name:    %{goname}
# If not set before
Version: 
Release: 1%{?dist}
Summary: 
URL:	 %{gourl}
# One for each of the previous goipath blocks
Source0: %{gosource0}
Source1: %{gosource1}
# …
%description
%{common_description}

# “gopkg” will generate all the subpackages package declarations corresponding
# to the elements declared above.
# You can replace “gopkg” with “godevelpkg” and “goaltpkg” calls for finer
# control.
# “godevelpkg” and “goaltpkg” accept the usual selection arguments:
# – “-a”          process everything
# – “-z <number>” process a specific declaration block
# If no flag is specified they only process the zero/nosuffix block.
%gopkg

%prep
# “%goprep” and “go_generate_buildrequires” accept the usual selection arguments:
# – “-a”          process everything
# – “-z <number>” process a specific declaration block
# If no flag is specified they only process the zero/nosuffix block.
%goprep -a

%generate_buildrequires
%go_generate_buildrequires -a

%build
# When your spec processes multiple Go source archives, you need to call
# “goenv” with the correct “-z <number>” argument before invoquing “%gobuild”.
# Otherwise the binaries risk being built with parameters corresponding to
# another source archive.
for cmd in cmd/* ; do
  %gobuild -o %{gobuilddir}/bin/$(basename $cmd) %{goipath}/$cmd
done

%install
# You can replace “gopkginstall” with  “godevelinstall” and “goaltinstall”
# calls for finer control.
# “godevelinstall” and “goaltinstall” accept the usual selection arguments:
# – “-a”          process everything
# – “-z <number>” process a specific declaration block
# If no flag is specified they only process the zero/nosuffix block.
%gopkginstall

install -m 0755 -vd                     %{buildroot}%{_bindir}
install -m 0755 -vp %{gobuilddir}/bin/* %{buildroot}%{_bindir}/

%check
%gocheck

%files
%license 
%doc     
%{_bindir}/*

# You can replace “gopkgfiles” with  “godevelfiles” and  “goaltfiles”
# calls for finer control.
# “godevelfiles” and “goaltfiles” accept the usual selection arguments:
# – “-a”          process everything
# – “-z <number>” process a specific declaration block
# If no flag is specified they only process the zero/nosuffix block.
%gopkgfiles

%changelog

# This template documents old-style semi-manual Go packaging. This packaging
# mode provides the most packager control. However, the result is also more
# difficult to get right and to maintain.
#
# Using this packaging mode is not recommended unless you really need it. If
# you prepare your sources correctly in prep you should not need it.
#
# All the “go-*-” spec templates complement one another without documentation
# overlaps. Try to read them all..
#
%global goipath  
%global forgeurl 
Version:         
%global tag      
%global commit   
%gometa

# Old naming of the same project
%global oldgoipath xxxx
%global oldgoname  %gorpmname %{oldgoipath}

%global common_description %{expand:
}

Name:    %{goname}
# If not set before
Version: 
Release: 1%{?dist}
Summary: 
URL:     %{gourl}
Source:  %{gosource}
%description
%{common_description}

%package -n %{goname}-devel
Summary: %{summary}

# If the package builds some binaries
Requires:  %{name} = %{version}-%{release}

%description -n %{goname}-devel
%{common_description}

This package contains the source code needed for building packages that
reference the following Go import paths:
 –  %{goipath}

# If you’ve defined an alternative go name
%package -n compat-%{oldgoname}-devel
Summary:   %{summary}
Obsoletes: %{oldgoname}-devel < %{version}-%{release}

%description -n compat-%{oldgoname}-devel
%{common_description}

This package provides symbolic links that alias the following Go import paths
to %{goipath}:
 – %{oldgoipath}

Aliasing Go import paths via symbolic links or http redirects is fragile. If
your Go code depends on this package, you should patch it to import directly
%{goipath}.

%prep
%goprep

%generate_buildrequires
%go_generate_buildrequires

%install
# goinstall is our Go source installation workhorse. It accepts a huge and
# bewildering array of arguments. Most of those have good default values,
# changing them is more likely to compound existing spec problems than fix
# anything.
#
# Selection arguments, that can not be repeated:
#  – “-a”                  process everything
#  – “-z <number>”         process a specific declaration block
#  – “-i <go import path>” use the specified import path value
#                          default: %{goipath<number>}
#
# If no “-a”, “-z” or “-i ”flag is specified goinstall will only process the
# zero/nosuffix Go import path.
#
# Miscellaneous settings:
#  – “-b <bindir>”         read binaries already produced in <bindir>
#                          default: %{gobuilddir}/bin
#  – “-s <sourcedir>”      read expanded and prepared Go sources in
#                          <sourcedir>/src
#                          <sourcedir> should be populated in %prep
#                          default: %{gobuilddir}
#  – “-o <filename>”       output installed file list in <filename>
#                          default: %{gofilelist<number>}
#  – “-O <directory>”      output <filename> in <directory>
#  – “-l <ldflags>”        add those flags to LDFLAGS when building unit tests
#  – “-v”                  be verbose
#
# Inclusion arguments, that can be repeated:
#  – “-e <extension>”      include files with the provided extension
#
# Exclusion ar²guments, that can be repeated, relative to the go import path
# root:
#  – “-d <directory>”      exclude the files contained in <directory>
#                          not recursive (subdirectories are not excluded)
#  – “-t <tree root>”      exclude the files contained in <tree root>
#                          recursive (subdirectories are excluded)
#  – “-r <regexp>”         exclude files matching <regexp>,
#
# Optional versionning metadata, that can not be repeated:
#  – “-V <version>”        should only be specified when creating subpackages
#                          with distinct versions. Excellent tool for producing
#                          broken packages.
#                          default: %{version}.%{release}
#  – “-T <tag>”            default: %{tag<number>}
#  – “-C <commit>”         default: %{commit<number>}
#  – “-B <branch>”         default: %{branch<number>}
#
%goinstall
#
# Old name aliasing
install -m 0755 -vd %{buildroot}%{gopath}/src/%(dirname %{oldgoipath})
ln -s %{gopath}/src/%{goipath} %{buildroot}%{gopath}/src/%{oldgoipath}
#
install -m 0755 -vd                     %{buildroot}%{_bindir}
install -m 0755 -vp %{gobuilddir}/bin/* %{buildroot}%{_bindir}/

%check
%gocheck

%files
%license 
%{_bindir}/*

%files -n %{goname}-devel -f %{gofilelist}

%files -n compat-%{oldgoname}-devel
# You need as many of those as necessary to own the levels of directories
# between %{gopath}/src and %{gopath}/src/%{oldgoipath}, that are not already
# owned by the %{goname}-devel subpackage
%dir %{gopath}/src/%(dirname %(dirname %{oldgoipath}))
%dir %{gopath}/src/%(dirname %{oldgoipath})
%{gopath}/src/%{oldgoipath}

%changelog