From owner-freebsd-ports@freebsd.org Mon May 25 02:56:14 2020 Return-Path: Delivered-To: freebsd-ports@mailman.nyi.freebsd.org Received: from mx1.freebsd.org (mx1.freebsd.org [IPv6:2610:1c1:1:606c::19:1]) by mailman.nyi.freebsd.org (Postfix) with ESMTP id CDF142F17C5 for ; Mon, 25 May 2020 02:56:14 +0000 (UTC) (envelope-from adamw@adamw.org) Received: from mail-wm1-x329.google.com (mail-wm1-x329.google.com [IPv6:2a00:1450:4864:20::329]) (using TLSv1.3 with cipher TLS_AES_128_GCM_SHA256 (128/128 bits) key-exchange X25519 server-signature RSA-PSS (4096 bits) server-digest SHA256 client-signature RSA-PSS (2048 bits) client-digest SHA256) (Client CN "smtp.gmail.com", Issuer "GTS CA 1O1" (verified OK)) by mx1.freebsd.org (Postfix) with ESMTPS id 49VhYn4xj4z48PY for ; Mon, 25 May 2020 02:56:13 +0000 (UTC) (envelope-from adamw@adamw.org) Received: by mail-wm1-x329.google.com with SMTP id u188so15420255wmu.1 for ; Sun, 24 May 2020 19:56:13 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=adamw-org.20150623.gappssmtp.com; s=20150623; h=mime-version:references:in-reply-to:from:date:message-id:subject:to :cc; bh=YWl2Ynt2V+vvNDeWnRfB1sYCoaqHIVgJXHZAQcIUGNE=; b=lwpPoxh+4Yv2nyh05VhbKTV30T77eo9fqcs1sITC1EyRXkxrO2/7jw9VRTA7RK3gz1 1NqNfQswSnNqxAfYxxo5qsh3DCtkqgfitdV2SqZnDnUkNRKuqhdsc6qUsS7momhzOFeU gOcxtMZ4dMaTje7ewSWwrrvPfYP7/Dj6wozua7Tqfxhk89GxLcIaRvRwkWL6BDDD1/id O4pH9H8/seOqCU/usUxpihnDq7mLFq/wfKvqONPBFp/jYJjLSI2wlpw/e35xfckGULWL R7cFmT+rBc5wUnnk9YKlJne35yeEvSM9JDgSRPDCgjL0qG4zCZBXncw1hYrFYvRKdr/M FHuw== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20161025; h=x-gm-message-state:mime-version:references:in-reply-to:from:date :message-id:subject:to:cc; bh=YWl2Ynt2V+vvNDeWnRfB1sYCoaqHIVgJXHZAQcIUGNE=; b=fzJ9zEOnPIN3FKHATkOUNIY7f5ipt4n1qHUw7xCnMAcF5mQAVJc+nFLQ3xK+iD5EjH glf+BUNlTY7atxMU54IaTr/Gw/zIhn1kxAg1xrhAAUIEbXz+1e5Q/RjU0hVD3w27hTct tcCt3v7K4hnB+KsKsIj7hu4wqJPlMlM4m7s/ITk+cUhe63L1i880kFsfmFzel+XYSPtv iiwdOIL8jO3S/cFgVzoa2Gvio7L6JApneH8d36niGwsxvHrcE11xfGERF3UvEncR03Lc Pf/WJ5wUd6QjxWxHSm3EmaMBNSdsfvLANKDpJrRsVJkYbieQ2Ajo7fDWVxoAms1irfqy ehBA== X-Gm-Message-State: AOAM530QuequpJuNJ7K1gkkFwSVRVCXvneO5hu6PSCKPrCHxcQq4LLWg 5gmyhJJWKufWiDutD/2meIo+DOIzV8Op5Jh+zD7Ckw== X-Google-Smtp-Source: ABdhPJwf8UMyWc256mKCvZl76a32fTnRAw/a4bUW6jvVFPTDA86oOh62ZNKHgR8PKlNNoeqmkLQInEns5ejmd2M5TaY= X-Received: by 2002:a1c:b656:: with SMTP id g83mr4913520wmf.151.1590375371216; Sun, 24 May 2020 19:56:11 -0700 (PDT) MIME-Version: 1.0 References: <3c6205ea-e589-769b-7b12-ee7e6d3fa8ff@missouri.edu> <5bb5cc69-ef90-2285-324f-58e09399d3ef@FreeBSD.org> In-Reply-To: <5bb5cc69-ef90-2285-324f-58e09399d3ef@FreeBSD.org> From: Adam Weinberger Date: Sun, 24 May 2020 20:55:55 -0600 Message-ID: Subject: Re: Ports from github To: Matthew Seaman Cc: FreeBSD Ports Content-Type: text/plain; charset="UTF-8" X-Rspamd-Queue-Id: 49VhYn4xj4z48PY X-Spamd-Bar: --- Authentication-Results: mx1.freebsd.org; dkim=pass header.d=adamw-org.20150623.gappssmtp.com header.s=20150623 header.b=lwpPoxh+; dmarc=none; spf=pass (mx1.freebsd.org: domain of adamw@adamw.org designates 2a00:1450:4864:20::329 as permitted sender) smtp.mailfrom=adamw@adamw.org X-Spamd-Result: default: False [-3.23 / 15.00]; ARC_NA(0.00)[]; NEURAL_HAM_MEDIUM(-1.01)[-1.006]; R_DKIM_ALLOW(-0.20)[adamw-org.20150623.gappssmtp.com:s=20150623]; FROM_HAS_DN(0.00)[]; R_SPF_ALLOW(-0.20)[+ip6:2a00:1450:4000::/36]; NEURAL_HAM_LONG(-1.01)[-1.007]; MIME_GOOD(-0.10)[text/plain]; PREVIOUSLY_DELIVERED(0.00)[freebsd-ports@freebsd.org]; DMARC_NA(0.00)[adamw.org]; TO_MATCH_ENVRCPT_SOME(0.00)[]; TO_DN_ALL(0.00)[]; DKIM_TRACE(0.00)[adamw-org.20150623.gappssmtp.com:+]; RCPT_COUNT_TWO(0.00)[2]; RCVD_IN_DNSWL_NONE(0.00)[2a00:1450:4864:20::329:from]; NEURAL_HAM_SHORT(-0.72)[-0.717]; FROM_EQ_ENVFROM(0.00)[]; MIME_TRACE(0.00)[0:+]; ASN(0.00)[asn:15169, ipnet:2a00:1450::/32, country:US]; RCVD_COUNT_TWO(0.00)[2]; RCVD_TLS_ALL(0.00)[] X-BeenThere: freebsd-ports@freebsd.org X-Mailman-Version: 2.1.33 Precedence: list List-Id: Porting software to FreeBSD List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Mon, 25 May 2020 02:56:14 -0000 On Sun, May 24, 2020 at 2:49 AM Matthew Seaman 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