Simple Use of Github for Distfiles

The only part of building a port that using GitHub affects is the fetch phase – actually pulling down the distribution files from GitHub. Once you've got all the necessary sources, the rest of building the port is exactly the same as it would be for using any other download location.

The FreeBSD ports can not only use GitHub, but can adapt to just about any of the weird and wonderful choices made by project authors. Consequently there are a lot of different GitHub-related settings available to use in a port – all comprehensively documented in the Porter's Handbook – but it can be confusing to the uninitiated.

If the following conditions are fulfilled, what you need to add to your port's Makefile is very simple:

• The project name on GitHub matches the name of the software
• The project makes numbered releases using git tags of the form v1.2.3
• There is no usage of git sub-modules

Very many GitHub projects match this pattern, and consequently this is the most popular pattern you will find for GitHub-using ports.

You will need to set the following in your port:

You will not need either of:

Let us consider the databases/pg_citus port as an example of the 'simple' pattern.

PORTNAME=	citus
PORTVERSION=	9.3.0
DISTVERSIONPREFIX=	v
CATEGORIES=	databases
PKGNAMEPREFIX=	pg_

[...]

USE_GITHUB=	yes
GH_ACCOUNT=	citusdata

The GitHub page for this project is https://github.com/citusdata/citus/ and if we examine their release page we can see that they use release tags incorporating the software version number, like v9.3.0. These correspond to the Makefile settings:

https://github.com/citusdata/citus/
                   ^         ^
                   |         PORTNAME
                   GH_ACCOUNT

v9.3.0
^^
| PORTVERSION 
DISTVERSIONPREFIX

The next largest grouping of GitHub-using ports are those where either the project naming or versioning doesn't quite match the simple pattern. If PORTNAME doesn't match the project name, override the defaults by setting GH_PROJECT to the project name. Similarly if the release tag isn't suitable as PORTVERSION you can frequently use DISTVERSION instead, in combination with DISTVERSIONPREFIX or (more rarely) DISTVERSIONSUFFIX. If that doesn't work, then you can set GH_TAGNAME directly.

Also still in the relatively simple category are the cases where upstream has committed an important bug fix but has not yet released a new version with the fix. One approach here (there are other alternatives) is to set GH_TAGNAME to the SHA hash of the commit fixing the problem, or the 6 character shortened hash.

More advanced GitHub usage usually involves pulling down more than one distfile from GitHub, in many cases because the upstream authors have used git submodules to pull in sources from a different project. Software written in the go language has a certain reputation for doing this extensively. In this case, you'ld use GH_TUPLE – the www/gitlab-pages port is an example.

Finally there is perhaps the zenith (or maybe nadir) of complexity: www/nginx which mixes not only numerous different distfiles pulled from projects all over GitHub, but uses OPTIONS to make compiling most of the available extensions configurable.

• Find a similar port and blatantly copy it
• Keep things as simple as possible (but no simpler) – just because you can do something doesn't mean you should
• Work iteratively: start with something close, and then make a series of small individual changes, testing as you go until you're spot on

It can be a bit of a pitfall when looking for something to base your port on that you end up copying a bad example. Prefer copying from ports that have a named maintainer, and that are being actively developed and are up-to-date with their upstream sources.

This page is based on a reply I made in a thread on the freebsd-ports mailing list. Thanks to Adam Weinberger for suggesting I write this Wiki entry.

CategoryPorts