From bdfffd216867e6eed28db6f630e2d698aca1268a Mon Sep 17 00:00:00 2001 From: Robert-André Mauchin Date: Jun 18 2019 23:21:14 +0000 Subject: Implement Golang Packaging Guidelines Signed-off-by: Robert-André Mauchin Fix various small typos. Golang: Fix a broken link. Signed-off-by: Elliott Sales de Andrade Signed-off-by: Robert-André Mauchin Adressing Igor Gnatenko's comments - Removed auto BR section - Removed Security section - More semantic breaks - Use xref for cross-page links - Added code blocks where needed - Added a mention of go2rpm Signed-off-by: Robert-André Mauchin --- diff --git a/guidelines/modules/ROOT/examples/golang/golang-cloud-google-go.spec b/guidelines/modules/ROOT/examples/golang/golang-cloud-google-go.spec new file mode 100644 index 0000000..c5bfafa --- /dev/null +++ b/guidelines/modules/ROOT/examples/golang/golang-cloud-google-go.spec @@ -0,0 +1,187 @@ +# Generated by go2rpm +%bcond_without check +%bcond_without bootstrap + +# https://github.com/GoogleCloudPlatform/google-cloud-go +%global goipath cloud.google.com/go +%global forgeurl https://github.com/GoogleCloudPlatform/google-cloud-go +Version: 0.37.4 + +%gometa + +%if %{without bootstrap} +%global goipaths0 cloud.google.com/go +%global goipathsex0 cloud.google.com/go/compute +%endif + +%global goipaths1 cloud.google.com/go/compute + +%global common_description %{expand: +Go packages for Google Cloud Platform services.} + +%global golicenses LICENSE +%global godocs AUTHORS CODE_OF_CONDUCT.md CONTRIBUTING.md CONTRIBUTORS RELEASING.md old-news.md CHANGES.md README.md + +Name: %{goname} +Release: 1%{?dist} +Summary: Google Cloud client libraries for Go + +# Upstream license specification: Apache-2.0 +License: ASL 2.0 +URL: %{gourl} +Source0: %{gosource} + +%if %{without bootstrap} +BuildRequires: golang(github.com/golang/mock/gomock) +BuildRequires: golang(github.com/golang/protobuf/proto) +BuildRequires: golang(github.com/golang/protobuf/ptypes) +BuildRequires: golang(github.com/golang/protobuf/ptypes/any) +BuildRequires: golang(github.com/golang/protobuf/ptypes/duration) +BuildRequires: golang(github.com/golang/protobuf/ptypes/empty) +BuildRequires: golang(github.com/golang/protobuf/ptypes/struct) +BuildRequires: golang(github.com/golang/protobuf/ptypes/timestamp) +BuildRequires: golang(github.com/golang/protobuf/ptypes/wrappers) +BuildRequires: golang(github.com/google/btree) +BuildRequires: golang(github.com/google/go-cmp/cmp) +BuildRequires: golang(github.com/google/martian) +BuildRequires: golang(github.com/google/martian/fifo) +BuildRequires: golang(github.com/google/martian/httpspec) +BuildRequires: golang(github.com/google/martian/martianhttp) +BuildRequires: golang(github.com/google/martian/martianlog) +BuildRequires: golang(github.com/google/martian/mitm) +BuildRequires: golang(github.com/google/pprof/profile) +BuildRequires: golang(github.com/googleapis/gax-go/v2) +BuildRequires: golang(go.opencensus.io/plugin/ocgrpc) +BuildRequires: golang(go.opencensus.io/stats) +BuildRequires: golang(go.opencensus.io/stats/view) +BuildRequires: golang(go.opencensus.io/tag) +BuildRequires: golang(go.opencensus.io/trace) +BuildRequires: golang(golang.org/x/oauth2) +BuildRequires: golang(golang.org/x/oauth2/google) +BuildRequires: golang(golang.org/x/oauth2/jwt) +BuildRequires: golang(golang.org/x/sync/errgroup) +BuildRequires: golang(golang.org/x/sync/semaphore) +BuildRequires: golang(golang.org/x/text/language) +BuildRequires: golang(golang.org/x/time/rate) +BuildRequires: golang(google.golang.org/api/bigquery/v2) +BuildRequires: golang(google.golang.org/api/clouddebugger/v2) +BuildRequires: golang(google.golang.org/api/cloudresourcemanager/v1) +BuildRequires: golang(google.golang.org/api/cloudtrace/v1) +BuildRequires: golang(google.golang.org/api/compute/v1) +BuildRequires: golang(google.golang.org/api/container/v1) +BuildRequires: golang(google.golang.org/api/gensupport) +BuildRequires: golang(google.golang.org/api/googleapi) +BuildRequires: golang(google.golang.org/api/iterator) +BuildRequires: golang(google.golang.org/api/option) +BuildRequires: golang(google.golang.org/api/storage/v1) +BuildRequires: golang(google.golang.org/api/support/bundler) +BuildRequires: golang(google.golang.org/api/transport) +BuildRequires: golang(google.golang.org/api/transport/grpc) +BuildRequires: golang(google.golang.org/api/transport/http) +BuildRequires: golang(google.golang.org/genproto/googleapis/api/expr/v1alpha1) +BuildRequires: golang(google.golang.org/genproto/googleapis/api/label) +BuildRequires: golang(google.golang.org/genproto/googleapis/api/metric) +BuildRequires: golang(google.golang.org/genproto/googleapis/api/monitoredres) +BuildRequires: golang(google.golang.org/genproto/googleapis/appengine/logging/v1) +BuildRequires: golang(google.golang.org/genproto/googleapis/bigtable/admin/v2) +BuildRequires: golang(google.golang.org/genproto/googleapis/bigtable/v2) +BuildRequires: golang(google.golang.org/genproto/googleapis/cloud/asset/v1) +BuildRequires: golang(google.golang.org/genproto/googleapis/cloud/asset/v1beta1) +BuildRequires: golang(google.golang.org/genproto/googleapis/cloud/audit) +BuildRequires: golang(google.golang.org/genproto/googleapis/cloud/bigquery/datatransfer/v1) +BuildRequires: golang(google.golang.org/genproto/googleapis/cloud/bigquery/storage/v1beta1) +BuildRequires: golang(google.golang.org/genproto/googleapis/cloud/dataproc/v1) +BuildRequires: golang(google.golang.org/genproto/googleapis/cloud/dataproc/v1beta2) +BuildRequires: golang(google.golang.org/genproto/googleapis/cloud/dialogflow/v2) +BuildRequires: golang(google.golang.org/genproto/googleapis/cloud/iot/v1) +BuildRequires: golang(google.golang.org/genproto/googleapis/cloud/irm/v1alpha2) +BuildRequires: golang(google.golang.org/genproto/googleapis/cloud/kms/v1) +BuildRequires: golang(google.golang.org/genproto/googleapis/cloud/language/v1) +BuildRequires: golang(google.golang.org/genproto/googleapis/cloud/language/v1beta2) +BuildRequires: golang(google.golang.org/genproto/googleapis/cloud/oslogin/common) +BuildRequires: golang(google.golang.org/genproto/googleapis/cloud/oslogin/v1) +BuildRequires: golang(google.golang.org/genproto/googleapis/cloud/oslogin/v1beta) +BuildRequires: golang(google.golang.org/genproto/googleapis/cloud/redis/v1) +BuildRequires: golang(google.golang.org/genproto/googleapis/cloud/redis/v1beta1) +BuildRequires: golang(google.golang.org/genproto/googleapis/cloud/scheduler/v1) +BuildRequires: golang(google.golang.org/genproto/googleapis/cloud/scheduler/v1beta1) +BuildRequires: golang(google.golang.org/genproto/googleapis/cloud/securitycenter/v1) +BuildRequires: golang(google.golang.org/genproto/googleapis/cloud/securitycenter/v1beta1) +BuildRequires: golang(google.golang.org/genproto/googleapis/cloud/speech/v1) +BuildRequires: golang(google.golang.org/genproto/googleapis/cloud/speech/v1p1beta1) +BuildRequires: golang(google.golang.org/genproto/googleapis/cloud/talent/v4beta1) +BuildRequires: golang(google.golang.org/genproto/googleapis/cloud/tasks/v2) +BuildRequires: golang(google.golang.org/genproto/googleapis/cloud/tasks/v2beta2) +BuildRequires: golang(google.golang.org/genproto/googleapis/cloud/tasks/v2beta3) +BuildRequires: golang(google.golang.org/genproto/googleapis/cloud/texttospeech/v1) +BuildRequires: golang(google.golang.org/genproto/googleapis/cloud/videointelligence/v1) +BuildRequires: golang(google.golang.org/genproto/googleapis/cloud/videointelligence/v1beta1) +BuildRequires: golang(google.golang.org/genproto/googleapis/cloud/videointelligence/v1beta2) +BuildRequires: golang(google.golang.org/genproto/googleapis/cloud/vision/v1) +BuildRequires: golang(google.golang.org/genproto/googleapis/cloud/vision/v1p1beta1) +BuildRequires: golang(google.golang.org/genproto/googleapis/cloud/webrisk/v1beta1) +BuildRequires: golang(google.golang.org/genproto/googleapis/container/v1) +BuildRequires: golang(google.golang.org/genproto/googleapis/datastore/v1) +BuildRequires: golang(google.golang.org/genproto/googleapis/devtools/clouddebugger/v2) +BuildRequires: golang(google.golang.org/genproto/googleapis/devtools/clouderrorreporting/v1beta1) +BuildRequires: golang(google.golang.org/genproto/googleapis/devtools/cloudprofiler/v2) +BuildRequires: golang(google.golang.org/genproto/googleapis/devtools/cloudtrace/v1) +BuildRequires: golang(google.golang.org/genproto/googleapis/devtools/cloudtrace/v2) +BuildRequires: golang(google.golang.org/genproto/googleapis/devtools/containeranalysis/v1beta1) +BuildRequires: golang(google.golang.org/genproto/googleapis/devtools/containeranalysis/v1beta1/grafeas) +BuildRequires: golang(google.golang.org/genproto/googleapis/firestore/v1) +BuildRequires: golang(google.golang.org/genproto/googleapis/iam/admin/v1) +BuildRequires: golang(google.golang.org/genproto/googleapis/iam/credentials/v1) +BuildRequires: golang(google.golang.org/genproto/googleapis/iam/v1) +BuildRequires: golang(google.golang.org/genproto/googleapis/logging/type) +BuildRequires: golang(google.golang.org/genproto/googleapis/logging/v2) +BuildRequires: golang(google.golang.org/genproto/googleapis/longrunning) +BuildRequires: golang(google.golang.org/genproto/googleapis/monitoring/v3) +BuildRequires: golang(google.golang.org/genproto/googleapis/privacy/dlp/v2) +BuildRequires: golang(google.golang.org/genproto/googleapis/pubsub/v1) +BuildRequires: golang(google.golang.org/genproto/googleapis/rpc/code) +BuildRequires: golang(google.golang.org/genproto/googleapis/rpc/errdetails) +BuildRequires: golang(google.golang.org/genproto/googleapis/rpc/status) +BuildRequires: golang(google.golang.org/genproto/googleapis/spanner/admin/database/v1) +BuildRequires: golang(google.golang.org/genproto/googleapis/spanner/admin/instance/v1) +BuildRequires: golang(google.golang.org/genproto/googleapis/spanner/v1) +BuildRequires: golang(google.golang.org/genproto/googleapis/type/latlng) +BuildRequires: golang(google.golang.org/genproto/protobuf/field_mask) +BuildRequires: golang(google.golang.org/grpc) +BuildRequires: golang(google.golang.org/grpc/codes) +BuildRequires: golang(google.golang.org/grpc/credentials) +BuildRequires: golang(google.golang.org/grpc/keepalive) +BuildRequires: golang(google.golang.org/grpc/metadata) +BuildRequires: golang(google.golang.org/grpc/status) + +%if %{with check} +# Tests +BuildRequires: golang(github.com/google/go-cmp/cmp/cmpopts) +BuildRequires: golang(google.golang.org/api/iterator/testing) +BuildRequires: golang(google.golang.org/api/logging/v2) +%endif +%endif + +%description +%{common_description} + +%gopkg + +%prep +%goprep + +%install +%gopkginstall + +%if %{without bootstrap} +%if %{with check} +%check +%gocheck +%endif +%endif + +%gopkgfiles + +%changelog +* Tue Apr 23 09:48:52 CEST 2019 Robert-André Mauchin - 0.37.4-1 +- Release 0.37.4 diff --git a/guidelines/modules/ROOT/examples/golang/golang-github-sirupsen-logrus.spec b/guidelines/modules/ROOT/examples/golang/golang-github-sirupsen-logrus.spec new file mode 100644 index 0000000..8b3f861 --- /dev/null +++ b/guidelines/modules/ROOT/examples/golang/golang-github-sirupsen-logrus.spec @@ -0,0 +1,45 @@ +# https://github.com/sirupsen/logrus +%global goipath github.com/sirupsen/logrus +Version: 1.4.0 + +%gometa + +%global goaltipaths github.com/Sirupsen/logrus + +%global common_description %{expand: +Logrus is a structured logger for Go (golang), completely API compatible with +the standard library logger.} + +%global golicenses LICENSE +%global godocs *.md + +Name: %{goname} +Release: 1%{?dist} +Summary: Structured logger for Go +License: MIT +URL: %{gourl} +Source0: %{gosource} + +BuildRequires: golang(golang.org/x/crypto/ssh/terminal) +BuildRequires: golang(github.com/stretchr/testify/assert) + +%description +%{common_description} + +%gopkg + +%prep +%goprep + +%install +%gopkginstall + +%check +%gocheck + +%gopkgfiles + + +%changelog +* Wed Oct 31 2018 Robert-André Mauchin - 1.4.0-1 +- First package for Fedora diff --git a/guidelines/modules/ROOT/examples/golang/golang-github-stretchr-testify.spec b/guidelines/modules/ROOT/examples/golang/golang-github-stretchr-testify.spec new file mode 100644 index 0000000..4256699 --- /dev/null +++ b/guidelines/modules/ROOT/examples/golang/golang-github-stretchr-testify.spec @@ -0,0 +1,49 @@ +# https://github.com/stretchr/testify +%global goipath github.com/stretchr/testify +Version: 1.2.2 + +%gometa + +%global common_description %{expand: +Golang set of packages that provide many tools for testifying +that your code will behave as you intend. + +Features include: + + - Easy assertions + - Mocking + - Testing suite interfaces and functions} + +%global golicenses LICENSE + +Name: %{goname} +Release: 1%{?dist} +Summary: Tools for testifying that your code will behave as you intend +License: BSD +URL: %{gourl} +Source0: %{gosource} + +BuildRequires: golang(github.com/davecgh/go-spew/spew) +BuildRequires: golang(github.com/pmezard/go-difflib/difflib) +BuildRequires: golang(github.com/stretchr/objx) + +%description +%{common_description} + +%gopkg + +%prep +%goprep + +%install +%gopkginstall + +%check +%gochecks + +%gopkgfiles + + +%changelog +* Thu Mar 21 22:20:22 CET 2019 Robert-André Mauchin - 1.2.2-1 +- First package for Fedora diff --git a/guidelines/modules/ROOT/examples/golang/golang-gopkg-square-jose-2.spec b/guidelines/modules/ROOT/examples/golang/golang-gopkg-square-jose-2.spec new file mode 100644 index 0000000..f3cc8e5 --- /dev/null +++ b/guidelines/modules/ROOT/examples/golang/golang-gopkg-square-jose-2.spec @@ -0,0 +1,67 @@ +# https://github.com/square/go-jose +%global goipath gopkg.in/square/go-jose.v2 +%global forgeurl https://github.com/square/go-jose +Version: 2.1.9 + +%gometa + +%global common_description %{expand: +Package jose aims to provide an implementation of the Javascript Object +Signing and Encryption set of standards. This includes support for JSON Web +Encryption, JSON Web Signature, and JSON Web Token standards.} + +%global golicenses LICENSE +%global godocs *.md + +%global godevelheader %{expand: +# The devel package will usually benefit from corresponding project binaries. +Requires: %{name} = %{version}-%{release} +} + +Name: %{goname} +Release: 1%{?dist} +Summary: An implementation of JOSE standards (JWE, JWS, JWT) in Go +# Detected licences +# - *No copyright* Apache License (v2.0) at 'LICENSE' +# json/ is BSD +License: ASL 2.0 and BSD +URL: %{gourl} +Source0: %{gosource} + +BuildRequires: golang(golang.org/x/crypto/ed25519) +BuildRequires: golang(golang.org/x/crypto/pbkdf2) +BuildRequires: golang(github.com/stretchr/testify/assert) +BuildRequires: golang(gopkg.in/alecthomas/kingpin.v2) + +%description +%{common_description} + +%gopkg + +%prep +%goprep + +%build +for cmd in jose-util jwk-keygen; 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 %{godocs} +%{_bindir}/* + +%gopkgfiles + +%changelog +* Thu Mar 21 21:59:10 CET 2019 Robert-André Mauchin - 2.1.9-1 +- First package for Fedora + diff --git a/guidelines/modules/ROOT/examples/golang/spectemplate-go-0-source-minimal.spec b/guidelines/modules/ROOT/examples/golang/spectemplate-go-0-source-minimal.spec new file mode 100644 index 0000000..391f421 --- /dev/null +++ b/guidelines/modules/ROOT/examples/golang/spectemplate-go-0-source-minimal.spec @@ -0,0 +1,140 @@ +# 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} +Source0: %{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 ” exclude the files contained in +# not recursive (subdirectories are not excluded) +# – “-t ” exclude the files contained in +# recursive (subdirectories are excluded) +# – “-r ” exclude files matching , +# 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 + diff --git a/guidelines/modules/ROOT/examples/golang/spectemplate-go-1-source-full.spec b/guidelines/modules/ROOT/examples/golang/spectemplate-go-1-source-full.spec new file mode 100644 index 0000000..2e21f48 --- /dev/null +++ b/guidelines/modules/ROOT/examples/golang/spectemplate-go-1-source-full.spec @@ -0,0 +1,104 @@ +# 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} +Source0: %{gosource} +%description +%{common_description} + +%gopkg + +%prep +%goprep + +%generate_buildrequires +%go_generate_buildrequires + +%install +%gopkginstall + +%check +%gocheck + +%gopkgfiles + +%changelog + diff --git a/guidelines/modules/ROOT/examples/golang/spectemplate-go-2-alternative-import-path-minimal.spec b/guidelines/modules/ROOT/examples/golang/spectemplate-go-2-alternative-import-path-minimal.spec new file mode 100644 index 0000000..f5f72d0 --- /dev/null +++ b/guidelines/modules/ROOT/examples/golang/spectemplate-go-2-alternative-import-path-minimal.spec @@ -0,0 +1,69 @@ +# 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} +Source0: %{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 + diff --git a/guidelines/modules/ROOT/examples/golang/spectemplate-go-3-alternative-import-path-full.spec b/guidelines/modules/ROOT/examples/golang/spectemplate-go-3-alternative-import-path-full.spec new file mode 100644 index 0000000..a0e308c --- /dev/null +++ b/guidelines/modules/ROOT/examples/golang/spectemplate-go-3-alternative-import-path-full.spec @@ -0,0 +1,89 @@ +# 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} +Source0: %{gosource} +%description +%{common_description} + +%gopkg + +%prep +%goprep + +%generate_buildrequires +%go_generate_buildrequires + +%install +%gopkginstall + +%check +%gocheck + +%gopkgfiles + +%changelog + diff --git a/guidelines/modules/ROOT/examples/golang/spectemplate-go-4-binary-minimal.spec b/guidelines/modules/ROOT/examples/golang/spectemplate-go-4-binary-minimal.spec new file mode 100644 index 0000000..19e1e8f --- /dev/null +++ b/guidelines/modules/ROOT/examples/golang/spectemplate-go-4-binary-minimal.spec @@ -0,0 +1,79 @@ +# 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} +Source0: %{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 + diff --git a/guidelines/modules/ROOT/examples/golang/spectemplate-go-5-binary-full.spec b/guidelines/modules/ROOT/examples/golang/spectemplate-go-5-binary-full.spec new file mode 100644 index 0000000..2c227a7 --- /dev/null +++ b/guidelines/modules/ROOT/examples/golang/spectemplate-go-5-binary-full.spec @@ -0,0 +1,91 @@ +# 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} +Source0: %{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 + diff --git a/guidelines/modules/ROOT/examples/golang/spectemplate-go-6-multi.spec b/guidelines/modules/ROOT/examples/golang/spectemplate-go-6-multi.spec new file mode 100644 index 0000000..198eb63 --- /dev/null +++ b/guidelines/modules/ROOT/examples/golang/spectemplate-go-6-multi.spec @@ -0,0 +1,193 @@ +# 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 ” 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 ” “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” is defined in the spec, fallbacks to +# “goipath” +%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” is defined in the spec, fallbacks to +# “goipath” +%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 ” 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 ” 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 ” 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 ” 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 ” process a specific declaration block +# If no flag is specified they only process the zero/nosuffix block. +%gopkgfiles + +%changelog + diff --git a/guidelines/modules/ROOT/examples/golang/spectemplate-go-7-manual.spec b/guidelines/modules/ROOT/examples/golang/spectemplate-go-7-manual.spec new file mode 100644 index 0000000..f11fe12 --- /dev/null +++ b/guidelines/modules/ROOT/examples/golang/spectemplate-go-7-manual.spec @@ -0,0 +1,145 @@ +# 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} +Source0: %{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 ” process a specific declaration block +# – “-i ” use the specified import path value +# default: %{goipath} +# +# If no “-a”, “-z” or “-i ”flag is specified goinstall will only process the +# zero/nosuffix Go import path. +# +# Miscellaneous settings: +# – “-b ” read binaries already produced in +# default: %{gobuilddir}/bin +# – “-s ” read expanded and prepared Go sources in +# /src +# should be populated in %prep +# default: %{gobuilddir} +# – “-o ” output installed file list in +# default: %{gofilelist} +# – “-O ” output in +# – “-l ” add those flags to LDFLAGS when building unit tests +# – “-v” be verbose +# +# Inclusion arguments, that can be repeated: +# – “-e ” include files with the provided extension +# +# Exclusion ar²guments, that can be repeated, relative to the go import path +# root: +# – “-d ” exclude the files contained in +# not recursive (subdirectories are not excluded) +# – “-t ” exclude the files contained in +# recursive (subdirectories are excluded) +# – “-r ” exclude files matching , +# +# Optional versionning metadata, that can not be repeated: +# – “-V ” should only be specified when creating subpackages +# with distinct versions. Excellent tool for producing +# broken packages. +# default: %{version}.%{release} +# – “-T ” default: %{tag} +# – “-C ” default: %{commit} +# – “-B ” default: %{branch} +# +%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 + diff --git a/guidelines/modules/ROOT/nav.adoc b/guidelines/modules/ROOT/nav.adoc index 2274819..99b98dc 100644 --- a/guidelines/modules/ROOT/nav.adoc +++ b/guidelines/modules/ROOT/nav.adoc @@ -39,6 +39,9 @@ ** xref:C_and_C++.adoc[C and {cpp}] ** xref:D.adoc[D] ** xref:Fortran.adoc[Fortran] +** xref:Golang.adoc[Golang] +*** xref:Golang_advanced.adoc[Advanced uses cases] +*** xref:Golang_templates.adoc[Additional annotated templates] ** xref:Haskell.adoc[Haskell] ** xref:Java.adoc[Java] *** xref:java-packaging-howto:ROOT:index.adoc[Java Packaging HOWTO] diff --git a/guidelines/modules/ROOT/pages/Golang.adoc b/guidelines/modules/ROOT/pages/Golang.adoc new file mode 100644 index 0000000..df37482 --- /dev/null +++ b/guidelines/modules/ROOT/pages/Golang.adoc @@ -0,0 +1,725 @@ += Golang Packaging Guidelines +:last-reviewed: 2019-06-19 +:toc: + +This document details best practices for packaging Golang packages. Most of it +is automated by an extensive use of macros. + +https://pagure.io/GoSIG/[go2rpm] is tool that automates many of these steps. +It is advisable to try `+go2rpm import_path+` first +before attempting to write a SPEC by hand. + +== Import Path + +In Golang, packages are referenced by full URLs. Since this URL is +referenced in several places throughout the rpmspec, set the +base import path as a global define at the top of the spec file + +[source,RPMSpec] +---- +%global goipath github.com/kr/pretty +---- + +All macros, including package name, source URL, will be computed from this +value. + +[NOTE] +==== +*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 will need +to fix references to past names in the Go source files, unit tests included. +Perform this fixing in `+%prep+`. +==== + +== Naming + +=== Source packages (src.rpm) + +* Golang source packages MUST be named after their main import path. +This +process is automated by the `+%{goname}+` macro. +This macro will remove any capitalization, "go" keywords, and any duplication in +the import path. ++ +For example: ++ +-- +** the import path `+github.com/kr/pretty+` will become +`+golang-github-kr-pretty+` +** the import path `+github.com/DATA-DOG/go-txdb+` will become +`+golang-github-data-dog-txdb+` +** the import path `+github.com/gopherjs/gopherjs+` will become +`+golang-github-gopherjs+` +-- + ++ +The filename of spec MUST match the name of the package. + ++ +If you're not sure what will the name processed by the `+%{goname}+` macro be, +simply build the SRPM with: + + + fedpkg --release f31 srpm + ++ +The SRPM filename will be the one to use in your rpmspec and spec filename. + +* Source packages that provide a well-known application such as `+etcd+` +MUST be named after the application. +End users do not care about the language their applications are written in. But +do not name packages after an obscure utility binary that happens to be built by +the package. + + +==== Implementation: `+%{gorpmname}+` + +`+%gometa+` uses the `+%{gorpmname}+` macro to compute the main `+%{goname}+` +from `+%{goipath}+`. + +[NOTE] +==== +*`+%{gorpmname}+` can produce collisions* + +`+%{gorpmname}+` tries to compute human-friendly and rpm-compatible naming from +Go import paths. It simplifies them, removing redundancies and common +qualifiers. +As a result it is possible for two different import paths to produce the same +result. In that case, feel free to adjust this result manually to avoid the +collision. +==== + +=== Go code packages: `+%{goname}-devel+` +==== In a source package dedicated to providing Go code + +Packages that ship Go code in `+%{goipath}+` should be named +`+%{goname}-devel+`. +If your source package is already named `+%{goname}+`, that is easily achieved +with: + +[source,RPMSpec] +---- +%package devel +[…] +%description devel +[…] +%files devel -f devel.file-list +---- + +==== In a another kind of source package + +If your source package is named something other than `+%{goname}+`, you SHOULD +use: + +[source,RPMSpec] +---- +%package -n %{goname}-devel +[…] +%description -n %{goname}-devel +[…] +%files -n %{goname}-devel -f devel.file-list +---- + +==== Separate code packages + +And, finally, if you wish to split the project Go code in multiple packages, +you can compute the corresponding names with: + +[source,RPMSpec] +---- +%global goname1 %gorpmname importpath1 +[…] +%package -n %{goname1}-devel +[…] +%description -n %{goname1}-devel +[…] +%files -n %{goname1}-devel -f %{goname1}.file-list +---- + +See also the xref:Golang_advanced.adoc#_dealing_with_cyclic_dependencies[Dealing with cyclic dependencies] +chapter. + +Do remember that for Go, each directory is a package. Never separate the .go +files contained in a single directory in different packages. + +==== Import path compatibility packages: `+%{compat-%{oldgoname}-devel}+` + +When a project can be referenced under multiple import paths, due to forks, +renamings, rehostings, organizational changes, or confusing project +documentation, it is possible to generate compatibility sub-packages to +connect code that uses one of the other import paths to the canonical one. + +The canonical import path SHOULD always be the one referenced in the project +documentation. +However some projects do not document import path changes, and rely on HTTPS +redirections (for example https://github.com/docker/docker → +https://github.com/moby/moby). +Such a redirection is a sufficient indicator the canonical import path has +changed (but please make sure with upstream). + +The new import path SHOULD be reflected in `+%{goipath}+` and compatibility +import paths MUST be declared with the `+goaltipaths+` macro: + +[source,RPMSpec] +---- +# A space-separated list of import paths to simulate. +%global goaltipaths +---- + +For example, the Go library `+github.com/Sirupsen/logrus+` was renamed +`+github.com/sirupsen/logrus+` and the documentatuon reflects this new import +path. +The packager SHOULD thus request a renaming of his package with a new import +path and a compatibility import path: + +[source,RPMSpec] +---- +%global goipath github.com/sirupsen/logrus +%global goaltipaths github.com/Sirupsen/logrus +---- + +If a project has gone through multiple rename, multiple compatibility import +paths can be specified as well. + +[NOTE] +==== +*Never defer renamings* + +Packagers MUST NOT use import path compatibility sub-packages to alias the +canonical import path to one of the previous namings. +Packagers MUST apply upstream renaming choices to the main `+%{goipath}+` spec +variable and +everything that derives from it, such as `+%{goname}+`. +Deferred renamings introduce friction with upstream and other packagers. +==== + +=== Go binary packages + +The binaries produced by your rpmspec SHOULD generally be listed in the main +package. However, if you want a more appropriate name or split binaries among +different packages, you can create additional binary subpackage. +Of course these package MUST NOT be noarch. + +For example we can create the package bbolt that will contain the binary +of the same name: + +[source,RPMSpec] +---- +%package -n bbolt +[…] +%description -n bbolt +[…] +%files -n bbolt +%license LICENSE +%{_bindir}/bbolt +---- + +== Versioning + +Many Go libraries do not use package versions or have regular releases and +are instead maintained in public version control. +In this case, follow the standard Fedora version conventions. This means that +often Go packages will have a version number of `+0+` and a release number like +`+0.10.20190319git27435c6+`. + +Most of this process is automated by macros so that you don't have to specify +the release number yourself. + +You first specify either a Version, tag or commit in the header. + +[source,RPMSpec] +---- +Version: +%global tag +%global commit +---- + +Then use the `+%gometa+` macro: + + %gometa + +The `+%gometa+` macro will automatically process the `+%{?dist}+` tag of the +`+Release+` field to take into account the commit if any. + +[NOTE] +==== +*Commits vs releases* + +You SHOULD package releases in priority. +Please reward the projects that make an effort to identify stable code states. +Only fall back to commits when the project does not release, when the release is +more than six months old, or if +you absolutely need one of the changes of a later commit. +In the later cases please inform the project politely of the reason you needed +to give up on their official releases. +Promoting releases is a way to limit incompatible commit hell. +==== + +== Go Language Architectures + +To compile on various architectures, golang and gcc-go compilers are available. +The golang compiler currently supports x86, x86_64, ppc64le, ppc64 (partially, +see upstream issue#13192), s390x, armv7hl and aarch64. + +Binaries SHOULD set ExclusiveArch so that we only attempt to build packages on +those arches. +This is now automatically added by the `+%gometa+` macro by leveraging the +`+%{go_arches}+` macro. + +== Dependencies + +Packages MUST have `+BuildRequires: go-rpm-macros+`. + +This is automated by the `+%gometa+` macro. + + +=== Automatic Dependency Generation + +Most of the `+golang-*+` packages are source code only. +The `+*-devel+` sub-package that includes the source code should explicitly have +provides for the golang imports that it includes. +These provides are automatically deduced from import paths. + +Binary builds that include these imports will use them in BuildRequires, +for example: + +[source,RPMSpec] +---- +BuildRequires: golang(github.com/gorilla/context) +---- + +=== Bundled or unbundled + +At the moment golang projects packaged in Fedora SHOULD be unbundled by +default. It means projects are built from dependencies packaged in Fedora. + +For some project it can be reasonable to build from bundled dependencies. +Every bundling needs a proper justification. + + +=== BuildRequires + +The BuildRequires of the project contains the dependencies needed by unit tests +and binaries. + +You can gather them manually with `golist`. +For example:[[manual_br]] + +[source,bash] +---- + export GOPATH=/home/user/go + export goipath="github.com/sirupsen/logrus" + go get $goipath + (sort -u | xargs -I{} echo "BuildRequires: golang({})") <<< "$( + golist --imported --package-path $goipath --skip-self + golist --imported --package-path $goipath --skip-self --tests + )" +---- + +outputs: + +[source] +---- +BuildRequires: golang(github.com/stretchr/testify/assert) +BuildRequires: golang(github.com/stretchr/testify/require) +BuildRequires: golang(golang.org/x/crypto/ssh/terminal) +---- + +If automatic buildrequires are available on your build target, you can use +the `+%go_generate_buildrequires+` macro in `+%generate_buildrequires+`: + +[source,RPMSpec] +---- +%generate_buildrequires +%go_generate_buildrequires +---- + +This macro leverages `+golist+` to gather build dependencies and tests +dependencies from the package source. + +== Testing + +You MUST run unit tests. +Due to the nature of Go development, especially the lack of use of semantic +versioning, API breakages are frequent.These need to be detected early and dealt +with upstream. + +Some tests may be disabled, especially the following kinds of unit tests are +incompatible with a secure build environment such as mock: + +* 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. + +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. + +== Walkthrough + +This chapter will present a typical Go spec file step by step, with comments +and explanations. + +=== Spec preamble: `+%{goipath}+`, `+%{forgeurl}+` and `+%gometa+` + +==== Usual case + +A Go package is identified by its import path. A Go spec file will therefore +start with the `+%{goipath}+` declaration. Don't get it wrong, it will control +the behaviour of the rest of the spec file. + + %global goipath google.golang.org/api + +If your package is hosted on a forge like GitHub, GitLab, Bitbucket or Pagure, +the hosting of the Go package will be automatically deduced from this variable +(typically by prefixing it with \https://). If that is not the case, you need +to declare explicitly the hosting URL with the `+%{forgeurl}+` macro + + %global forgeurl https://github.com/google/google-api-go-client + +The `+%{forgeurl}+` declaration is followed by either `+Version+`, `+commit+` or +`+tag+`. Use the combination that matches your use-case. + + %global commit 2dc3ad4d67ba9a37200c5702d36687a940df1111 + +[NOTE] +==== +You can also define `+date+` to override the mtime of the Source archive. +==== + +Now that we have all the required variables, the `+%gometa+` macro can be run + + %gometa + +It will compute and set the following variables if they are not already set by +the packager: + +goname:: an rpm-compatible package name derived from goipath +gosource:: a URL that can be used as SourceX: value +gourl:: a URL that can be used as URL: value + +It will delegate processing to the `+%forgemeta+` macro for: + +forgesource:: a URL that can be used as SourceX: value +forgesetupargs:: the correct arguments to pass to `+%setup+` for this source +used by `+%forgesetup+` and `+%forgeautosetup+` +archivename:: the source archive filename, without extensions +archiveext:: the source archive filename extensions, without leading dot +archiveurl:: the URL that can be used to download the source archive, +without renaming +topdir:: the source archive top directory (can be empty) +extractdir:: the source directory created inside `+%{_builddir}+` after +using `+%forgesetup+`, `+%forgeautosetup+` or `+%{forgesetupargs}+` +repo:: the repository name +owner:: the repository owner (if used by another computed variable) +shortcommit:: the commit hash clamping used by the forge, if any +scm:: the scm type, when packaging code snapshots: commits or tags +distprefix:: the prefix that needs adding to dist to trace non-release +packaging + +Most of the computed variables are both overridable and optional. + +Now we can add the remaining elements of the preamble. First, we can define a +multiline description block shared between subpackages: + +[source,RPMSpec] +---- +%global common_description %{expand: +cmux is a generic Go library to multiplex connections based on their payload. +Using cmux, you can serve gRPC, SSH, HTTPS, HTTP, Go RPC, and pretty much any +other protocol on the same TCP listener.} +---- + +This description MUST stay within 80 characters per line. + +[NOTE] +==== +If you need specific devel summary and description, you can also define: + +- `+%global godevelsummary+` +- `+%global godeveldescription+` +==== + +Then we MUST specify the license files that will be added to the devel +subpackages: + +`+%global golicenses+`: A space-separated list of shell globs matching the +project license files. + +And the possible documentation that SHOULD be included: + +`+%global godocs+`: 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. + +[NOTE] +==== +You can also exclude files from `+%golicense+` and `+%godocs+` with: + +- `+%global golicensesex+` +- `+%global godocsex+` + +For example you might want to exclude `+INSTALL*+` files from `+%godocs+` as +these should not be provided. +==== + +=== Source package metadata: `+%{goname}+`, `+%{gourl}+` and `+%{gosource}+` + +We can declare the usual rpm headers, using the values computed by `+%gometa+`: + +[source,RPMSpec] +---- +Name: %{goname} +# If not set before +Version: +Release: 1%{?dist} +Summary: +License: +URL: %{gourl} +Source0: %{gosource} +---- + +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. + +=== BuildRequires + +If they are not automatically generated, you can now add the dependencies needed +for package building and unit testings: + +[source,RPMSpec] +---- +BuildRequires: golang(github.com/stretchr/testify/assert) +BuildRequires: golang(github.com/stretchr/testify/require) +BuildRequires: golang(golang.org/x/crypto/ssh/terminal) +---- + +See <> on how to get the BuildRequires list manually. + +=== Description + +Now add the main package description: + +[source,RPMSpec] +---- +%description +%{common_description} +---- + +=== Package metadata + +The process of declaring Go code packages has been automated with the +`+%{gopkg}+` macro. It will automatically generate a `+%package+` and +`+%description+` for all primary import paths and compatibility ones. + + %gopkg + +If you only need to generate Go devel subpackages without compat, use: + + %godevelpkg + +If necessary, you can then define one or multiple Go packages that will +contain the binaries being built. See the previous <> +section. + +=== %prep: `+%goprep+` , removing vendoring + +`+%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. + + %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) + +[NOTE] +==== +You SHOULD send fixes and problem reports upstream. Any patch used +SHOULD contain a link to an upstream bug report or merge request. At minimum, +a comment SHOULD be added to explain the patch rationale. +==== + +When you package an import path, that participates in a dependency loop, you +need bootstrapping 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 +xref:Golang_advanced.adoc#_dealing_with_cyclic_dependencies[Dealing with cyclic dependencies]. + +=== Automatic BuildRequires + +If BuildRequires generator are supported, you can now add them to your build: + +[source,RPMSpec] +---- +%generate_buildrequires +%go_generate_buildrequires +---- + +=== Packaging a binary: the %build section + +If your package is a source package only, you can skip this `+%build+` section +entirely. + +Otherwise, you first 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. + +[source,RPMSpec] +---- +for cmd in cmd/* ; do + %gobuild -o %{gobuilddir}/bin/$(basename $cmd) %{goipath}/$cmd +done +---- + +=== Installing the packages +==== Source package installation + +If you package a library, `+%gopkginstall+` will perform installation steps +for all primary import paths and compatibility ones. + + %gopkginstall + +If you only need to install Go devel subpackages without compat, use: + + %godevelinstall + +==== Binary package installation + +For binaries, we simply create the `+%{_bindir}+` directory in the buildroot +and install the commands as executable in it: + +[source,RPMSpec] +---- +install -m 0755 -vd %{buildroot}%{_bindir} +install -m 0755 -vp %{gobuilddir}/bin/* %{buildroot}%{_bindir}/ +---- + +[NOTE] +==== +Be wary of command names which might already exist in Fedora. If you have +any doubt, you can check if the command is already provided in Fedora: + +[source,shell] +---- +dnf whatprovides --disablerepo="*" --enablerepo=rawhide "/usr/bin/$cmd" +---- + +If this is the case, use your best judgment to rename the command. +==== + + +=== Running the unit tests: `+%gocheck+` + +As said before, you MUST run unit tests in `+%check+`: + + %gocheck + +However it is often necessary to disable some of them. You have 3 exclusion +flags to do so: + +* `+-d +`: exclude the files contained in `++` + non-recursively (subdirectories are not excluded) +* `+-t +`: exclude the files contained in `++` + recursively (subdirectories are excluded) +* `+-r +`: exclude files matching `++` + +Remember to document why a test has been disabled. + +=== %files declaration +==== When shipping source code + +The `+%gopkgfiles+` will process the file list produced in `+%install+` and add +the necessary license and documentation files: + + %gopkgfiles + +==== When shipping binaries + +Binaries are usually shipped in the main package. This package MUST include +legal files and documentation associated with those binaries. + +[source,RPMSpec] +---- +%files +%license LICENSE +%doc cmd/foo/README.md +%{_bindir}/* +---- + +== Examples + +=== Simple source package + +.golang-github-stretchr-testify.spec +[source,RPMSpec] +---- +include::{examplesdir}/golang/golang-github-stretchr-testify.spec[] +---- + +=== Handling package renames + +.golang-github-sirupsen-logrus.spec +[source,RPMSpec] +---- +include::{examplesdir}/golang/golang-github-sirupsen-logrus.spec[] +---- + +=== Simple binary package + +.golang-github-boltdb-bolt.spec +[source,RPMSpec] +---- +include::{examplesdir}/golang/golang-gopkg-square-jose-2.spec[] +---- + +== Additional resources + +=== Advanced uses cases + +** xref:Golang_advanced.adoc#_shipping_additional_files[Shipping additional files] +** xref:Golang_advanced.adoc#_additional_header_declarations[Additional header declarations] +** xref:Golang_advanced.adoc#_dealing_with_cyclic_dependencie[Dealing with cyclic dependencies] + +=== Additional annotated templates + +** xref:Golang_templates.adoc#_minimal_source_package[Minimal source package] +** xref:Golang_templates.adoc#_full_source_package[Full source package] +** xref:Golang_templates.adoc#_minimal_alternative_import_path[Minimal alternative import path] +** xref:Golang_templates.adoc#_full_alternative_import_path[Full alternative import path] +** xref:Golang_templates.adoc#_minimal_binary[Minimal binary] +** xref:Golang_templates.adoc#_full_binary[Full binary] +** xref:Golang_templates.adoc#_multi_package[Multi package] +** xref:Golang_templates.adoc#_manual_package_deprecated[Manual package (deprecated)] diff --git a/guidelines/modules/ROOT/pages/Golang_advanced.adoc b/guidelines/modules/ROOT/pages/Golang_advanced.adoc new file mode 100644 index 0000000..3d8df21 --- /dev/null +++ b/guidelines/modules/ROOT/pages/Golang_advanced.adoc @@ -0,0 +1,297 @@ += Advanced uses cases +:last-reviewed: 2019-06-19 +:toc: + +== Shipping additional files + +If you need to ship additional files in your source code packages, you can use +the following macros in the preamble: + +* `+%global goextensions+` A space separated list of extensions that should + be included in the devel package in addition to + Go default file extensions. +* `+%global gosupfiles+`: A space-separated list of shell globs matching + other files to include in the devel package. +* `+%global gosupfilesex+` A space-separated list of shell globs matching + other files you wish to exclude from package lists. + Only works with “gosupfiles”-specified files. + +For example, if you have glide files to ship: + +[source,RPMSpec] +---- +%global gosupfiles glide.yaml glide.lock +---- + +== Additional header declarations + +Use `+%godevelheader+` to add specific subpackage declarations. For example, you +might want to require the main package containing the binaries, or +Obsoletes/Provides another package in case of renaming. + +[source,RPMSpec] +---- +%global godevelheader %{expand: +Requires: +Obsoletes: +Provides: +} +---- + +== Dealing with cyclic dependencies + +In many cases, you'll encounter packages that depend on each other, also known +as cyclic dependencies, making it difficult to build either package. + +Typically, when you have a problematic requires, it is only used in specific +project subpackages, and most project dependents do not need those subpackages +directly or indirectly. The idea is then to affect the goipaths associated with +the problematic subpackages to a separate -devel rpm package, to simplify +your dependency graph. + +Let's take for example the following packages: `+cloud.google.com/go+` and +`+golang.org/x/oauth2+`. + +`+cloud.google.com/go+` has the following dependency graph: + + +[source] +---- +github.com/golang/mock/gomock +github.com/golang/protobuf/proto +github.com/golang/protobuf/ptypes +github.com/golang/protobuf/ptypes/any +github.com/golang/protobuf/ptypes/duration +github.com/golang/protobuf/ptypes/empty +github.com/golang/protobuf/ptypes/struct +github.com/golang/protobuf/ptypes/timestamp +github.com/golang/protobuf/ptypes/wrappers +github.com/google/btree +github.com/google/go-cmp/cmp +github.com/google/martian +github.com/google/martian/fifo +github.com/google/martian/httpspec +github.com/google/martian/martianhttp +github.com/google/martian/martianlog +github.com/google/martian/mitm +github.com/google/pprof/profile +github.com/googleapis/gax-go/v2 +go.opencensus.io/plugin/ocgrpc +go.opencensus.io/stats +go.opencensus.io/stats/view +go.opencensus.io/tag +go.opencensus.io/trace +golang.org/x/build/kubernetes +golang.org/x/build/kubernetes/api +golang.org/x/build/kubernetes/gke +golang.org/x/oauth2 +golang.org/x/oauth2/google +golang.org/x/oauth2/jwt +golang.org/x/sync/errgroup +golang.org/x/sync/semaphore +golang.org/x/text/language +golang.org/x/time/rate +[…] +---- + +And `+golang.org/x/oauth2+` has the following dependency graph: + +[source] +---- +cloud.google.com/go/compute/metadata +golang.org/x/net/context/ctxhttp +---- + +As you can see both packages depend on each other. +If we search for where `+cloud.google.com/go+` is used in +`+golang.org/x/oauth2+`: + +[source,bash] +---- +grep -nr "cloud.google.com/go/compute/metadata" $GOPATH/src/golang.org/x/oauth2 + +/home/user/go/src/golang.org/x/oauth2/google/default.go:17: "cloud.google.com/go/compute/metadata" +/home/user/go/src/golang.org/x/oauth2/google/google.go:15: "cloud.google.com/go/compute/metadata" +---- + +we can see that it is used in the`+golang.org/x/oauth2/google+` subpackage, +which is precisely the subpackage needed by `+cloud.google.com/go+`. It is thus +not possible to split `+golang.org/x/oauth2/google+` into separate devel +subpackage to resolve our cyclic dependency graph. + + +Now if we search for where `+golang.org/x/oauth2+` is used in +`+cloud.google.com/go+`: + +[source,bash] +---- +grep -nr "golang.org/x/oauth2/google" $GOPATH/src/cloud.google.com/go + +/home/user/go/src/cloud.google.com/go/cmd/go-cloud-debug-agent/debuglet.go:38: "golang.org/x/oauth2/google" +/home/user/go/src/cloud.google.com/go/internal/testutil/context.go:26: "golang.org/x/oauth2/google" +/home/user/go/src/cloud.google.com/go/profiler/integration_test.go:30: "golang.org/x/oauth2/google" +/home/user/go/src/cloud.google.com/go/authexample_test.go:22: "golang.org/x/oauth2/google" +---- + +we can see that it is not used in the `+cloud.google.com/go/compute/metadata+` +subpackage. As a result we can split `+cloud.google.com/go/compute/metadata+` +into a separate devel subpackage to resolve our cyclic dependency graph. + +To achieve this, we use multiple `+goipaths+` in the preamble: + +[source,RPMSpec] +---- +%global goipaths0 cloud.google.com/go +%global goipathsex0 cloud.google.com/go/compute + +%global goipaths1 cloud.google.com/go/compute +---- + +`+goipaths0+` will be the main package from which we exclude `+compute+`, and +`+goipaths1+` will be the split package containing it. + +After building, we end up with two packages: + +* `+golang-cloud-google-devel-0.36.0-1.fc31.x86_64.rpm+`, which provides: ++ +[source] +---- +golang(cloud.google.com/go) = 0.36.0-1.fc31 +golang(cloud.google.com/go/asset/apiv1beta1) = 0.36.0-1.fc31 +golang(cloud.google.com/go/asset/v1beta1) = 0.36.0-1.fc31 +golang(cloud.google.com/go/bigquery) = 0.36.0-1.fc31 +golang(cloud.google.com/go/bigquery/datatransfer/apiv1) = 0.36.0-1.fc31 +golang(cloud.google.com/go/bigquery/storage/apiv1beta1) = 0.36.0-1.fc31 +golang(cloud.google.com/go/bigtable) = 0.36.0-1.fc31 +golang(cloud.google.com/go/bigtable/bttest) = 0.36.0-1.fc31 +golang(cloud.google.com/go/bigtable/internal/cbtconfig) = 0.36.0-1.fc31 +golang(cloud.google.com/go/bigtable/internal/gax) = 0.36.0-1.fc31 +golang(cloud.google.com/go/bigtable/internal/option) = 0.36.0-1.fc31 +golang(cloud.google.com/go/bigtable/internal/stat) = 0.36.0-1.fc31 +golang(cloud.google.com/go/civil) = 0.36.0-1.fc31 +golang(cloud.google.com/go/cloudtasks/apiv2beta2) = 0.36.0-1.fc31 +golang(cloud.google.com/go/cloudtasks/apiv2beta3) = 0.36.0-1.fc31 +golang(cloud.google.com/go/cmd/go-cloud-debug-agent/internal/breakpoints) = 0.36.0-1.fc31 +golang(cloud.google.com/go/cmd/go-cloud-debug-agent/internal/controller) = 0.36.0-1.fc31 +golang(cloud.google.com/go/cmd/go-cloud-debug-agent/internal/debug) = 0.36.0-1.fc31 +golang(cloud.google.com/go/cmd/go-cloud-debug-agent/internal/debug/arch) = 0.36.0-1.fc31 +golang(cloud.google.com/go/cmd/go-cloud-debug-agent/internal/debug/dwarf) = 0.36.0-1.fc31 +golang(cloud.google.com/go/cmd/go-cloud-debug-agent/internal/debug/elf) = 0.36.0-1.fc31 +golang(cloud.google.com/go/cmd/go-cloud-debug-agent/internal/debug/gosym) = 0.36.0-1.fc31 +golang(cloud.google.com/go/cmd/go-cloud-debug-agent/internal/debug/local) = 0.36.0-1.fc31 +golang(cloud.google.com/go/cmd/go-cloud-debug-agent/internal/debug/remote) = 0.36.0-1.fc31 +golang(cloud.google.com/go/cmd/go-cloud-debug-agent/internal/debug/server) = 0.36.0-1.fc31 +golang(cloud.google.com/go/cmd/go-cloud-debug-agent/internal/debug/server/protocol) = 0.36.0-1.fc31 +golang(cloud.google.com/go/cmd/go-cloud-debug-agent/internal/debug/tests/peek) = 0.36.0-1.fc31 +golang(cloud.google.com/go/cmd/go-cloud-debug-agent/internal/valuecollector) = 0.36.0-1.fc31 +golang(cloud.google.com/go/container) = 0.36.0-1.fc31 +golang(cloud.google.com/go/container/apiv1) = 0.36.0-1.fc31 +golang(cloud.google.com/go/containeranalysis/apiv1beta1) = 0.36.0-1.fc31 +golang(cloud.google.com/go/dataproc/apiv1) = 0.36.0-1.fc31 +golang(cloud.google.com/go/dataproc/apiv1beta2) = 0.36.0-1.fc31 +golang(cloud.google.com/go/datastore) = 0.36.0-1.fc31 +golang(cloud.google.com/go/debugger/apiv2) = 0.36.0-1.fc31 +golang(cloud.google.com/go/dialogflow/apiv2) = 0.36.0-1.fc31 +golang(cloud.google.com/go/dlp/apiv2) = 0.36.0-1.fc31 +golang(cloud.google.com/go/errorreporting) = 0.36.0-1.fc31 +golang(cloud.google.com/go/errorreporting/apiv1beta1) = 0.36.0-1.fc31 +golang(cloud.google.com/go/expr/apiv1alpha1) = 0.36.0-1.fc31 +golang(cloud.google.com/go/firestore) = 0.36.0-1.fc31 +golang(cloud.google.com/go/firestore/apiv1) = 0.36.0-1.fc31 +golang(cloud.google.com/go/firestore/apiv1beta1) = 0.36.0-1.fc31 +golang(cloud.google.com/go/firestore/genproto) = 0.36.0-1.fc31 +golang(cloud.google.com/go/firestore/internal) = 0.36.0-1.fc31 +golang(cloud.google.com/go/functions/metadata) = 0.36.0-1.fc31 +golang(cloud.google.com/go/httpreplay) = 0.36.0-1.fc31 +golang(cloud.google.com/go/httpreplay/internal/proxy) = 0.36.0-1.fc31 +golang(cloud.google.com/go/iam) = 0.36.0-1.fc31 +golang(cloud.google.com/go/iam/admin/apiv1) = 0.36.0-1.fc31 +golang(cloud.google.com/go/iam/credentials/apiv1) = 0.36.0-1.fc31 +golang(cloud.google.com/go/internal) = 0.36.0-1.fc31 +golang(cloud.google.com/go/internal/btree) = 0.36.0-1.fc31 +golang(cloud.google.com/go/internal/fields) = 0.36.0-1.fc31 +golang(cloud.google.com/go/internal/leakcheck) = 0.36.0-1.fc31 +golang(cloud.google.com/go/internal/optional) = 0.36.0-1.fc31 +golang(cloud.google.com/go/internal/pretty) = 0.36.0-1.fc31 +golang(cloud.google.com/go/internal/protostruct) = 0.36.0-1.fc31 +golang(cloud.google.com/go/internal/testutil) = 0.36.0-1.fc31 +golang(cloud.google.com/go/internal/trace) = 0.36.0-1.fc31 +golang(cloud.google.com/go/internal/tracecontext) = 0.36.0-1.fc31 +golang(cloud.google.com/go/internal/uid) = 0.36.0-1.fc31 +golang(cloud.google.com/go/internal/version) = 0.36.0-1.fc31 +golang(cloud.google.com/go/irm/apiv1alpha2) = 0.36.0-1.fc31 +golang(cloud.google.com/go/kms/apiv1) = 0.36.0-1.fc31 +golang(cloud.google.com/go/language/apiv1) = 0.36.0-1.fc31 +golang(cloud.google.com/go/language/apiv1beta2) = 0.36.0-1.fc31 +golang(cloud.google.com/go/logging) = 0.36.0-1.fc31 +golang(cloud.google.com/go/logging/apiv2) = 0.36.0-1.fc31 +golang(cloud.google.com/go/logging/internal) = 0.36.0-1.fc31 +golang(cloud.google.com/go/logging/internal/testing) = 0.36.0-1.fc31 +golang(cloud.google.com/go/logging/logadmin) = 0.36.0-1.fc31 +golang(cloud.google.com/go/longrunning) = 0.36.0-1.fc31 +golang(cloud.google.com/go/longrunning/autogen) = 0.36.0-1.fc31 +golang(cloud.google.com/go/monitoring/apiv3) = 0.36.0-1.fc31 +golang(cloud.google.com/go/oslogin/apiv1) = 0.36.0-1.fc31 +golang(cloud.google.com/go/oslogin/apiv1beta) = 0.36.0-1.fc31 +golang(cloud.google.com/go/profiler) = 0.36.0-1.fc31 +golang(cloud.google.com/go/profiler/mocks) = 0.36.0-1.fc31 +golang(cloud.google.com/go/profiler/proftest) = 0.36.0-1.fc31 +golang(cloud.google.com/go/pubsub) = 0.36.0-1.fc31 +golang(cloud.google.com/go/pubsub/apiv1) = 0.36.0-1.fc31 +golang(cloud.google.com/go/pubsub/internal/distribution) = 0.36.0-1.fc31 +golang(cloud.google.com/go/pubsub/loadtest) = 0.36.0-1.fc31 +golang(cloud.google.com/go/pubsub/loadtest/pb) = 0.36.0-1.fc31 +golang(cloud.google.com/go/pubsub/pstest) = 0.36.0-1.fc31 +golang(cloud.google.com/go/redis/apiv1) = 0.36.0-1.fc31 +golang(cloud.google.com/go/redis/apiv1beta1) = 0.36.0-1.fc31 +golang(cloud.google.com/go/rpcreplay) = 0.36.0-1.fc31 +golang(cloud.google.com/go/rpcreplay/proto/intstore) = 0.36.0-1.fc31 +golang(cloud.google.com/go/rpcreplay/proto/rpcreplay) = 0.36.0-1.fc31 +golang(cloud.google.com/go/scheduler/apiv1beta1) = 0.36.0-1.fc31 +golang(cloud.google.com/go/securitycenter/apiv1beta1) = 0.36.0-1.fc31 +golang(cloud.google.com/go/spanner) = 0.36.0-1.fc31 +golang(cloud.google.com/go/spanner/admin/database/apiv1) = 0.36.0-1.fc31 +golang(cloud.google.com/go/spanner/admin/instance/apiv1) = 0.36.0-1.fc31 +golang(cloud.google.com/go/spanner/apiv1) = 0.36.0-1.fc31 +golang(cloud.google.com/go/spanner/internal/backoff) = 0.36.0-1.fc31 +golang(cloud.google.com/go/spanner/internal/testutil) = 0.36.0-1.fc31 +golang(cloud.google.com/go/speech/apiv1) = 0.36.0-1.fc31 +golang(cloud.google.com/go/speech/apiv1p1beta1) = 0.36.0-1.fc31 +golang(cloud.google.com/go/storage) = 0.36.0-1.fc31 +golang(cloud.google.com/go/talent/apiv4beta1) = 0.36.0-1.fc31 +golang(cloud.google.com/go/texttospeech/apiv1) = 0.36.0-1.fc31 +golang(cloud.google.com/go/trace) = 0.36.0-1.fc31 +golang(cloud.google.com/go/trace/apiv1) = 0.36.0-1.fc31 +golang(cloud.google.com/go/trace/apiv2) = 0.36.0-1.fc31 +golang(cloud.google.com/go/translate) = 0.36.0-1.fc31 +golang(cloud.google.com/go/translate/internal/translate/v2) = 0.36.0-1.fc31 +golang(cloud.google.com/go/videointelligence/apiv1) = 0.36.0-1.fc31 +golang(cloud.google.com/go/videointelligence/apiv1beta1) = 0.36.0-1.fc31 +golang(cloud.google.com/go/videointelligence/apiv1beta2) = 0.36.0-1.fc31 +golang(cloud.google.com/go/vision/apiv1) = 0.36.0-1.fc31 +golang(cloud.google.com/go/vision/apiv1p1beta1) = 0.36.0-1.fc31 +golang-cloud-google-devel = 0.36.0-1.fc31 +golang-cloud-google-devel(x86-64) = 0.36.0-1.fc31 +golang-ipath(cloud.google.com/go) = 0.36.0-1.fc31 +---- +* `+golang-cloud-google-compute-devel-0.36.0-1.fc31.x86_64.rpm+`, which +provides: ++ +[source] +---- +golang(cloud.google.com/go/compute/metadata) = 0.36.0-1.fc31 +golang-cloud-google-compute-devel = 0.36.0-1.fc31 +golang-cloud-google-compute-devel(x86-64) = 0.36.0-1.fc31 +golang-ipath(cloud.google.com/go/compute) = 0.36.0-1.fc31 +---- + +We now have broken the cyclic dependency graph: `+golang.org/x/oauth2+` can now +depend separately on `+golang-cloud-google-compute-devel+`. + +Here is the full example: + +.golang-cloud-google-go.spec +[source,RPMSpec] +---- +include::{examplesdir}/golang/golang-cloud-google-go.spec[] +---- diff --git a/guidelines/modules/ROOT/pages/Golang_templates.adoc b/guidelines/modules/ROOT/pages/Golang_templates.adoc new file mode 100644 index 0000000..157bff7 --- /dev/null +++ b/guidelines/modules/ROOT/pages/Golang_templates.adoc @@ -0,0 +1,67 @@ += Additional annotated templates +:last-reviewed: 2019-03-22 +:toc: + +== Minimal source package + +.spectemplate-go-0-source-minimal.spec +[source,RPMSpec] +---- +include::{examplesdir}/golang/spectemplate-go-0-source-minimal.spec[] +---- + +== Full source package + +.spectemplate-go-1-source-full.spec +[source,RPMSpec] +---- +include::{examplesdir}/golang/spectemplate-go-1-source-full.spec[] +---- + +== Minimal alternative import path + +.spectemplate-go-2-alternative-import-path-minimal.spec +[source,RPMSpec] +---- +include::{examplesdir}/golang/spectemplate-go-2-alternative-import-path-minimal.spec[] +---- + +== Full alternative import path + +.spectemplate-go-3-alternative-import-path-full.spec +[source,RPMSpec] +---- +include::{examplesdir}/golang/spectemplate-go-3-alternative-import-path-full.spec[] +---- + +== Minimal binary + +.spectemplate-go-4-binary-minimal.spec +[source,RPMSpec] +---- +include::{examplesdir}/golang/spectemplate-go-4-binary-minimal.spec[] +---- + +== Full binary + +.spectemplate-go-5-binary-full.spec +[source,RPMSpec] +---- +include::{examplesdir}/golang/spectemplate-go-5-binary-full.spec[] +---- + +== Multi package + +.spectemplate-go-6-multi.spec +[source,RPMSpec] +---- +include::{examplesdir}/golang/spectemplate-go-6-multi.spec[] +---- + +== Manual package (deprecated) + +.spectemplate-go-7-manual.spec +[source,RPMSpec] +---- +include::{examplesdir}/golang/spectemplate-go-7-manual.spec[] +----