Date: Sun, 24 May 2020 20:55:55 -0600 From: Adam Weinberger <adamw@adamw.org> To: Matthew Seaman <matthew@freebsd.org> Cc: FreeBSD Ports <freebsd-ports@freebsd.org> Subject: Re: Ports from github Message-ID: <CAP7rwcg0xf2n=MjuZGMEq8SU9hvYDKH7xawGUJtZZjOLSbQT8Q@mail.gmail.com> In-Reply-To: <5bb5cc69-ef90-2285-324f-58e09399d3ef@FreeBSD.org> References: <3c6205ea-e589-769b-7b12-ee7e6d3fa8ff@missouri.edu> <5bb5cc69-ef90-2285-324f-58e09399d3ef@FreeBSD.org>
next in thread | previous in thread | raw e-mail | index | archive | help
On Sun, May 24, 2020 at 2:49 AM Matthew Seaman <matthew@freebsd.org> wrote: > > 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 Thank you, Matthew! This is such gold. Could you maybe dump that into a page on the FreeBSD wiki? It'd be nice to have in the PHB but wiki would be a great start. Clear explanations like this are precisely what users need, and we need to start making them easier to find. # Adam -- Adam Weinberger adamw@adamw.org https://www.adamw.org
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?CAP7rwcg0xf2n=MjuZGMEq8SU9hvYDKH7xawGUJtZZjOLSbQT8Q>