From Fedora Project Wiki
(adding back note on no debug stripping)
(Generate debuginfo rpms)
(6 intermediate revisions by 2 users not shown)
Line 1: Line 1:
{{Draft}}
{{Draft}}


= Go Packaging Guidelines =


= Naming =
= Naming =
Line 14: Line 13:


<pre>
<pre>
%global import_path     code.google.com/p/go.net
%global go_import_path     code.google.com/p/go.net
</pre>
</pre>


Line 58: Line 57:
All golang binary packages have an automatic exception to the standard policy.
All golang binary packages have an automatic exception to the standard policy.


The GCC-Go compiler by default produces dynamically-linked binaries and is capable of statically linking as well. GCC-Go is also unable to produce shared object libraries.
The GCC-Go compiler by default produces dynamically-linked binaries and is capable of statically linking as well.


At this stage, the reference compiler is the golang compiler, though gccgo is ready for use, and has demonstrated performance benefits for isolated use-cases.
At this stage, the reference compiler is the golang compiler, though gccgo is ready for use, and has demonstrated performance benefits for isolated use-cases.


== Debuginfo and Stripping Binaries ==
== Build ID ==


If you are using gccgo, stripped binaries are not presently supported [https://bugzilla.redhat.com/show_bug.cgi?id=927608]. If this applies to your package, use
The golang compiler (`gc`) does provide by default the ".note.gnu.build-id" section that GCC does. Though, if the binary being built supports being compiled with `gccgo`, the gccgo compiler does support and include the .note.gnu.build-id.
 
== Debuginfo ==
 
If you are using golang, DWZ is currently incompatible with binaries produced by it ([https://bugzilla.redhat.com/show_bug.cgi?id=995136#c12 Bug 995136]). To get at least partial DWZ optimization use:
<pre>
<pre>
%global __strip /bin/true
# https://bugzilla.redhat.com/show_bug.cgi?id=995136#c12
%global _dwz_low_mem_die_limit 0
</pre>
</pre>


 
If you are using golang, it does not produce build ID by default. Use this compilation command otherwise build ID packaging check would stop the package build:
For now, the debuginfo macro fails due to no build ID note on golang binaries, so disable the debug package.
<pre>
<pre>
%global debug_package %{nil}
# *** ERROR: No build ID note found in /.../BUILDROOT/etcd-2.0.0-1.rc1.fc22.x86_64/usr/bin/etcd
function gobuild { go build -a -ldflags "-B 0x$(head -c20 /dev/urandom|od -An -tx1|tr -d ' \n')" -v -x "$@"; }
</pre>
</pre>
There is still a bug the *.debug files in *-debuginfo.rpm will have incorrect reference to the source files directory - [https://bugzilla.redhat.com/show_bug.cgi?id=1184221 Bug 1184221].


== Dependencies ==
== Dependencies ==
Line 85: Line 91:
== Go Language Architectures ==
== Go Language Architectures ==


The golang compiler currently only supports x86 and Arm (32- and 64-bit). Binaries should set  
The golang compiler currently only supports x86, x86_64, and Arm (32- and 64-bit). Binaries should set <code>ExclusiveArch</code> so that we only attempt to build packages on those arches. The <code>golang</code> package provides the <code>%{go_arches}</code> macro for this:
 
<pre>
ExclusiveArch: %{ix86} x86_64 %{arm}
</pre>
 
In golang package > 1.2.1-1, this is shortened to


<pre>
<pre>
Line 108: Line 108:


Binary packages which build against this source will set $GOPATH to '%{_datadir}/gocode' ( or '%{gopath}' in golang > 1.2.1-1)
Binary packages which build against this source will set $GOPATH to '%{_datadir}/gocode' ( or '%{gopath}' in golang > 1.2.1-1)
== Shared-object libraries ==
There has been talk of golang having shared-object libraries at some point, but that is still presently only a discussion [https://groups.google.com/forum/#!topic/golang-nuts/zmjXkGrEx6Q] and somewhat stale review [https://codereview.appspot.com/9738047/].
Also, presently the shared object libraries produced by GCC-Go are not usable [https://gcc.gnu.org/ml/gcc-help/2011-06/msg00239.html].
Neither of these cases are a blocker for supported architectures using cgo to have dynamic links to a C/C++ compiled shared-object library [http://golang.org/cmd/cgo/].


== Dependencies ==
== Dependencies ==
Line 115: Line 122:
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. ''(without single or double quotes)''
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. ''(without single or double quotes)''
<pre>
<pre>
Provides: golang(%{import_path}) = %{version}-%{release}
Provides: golang(%{go_import_path}) = %{version}-%{release}
</pre>
</pre>


Line 130: Line 137:
<pre>
<pre>
BuildArch: noarch
BuildArch: noarch
ExclusiveArch: %{ix86} x86_64 %{arm} noarch
ExclusiveArch: %{go_arches} noarch
</pre>
</pre>


Line 141: Line 148:


<code>
<code>
repoquery -q --disablerepo='*' --enablerepo=fedora-source --enablerepo=updates-source --enablerepo=updates-testing-source --archlist=src --whatrequires golang-$WHATEVER-devel
repoquery -q --disablerepo='*' --enablerepo=fedora-source --enablerepo=updates-source --enablerepo=updates-testing-source --archlist=src --whatrequires 'golang($SOME_IMPORT_PATH)'
</code>
</code>


Line 148: Line 155:


<code>
<code>
repoquery -q --disablerepo='*' --enablerepo=fedora --enablerepo=updates --enablerepo=updates-testing  --whatrequires golang-$WHATEVER-devel
repoquery -q --disablerepo='*' --enablerepo=fedora --enablerepo=updates --enablerepo=updates-testing  --whatrequires 'golang($SOME_IMPORT_PATH)'
</code>
</code>


Line 159: Line 166:
== Packaging a library ==
== Packaging a library ==
<pre>
<pre>
%global import_path     code.google.com/p/go.net
%global go_import_path     code.google.com/p/go.net
%global rev            84a4013f96e01fdd14b65d260a78b543e3702ee1
%global rev            84a4013f96e01fdd14b65d260a78b543e3702ee1
%global shortrev        %(r=%{rev}; echo ${r:0:12})
%global shortrev        %(r=%{rev}; echo ${r:0:12})
Line 168: Line 175:
Summary:        Supplementary Go networking libraries
Summary:        Supplementary Go networking libraries
License:        BSD
License:        BSD
URL:            http://%{import_path}
URL:            http://%{go_import_path}
Source0:        https://net.go.googlecode.com/archive/%{rev}.zip
Source0:        https://net.go.googlecode.com/archive/%{rev}.zip
%if 0%{?fedora} >= 19
%if 0%{?fedora} >= 19
Line 183: Line 190:
Requires:      golang
Requires:      golang
Summary:        Supplementary Go networking libraries
Summary:        Supplementary Go networking libraries
Provides:      golang(%{import_path}) = %{version}-%{release}
Provides:      golang(%{go_import_path}) = %{version}-%{release}
Provides:      golang(%{import_path}/dict) = %{version}-%{release}
Provides:      golang(%{go_import_path}/dict) = %{version}-%{release}
# [...]
# [...]


Line 202: Line 209:


%install
%install
install -d %{buildroot}/%{gopath}/src/%{import_path}
install -d %{buildroot}/%{gopath}/src/%{go_import_path}
for d in dict html idna ipv4 ipv6 proxy publicsuffix spdy websocket; do
for d in dict html idna ipv4 ipv6 proxy publicsuffix spdy websocket; do
   cp -avp $d %{buildroot}/%{gopath}/src/%{import_path}/
   cp -avp $d %{buildroot}/%{gopath}/src/%{go_import_path}/
done
done


%check
%check
GOPATH=%{buildroot}/%{gopath} go test %{import_path}/html
GOPATH=%{buildroot}/%{gopath} go test %{go_import_path}/html
# [...]
# [...]


Line 215: Line 222:
%doc AUTHORS CONTRIBUTORS LICENSE PATENTS README
%doc AUTHORS CONTRIBUTORS LICENSE PATENTS README
%doc README-webkit
%doc README-webkit
%dir %attr(755,root,root) %{gopath}/src/%{import_path}
%dir %attr(755,root,root) %{gopath}/src/%{go_import_path}
%dir %attr(755,root,root) %{gopath}/src/%{import_path}/dict
%dir %attr(755,root,root) %{gopath}/src/%{go_import_path}/dict
%dir %attr(755,root,root) %{gopath}/src/%{import_path}/html
%dir %attr(755,root,root) %{gopath}/src/%{go_import_path}/html
# [...]
# [...]
%{gopath}/src/%{import_path}/dict/*.go
%{gopath}/src/%{go_import_path}/dict/*.go
%{gopath}/src/%{import_path}/html/*.go
%{gopath}/src/%{go_import_path}/html/*.go
# [...]
# [...]



Revision as of 21:00, 20 January 2015

Warning.png
This page is a draft only
It is still under construction and content may change. Do not rely on the information on this page.


Naming

Package Names

The package name idiom for the golang is that the import paths of libraries are fully qualified domain names. This way you have clarity to the precise upstream being used. We'll acknowledge this qualified path in the Provides, but also the package name should indicate the upstream project as much as possible. Truncating domain names and using '-' instead of '/'. For example, 'github.com/gorilla/context' would be 'golang-github-gorilla-context' for the base RPM name. Similarly, the 'code.google.com/p/go.net' repository would be 'golang-googlecode-net' base RPM name.

Import Path

In the golang library paths, are referenced in full URLs. Since this URL is referenced in several places throughout the rpmspec, as a standard, set the base import path as a global define at the top of the spec file

%global go_import_path     code.google.com/p/go.net

Versions

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.git27435c6".

To make that version and release string easier to manage, set global defines for the project's revision (and short revision if needed).

Hashed revisions

For projects that use a hashed version control (git, hg/mecurial), then the defines would look like:

%global rev             84a4013f96e01fdd14b65d260a78b543e3702ee1                
%global shortrev        %(r=%{rev}; echo ${r:0:12})

Then the Release: can be set as:

Release:        0.10.hg%{shortrev}%{?dist}

Numerical revisions

For projects that use a numerical version control (bzr), then the defines would look like:

%global rev             53                

Then the Release: can be set as:

Release:        0.10.bzr%{rev}%{?dist}


Packaging Binaries

Applications that have a 'main' package name, are compiled to a binary. These should be named after the upstream project, and do not need a "golang" prefix.

If that project does also include source libraries, then a subpackage can be produced with the "golang" prefix and Provides: for the import paths that are packaged.

The golang compiler only produces static binaries for all native golang source code. There is a C bridge logic that allows golang source to dynamically linked to C compiled shared objects (e.g. libssl), the the golang compiler can not produce a shared object library. All golang binary packages have an automatic exception to the standard policy.

The GCC-Go compiler by default produces dynamically-linked binaries and is capable of statically linking as well.

At this stage, the reference compiler is the golang compiler, though gccgo is ready for use, and has demonstrated performance benefits for isolated use-cases.

Build ID

The golang compiler (gc) does provide by default the ".note.gnu.build-id" section that GCC does. Though, if the binary being built supports being compiled with gccgo, the gccgo compiler does support and include the .note.gnu.build-id.

Debuginfo

If you are using golang, DWZ is currently incompatible with binaries produced by it (Bug 995136). To get at least partial DWZ optimization use:

# https://bugzilla.redhat.com/show_bug.cgi?id=995136#c12
%global _dwz_low_mem_die_limit 0

If you are using golang, it does not produce build ID by default. Use this compilation command otherwise build ID packaging check would stop the package build:

# *** ERROR: No build ID note found in /.../BUILDROOT/etcd-2.0.0-1.rc1.fc22.x86_64/usr/bin/etcd
function gobuild { go build -a -ldflags "-B 0x$(head -c20 /dev/urandom|od -An -tx1|tr -d ' \n')" -v -x "$@"; }

There is still a bug the *.debug files in *-debuginfo.rpm will have incorrect reference to the source files directory - Bug 1184221.

Dependencies

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. (without single or double quotes) Binary builds that include these imports will use BuildRequires:

BuildRequires: golang(github.com/gorilla/context) >= 0-0.13


Go Language Architectures

The golang compiler currently only supports x86, x86_64, and Arm (32- and 64-bit). Binaries should set ExclusiveArch so that we only attempt to build packages on those arches. The golang package provides the %{go_arches} macro for this:

ExclusiveArch:  %{go_arches}

Packaging Libraries

At this time, Go libraries packaged in Fedora are primarily for the purpose of being BuildRequires for building Fedora binary RPMs, and not meant to be developed against otherwise -- for that, we encourage the upstream "go get" idiom and a per-user $GOPATH.

We do not provide or recommend a system-wide GOPATH that users should inherit and there is no notion of a "site" or "vendor" path for system libriaries.

GOROOT is reserved for golang standard library only. This way developers do not need to be concerned with library path conflicts, but instead can choose to include the system path in their per-user path (e.g. export GOPATH=$HOME/go:/usr/share/gocode). This way a call to go get ... would land new source in the $HOME/go directory

The standard golang compiler only produces static libraries. There is little value in shipping these prebuilt, especially since these libraries are very specifically tied to the exact minor release of the golang compiler. Instead, each library package should consist of a -devel subpackage which installs .go source code to /usr/share/gocode/src, under the appropriate import path.

Binary packages which build against this source will set $GOPATH to '%{_datadir}/gocode' ( or '%{gopath}' in golang > 1.2.1-1)

Shared-object libraries

There has been talk of golang having shared-object libraries at some point, but that is still presently only a discussion [1] and somewhat stale review [2]. Also, presently the shared object libraries produced by GCC-Go are not usable [3].

Neither of these cases are a blocker for supported architectures using cgo to have dynamic links to a C/C++ compiled shared-object library [4].

Dependencies

To match the fully qualified import paths of the projects and source, utilize the meta wrapper / virtual provides in the golang namespace to provide the import paths being packaged.

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. (without single or double quotes)

Provides: golang(%{go_import_path}) = %{version}-%{release}

Then other source packages that reference these imports can have Requires: matching that:

Requires: golang(github.com/gorilla/context)


Libraries and Arch

Because these packages contain no compiled code, they should be made noarch. However, since they require golang, they need to only be built on the architectures supported by the language. For that reason, follow the standard guidelines for noarch packages with unported dependencies:

BuildArch: noarch
ExclusiveArch: %{go_arches} noarch

Security in Go Language Packages

If there is a security issue in the standard Go library or in a library built into binary Go programs, all affected RPMs will need to be rebuilt.

In the event that a security issue is found in a library, all packages which have that library as a BuildRequires must be identified and rebuilt with the version and release of the fixed library added to the BuildRequires.


repoquery -q --disablerepo='*' --enablerepo=fedora-source --enablerepo=updates-source --enablerepo=updates-testing-source --archlist=src --whatrequires 'golang($SOME_IMPORT_PATH)'


Additionally, other golang-*-devel packages may directly require their own dependencies; check for such packages with

repoquery -q --disablerepo='*' --enablerepo=fedora --enablerepo=updates --enablerepo=updates-testing --whatrequires 'golang($SOME_IMPORT_PATH)'

and, if any of the results are golang-*-devel RPMs, repeat the previous step to find packages which may have that as a BuildRequires.

Sample RPM Spec

Following a couple of example RPM spec files to give a sample layout for future packagers of libraries or applications written in golang.

Packaging a library

%global go_import_path     code.google.com/p/go.net
%global rev             84a4013f96e01fdd14b65d260a78b543e3702ee1
%global shortrev        %(r=%{rev}; echo ${r:0:12})

Name:           golang-googlecode-net
Version:        0
Release:        0.15.hg%{shortrev}%{?dist}
Summary:        Supplementary Go networking libraries
License:        BSD
URL:            http://%{go_import_path}
Source0:        https://net.go.googlecode.com/archive/%{rev}.zip
%if 0%{?fedora} >= 19
BuildArch:      noarch
%else
ExclusiveArch:  %{go_arches}
%endif
BuildRequires:  golang

%description
%{summary}

%package devel
Requires:       golang
Summary:        Supplementary Go networking libraries
Provides:       golang(%{go_import_path}) = %{version}-%{release}
Provides:       golang(%{go_import_path}/dict) = %{version}-%{release}
# [...]

%description devel
%{summary}

This package contains library source intended for building other packages
which use the supplementary Go networking libraries.


%prep

%setup -n net.go-%{shortrev}
cp html/testdata/webkit/README README-webkit

%build

%install
install -d %{buildroot}/%{gopath}/src/%{go_import_path}
for d in dict html idna ipv4 ipv6 proxy publicsuffix spdy websocket; do
   cp -avp $d %{buildroot}/%{gopath}/src/%{go_import_path}/
done

%check
GOPATH=%{buildroot}/%{gopath} go test %{go_import_path}/html
# [...]

%files devel
%defattr(-,root,root,-)
%doc AUTHORS CONTRIBUTORS LICENSE PATENTS README
%doc README-webkit
%dir %attr(755,root,root) %{gopath}/src/%{go_import_path}
%dir %attr(755,root,root) %{gopath}/src/%{go_import_path}/dict
%dir %attr(755,root,root) %{gopath}/src/%{go_import_path}/html
# [...]
%{gopath}/src/%{go_import_path}/dict/*.go
%{gopath}/src/%{go_import_path}/html/*.go
# [...]

%changelog
* Fri Jul 11 2014 Vincent Batts <vbatts@fedoraproject.org> - 0-0.15.hg84a4013f96e0
- don't fail on ipv6 test bz1056185
# [...]


Packaging a binary

%global commit      63fe64c471e7d76be96a625350468dfc65c06c31
%global shortcommit %(c=%{commit}; echo ${c:0:7})

Name:           example-app
Version:        1.0.0
Release:        6%{?dist}
Summary:        This application is an example for the golang binary RPM spec
License:        ASL 2.0 
URL:            http://www.example-app.io
Source0:        https://github.com/example/app/archive/v%{version}.tar.gz
Source1:        example-app.service
Source2:        example-app.sysconfig

BuildRequires:  gcc

BuildRequires:  golang >= 1.2-7

# pull in golang libraries by explicit import path, inside the meta golang()
BuildRequires:  golang(github.com/gorilla/mux) >= 0-0.13
[...]

%description
# include your full description of the application here.

%prep
%setup -q -n example-app-%{version}

# many golang binaries are "vendoring" (bundling) sources, so remove them. Those dependencies need to be packaged independently.
rm -rf vendor

%build
# set up temporary build gopath, and put our directory there
mkdir -p ./_build/src/github.com/example
ln -s $(pwd) ./_build/src/github.com/example/app

export GOPATH=$(pwd)/_build:%{gopath}
go build -o example-app .

%install
install -d %{buildroot}%{_bindir}
install -p -m 0755 ./example-app %{buildroot}%{_bindir}/example-app

%files
%defattr(-,root,root,-)
%doc AUTHORS CHANGELOG.md CONTRIBUTING.md FIXME LICENSE MAINTAINERS NOTICE README.md
%{_bindir}/example-app

%changelog
* Tue Jul 01 2014 Jill User <jill.user@fedoraproject.org> - 1.0.0-6
- package the example-app

Thanks

These guidelines are Fedora-specific but are intended to match Debian practice where that is reasonable.

Discussion

See Talk:PackagingDrafts/Go for discussion.