Ports from github

[Matthew Seaman]

On 24/05/2020 03:39, Montgomery-Smith, Stephen wrote:
> Is there a "howto" that explains how to build a port from a project that
> is on github?  The FreeBSD porters handbook seems to assume a lot of
> knowledge is already understood.

Well, the only thing "different" about porting something from Github, as
opposed to any other distfile location, occurs in the 'fetch' phase --
actually pulling down the distfiles.  Once you've got past that, the
rest of building the port is exactly the same as it would be if you got
the distfiles from anywhere else.

So, minimally a Github using port will set the following variables:

PORTNAME= someport
PORTVERSION= 1.2.3
DISTVERSIONPREFIX= v
USE_GITHUB= yes
GH_ACCOUNT= someone

and it won't set:

MASTER_SITES
DISTFILES

An example from amongst the ports I maintain is database/pg_citus:

PORTNAME=       citus
PORTVERSION=    9.3.0
DISTVERSIONPREFIX=      v

USE_GITHUB=     yes
GH_ACCOUNT=     citusdata

From this, the ports can work out that the Github project is:

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

If you go to that project URL and look at their releases page:

  https://github.com/citusdata/citus/releases

you'll see the list of versions like so:

  v9.3.0
  ^ ^^^^
  | PORTVERSION
  DISTVERSIONPREFIX

That's all that is needed for this port to be able to download a tarball
of the project's sources.

Now, this is about the simplest possible example of what you might need
when pulling sources from Github, and this pattern probably accounts for
the largest fraction of the Github-using ports in the tree.

Beyond that, the next largest fraction will be projects where the
PORTNAME doesn't quite match the GH project URL, or their release tags
specify the version as (eg.) v1_2_3 rather than v1.2.3 -- all just minor
tweaks so the ports can put together the right URL to pull the distfiles
from.

Beyond that is where it can start to get pretty complicated though.
Sometimes a project doesn't create formal releases, or you want to pull
down a code base a few commits beyond the latest release, or the project
uses a lot of different sub-projects linked into its tree from other
github repositories.  Certain programs written in go are pretty
notorious for this, and can end up with huge lists of distfiles.  See
www/gitlab-pages for an example.

Finally, and only if you really want to blow your mind: throw in an
unreasonable number of port options to the mix.  www/nginx is the
pinnacle (or is it nadir?) here.

In general I'd offer the following three pieces of advice when trying to
get to grips with a new area in porting:

  * Find a good example of a port that does something similar and
    blatantly copy it[*].
  * Keep things as simple as possible (but no simpler).
  * Work iteratively: start with something close, and make simple
    minimal changes, one at a time and testing as you go, to get it spot
    on.

[*] The trick here is not to copy a port that does things sub-optimally.
 Sods law has it that if there's a dozen good examples you might copy,
and one bad one, it's the bad one that will seem like the most enticing
prospect.

If in doubt, ask.  It helps if you can provide a concrete example or a
specific context for your questions, and indeed, trying to formulate
such a question will often lead you directly to the answer yourself.

	Cheers,

	Matthew





-------------- next part --------------
A non-text attachment was scrubbed...
Name: signature.asc
Type: application/pgp-signature
Size: 963 bytes
Desc: OpenPGP digital signature
URL: <http://lists.freebsd.org/pipermail/freebsd-ports/attachments/20200524/129d78b1/attachment.sig>