User:Peter/Erlang Packaging Guidelines

THIS DOCUMENT IS WIP

This document seeks to document the conventions and customs surrounding the proper packaging of Erlang modules and applications in Fedora and EPEL. It does not intend to cover all situations, but to codify those practices which have served the Fedora Erlang community well.

Naming

Erlang packages should be named as erlang-something, expect for applications which can be named without the erlang- prefix (e.g. couchdb, rabbitmq-server, wings).

Building

Normally we're using Rebar to build packages. This is a de-facto standard tool for Erlang application building. Ususally it bundled along with the sources. Packager must ensure that we don't use bundled version. We recommend to use our build macros for building - %{erlang_compile} or less generic %{rebar_compile}. However some old software cannot be built with rebar - this is an issue which better be addressed.

Debug symbols / source installation / dialyzer

Erlang package should not install its original sources. Instead packages should ensure that it's built with +debug_info flag. It does NOT impact the runtime performance of the application at all (beam loader disregards debug symbols before loading to VM). Dialyzer requires either this debug info or original sources. if the package was built with our recommended macros (%{erlang_compile} or less generic %{rebar_compile}), then debug_info generated automatically.

If Erlang package doesn't contain any NIF-libraries, port-applications, or driver libraries, it must contain "%global debug_package %{nil}" directive to suppress building an empty debuginfo sub-package. Unfortunately this adds two additional rpmlint messages:

Auriga ~: rpmlint ~/rpmbuild/RPMS/x86_64/erlang-cowboy-2.0.0-0.1.pre.3.fc24.x86_64.rpm 
erlang-cowboy.x86_64: E: no-binary
erlang-cowboy.x86_64: W: only-non-binary-in-usr-lib
1 packages and 0 specfiles checked; 1 errors, 1 warnings.
Auriga ~: 

What rpmlint it trying to say here is that we're installing arch-independent data into arch-dependent library. That's expected. Just ignore these messages for now.

File Locations

Erlang packages should install theirselves to %{_erllibdir}/%{realname}-%{version}. A packager can use handy macro - %{erlang_appdir}. Big applications, such as ejabberd, rabbitmq-server, riak install their content somewhere else due to historical reasons.

Header files

Header files for erlang modules stored in ./include directory must be bundled with main package (not in a *-devel subpackage). They are used by system administrators sometimes right from the REPL console. Headers from ./src directory normally shouldn't be packaged, however sometimes it's required. In this case you have to package it but pconsider reporting upstream about wrong include files placement.

Dependencies

Packager has to build a list of BuildRequires by hand. RPM builds a list of Requires automatically (expect for few rare cases). Please take a look at the Koji build log. If you see messages like the following one, then the packager either missed one of the BuildRequires, or the package contains an error.

error: invalid dependency (bad format): ERROR: Cant find lager:error/2 while processing '/builddir/build/BUILDROOT/erlang-ibrowse-4.2.4-1.fc25.x86_64/usr/lib64/erlang/lib/ibrowse-4.2.4/ebin/ibrowse.beam'

In this case the package contains an error, which was addressed upstream already. But it also might mean that the packager forgot to add "BuildRequires: erlang-lager". We can't give packager a hint on what's missing, but in the case of this message the poackager should try running "sudo dnf provides "*/lager.beam" first.

An example of spec-file

A typical Erlang package's spec-file looks like that. We're using %{realname} and  %{upstream} macro in RPM scripts, so please fill it properly. Otherwise you have to do a lot of manual work.

%global realname foo
%global upstream bar
# Technically, we're noarch; but erlang whose directories we install into is not.
# This should be removed if a package contains NIF, or driver.
%global debug_package %{nil}


Name:		erlang-%{realname}
Version:	1.2.3
Release:	1%{?dist}
Summary:	Erlang library for doing cool things
Group:		Development/Libraries
License:	ASL 2.0
URL:		https://github.com/%{upstream}/%{realname}
Source0:	https://github.com/%{upstream}/%{realname}/archive/%{version}/%{realname}-%{version}.tar.gz
# Normally erlang-rebar install almost everything required for building. But sometimes some extra packages required.
# Please try building in Koji - you'll likely see some hints.
BuildRequires:	erlang-rebar

# If the package contains NIF-library or driver, then you have to include one or both of the following lines.
# This has to be done manually - we don't detect them automatically (for now).
%{?__erlang_nif_version:Requires: %{__erlang_nif_version}}
%{?__erlang_drv_version:Requires: %{__erlang_drv_version}}

# Normally RPM detects Erlang dependencies automatically (if built with erlang-rebar). However in some rare cases it can't be detected.
Requires: erlang-bar

%description
Erlang library for doing cool things.


%prep
%setup -q -n %{realname}-%{version}


%build
%{erlang_compile}


%install
%{erlang_install}

# Additionally install some cool stuff required to run application properly
cp -arv priv/ %{buildroot}%{erlang_appdir}/


%check
%{erlang_test}


%files
%license LICENSE.txt
%doc doc/ examples/ README.md
%{erlang_appdir}/


* Wed Mar 16 2016 Peter Lemenkov <lemenkov@gmail.com> - 1.2.3-1
- Initial build