Bug 227600 - porter's handbook: use of distinfo
Summary: porter's handbook: use of distinfo
Status: New
Alias: None
Product: Ports & Packages
Classification: Unclassified
Component: Individual Port(s) (show other bugs)
Version: Latest
Hardware: Any Any
: --- Affects Some People
Assignee: freebsd-ports-bugs mailing list
URL:
Keywords: feature, needs-patch
Depends on:
Blocks:
 
Reported: 2018-04-18 03:24 UTC by freebsd
Modified: 2018-07-03 04:52 UTC (History)
4 users (show)

See Also:


Attachments

Note You need to log in before you can comment on or make changes to this bug.
Description freebsd 2018-04-18 03:24:44 UTC
If you have a distinfo file that does not match the tarball you are attempting to fetch, the ports mechanism fails fetching the tarball with the following misleading message:

=> nufraw-0.41.tar.gz is not in /hd2/home/garya/Computing/ports/graphics/nufraw/distinfo.
=> Either /hd2/home/garya/Computing/ports/graphics/nufraw/distinfo is out of date, or
=> nufraw-0.41.tar.gz is spelled incorrectly.

In the general description of the fetch phase, it should mention that if a distinfo file is present, it *must* match the tarball being fetched.  I had the impression distinfo was only used after the tarball was fetched, during the extract phase.  When upgrading a port it's easy to forget there is already a distinfo lying around.
Comment 1 Tobias Kortkamp freebsd_committer 2018-05-30 06:50:31 UTC
(In reply to freebsd from comment #0)
How is the message misleading?  It clearly says that distinfo is out of date
and doesn't contain the tarball for the new version which implies that it needs
updating.

> When upgrading a port it's easy to forget there is already a distinfo lying around.

How so?  distinfo will automatically be updated when you run `make makesum`
which you must do anyway after bumping a port's version.
Comment 2 freebsd 2018-06-03 19:49:22 UTC
You're correct in that the message clearly states that distinfo is out of date.
However, if one is updating a port, one needs to do the fetch before one can run make makesum to produce an up-to-date version of distinfo.  But one can't do the fetch if a distinfo is lying around.  A user can easily think "I know it's out of date, I'm trying to fetch the file and generate an up to date version!"

The issue is not with the failure message; the issue is with the general description of the fetch phase in the Porter's Handbook.  It would be helpful if the Handbook indicated the fetch itself will not succeed if a distinfo is lying around which does not match the file being fetched.  It is not at all clear that a mis-matched distinfo will cause a fetch to fail, particularly since distinfo is not required to be there to perform a fetch, and cannot be generated until after the fetch is done.

One could also make the message a little clearer, such as:

=> Either /hd2/home/garya/Computing/ports/graphics/nufraw/distinfo is out of date, or
=> nufraw-0.41.tar.gz is spelled incorrectly.
=> If distinfo is out of date, delete it before attempting to fetch.
Comment 3 Tobias Kortkamp freebsd_committer 2018-06-04 07:51:19 UTC
(In reply to freebsd from comment #2)

> However, if one is updating a port, one needs to do the fetch before one can
> run make makesum to produce an up-to-date version of distinfo.  But one can't
> do the fetch if a distinfo is lying around. 

This is incorrect.  Let me try and clarify.

If you change PORTVERSION/DISTNAME/DISTFILES/...  and then run `make
makesum` the new distfiles are fetched first and distinfo is replaced
with their checksums irregardless of what was in distinfo before.
You do *not* have to run `make fetch` first.

'makesum' is the target you should use as a maintainer not 'fetch'.

Can you add a link to the section of the Porter's Handbook that you find
problematic?
Comment 4 freebsd 2018-06-05 14:45:52 UTC
(In reply to Tobias Kortkamp from comment #3)

>> However, if one is updating a port, one needs to do the fetch before one can
>> run make makesum to produce an up-to-date version of distinfo.  But one can't
>> do the fetch if a distinfo is lying around. 
> 
> This is incorrect.  Let me try and clarify.
> 
> If you change PORTVERSION/DISTNAME/DISTFILES/...  and then run `make
> makesum` the new distfiles are fetched first and distinfo is replaced
> with their checksums irregardless of what was in distinfo before.
> You do *not* have to run `make fetch` first.
> 
> 'makesum' is the target you should use as a maintainer not 'fetch'.
> 
> Can you add a link to the section of the Porter's Handbook that you find
> problematic?

Ok, so what you're saying is one should not stepwise run make fetch and
then make makesum; that's not clear from section 4.1, "How things work".
3.3 on building a new port implies the porter is responsible for updating
distinfo by running make makesum after obtaining the source.

Section 4.1 #1 is the part which could be expanded to explain more of how
things work.
Comment 5 Tobias Kortkamp freebsd_committer 2018-06-18 22:56:04 UTC
I don't think I can help here.
Comment 6 Kurt Jaeger freebsd_committer 2018-06-29 18:08:53 UTC
section 3.3 explains for quick ports, how to generate the distinfo.

section 4.1 is verbose, but does not really mention make makesum.

section 4.2 says to get the source somehow, but doesn't mention make makesum, either.

If I write a new port, I normally use

cd /usr/ports/category
port create <newport>

using ports-mgmt/porttools. Then I try to get the skeleton port Makefile
to fetch it's distfiles. If that works, I can use make makesum.

If we replace 4.2 with a rough description like that above, would that
be helpful ? Is it allowed to depend on ports-mgmt/porttools in the
porters handbook or is it frowned upon ?
Comment 7 freebsd 2018-06-29 23:38:31 UTC
(In reply to Kurt Jaeger from comment #6)
I don't think it's appropriate to rely on a particular ports-mgmt tool in the explanation, particularly given there are different tools in use by different people.

In any case, the problem is not so much creating a new port from scratch but tweaking an existing port.  As explained in comments 3 & 4, one should be using the "makesum" target rather than the "fetch" target when trying to fetch when the port skeleton (e.g. makefile and distinfo) is inconsistent.

Perhaps 4.1 #1 could additionally say something like 

Note: If executing port build stages individually, the fetch target will fail if distinfo exists and does not match the distfile to be fetched.  In this case, the makesum target should be run instead.  It will fetch the new distfile first, then replace distinfo with the appropriate checksum regardless of what was in distinfo before.
Comment 8 Chris Hutchinson 2018-07-03 04:52:23 UTC
(In reply to freebsd from comment #7)
> (In reply to Kurt Jaeger from comment #6)
> I don't think it's appropriate to rely on a particular ports-mgmt tool in
> the explanation, particularly given there are different tools in use by
> different people.
> 
> In any case, the problem is not so much creating a new port from scratch but
> tweaking an existing port.  As explained in comments 3 & 4, one should be
> using the "makesum" target rather than the "fetch" target when trying to
> fetch when the port skeleton (e.g. makefile and distinfo) is inconsistent.
> 
> Perhaps 4.1 #1 could additionally say something like 
> 
> Note: If executing port build stages individually, the fetch target will
> fail if distinfo exists and does not match the distfile to be fetched.  In
> this case, the makesum target should be run instead.  It will fetch the new
> distfile first, then replace distinfo with the appropriate checksum
> regardless of what was in distinfo before.

+1 :-)

--Chris