====== Simple Use of Github for Distfiles ======

===== What using GitHub affects =====

The only part of building a port that using [[/GitHub|GitHub]] affects is the //fetch// phase -- actually pulling down the distribution files from [[/GitHub|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.

===== What is the simple case? =====

The %%FreeBSD%% ports can not only use [[https://github.com|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|GitHub]]-related settings available to use in a port -- all comprehensively documented in the [[https://www.freebsd.org/doc/en_US.ISO8859-1/books/porters-handbook/makefile-distfiles.html#makefile-master_sites-github|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|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|GitHub]] projects match this pattern, and consequently this is the most popular pattern you will find for [[/GitHub|GitHub]]-using ports.

===== Makefile Variables =====

You will need to set the following in your port:

^ Variable ^ Value ^
| ''%%PORTNAME%%'' | //projectname// |
| ''%%PORTVERSION%%'' | //1.2.3// |
| ''%%DISTVERSIONPREFIX%%'' | Typically ''%%v%%'' |
| ''%%USE_GITHUB%%'' | ''%%yes%%'' |
| ''%%GH_ACCOUNT%%'' | //accountname// |

You will not need either of:

| ''%%MASTER_SITES%%'' |
| ''%%DISTFILES%%'' |

==== An Example ====

Let us consider the [[https://github.com/freebsd/freebsd-ports/blob/master/databases/pg_citus|databases/pg_citus]] port as an example of the 'simple' pattern.

<code>
PORTNAME=	citus
PORTVERSION=	9.3.0
DISTVERSIONPREFIX=	v
CATEGORIES=	databases
PKGNAMEPREFIX=	pg_

[...]

USE_GITHUB=	yes
GH_ACCOUNT=	citusdata
</code>

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

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

v9.3.0
^^
| PORTVERSION 
DISTVERSIONPREFIX
</code>

===== Slightly Less Simple Ports =====

The next largest grouping of [[/GitHub|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 Complicated Ports =====

More advanced [[/GitHub|GitHub]] usage usually involves pulling down more than one distfile from [[/GitHub|GitHub]], in many cases because the upstream authors have used [[https://git-scm.com/book/en/v2/Git-Tools-Submodules|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 [[https://github.com/freebsd/freebsd-ports/blob/master/www/gitlab-pages/Makefile|www/gitlab-pages]] port is an example.

Finally there is perhaps the zenith (or maybe nadir) of complexity: [[https://github.com/freebsd/freebsd-ports/blob/master/www/nginx/Makefile.extmod|www/nginx]] which mixes not only numerous different distfiles pulled from projects all over [[/GitHub|GitHub]], but uses ''%%OPTIONS%%'' to make compiling most of the available extensions configurable.

===== If you're still unsure =====

  * 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.

===== Acknowledgements =====

This page is based on a reply I made in a thread on the [[https://lists.freebsd.org/pipermail/freebsd-ports/2020-May/118607.html|freebsd-ports]] mailing list.  Thanks to Adam Weinberger for suggesting I write this Wiki entry.

----

[[/CategoryPorts]]