Bug 227600
| Summary: | porter's handbook: use of distinfo | ||
|---|---|---|---|
| Product: | Ports & Packages | Reporter: | freebsd |
| Component: | Individual Port(s) | Assignee: | Port Management Team <portmgr> |
| Status: | Open --- | ||
| Severity: | Affects Some People | CC: | 0mp, diizzy, linimon, lwhsu, pi, portmaster |
| Priority: | --- | Keywords: | feature, needs-patch |
| Version: | Latest | ||
| Hardware: | Any | ||
| OS: | Any | ||
|
Description
freebsd
2018-04-18 03:24:44 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. 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. (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? (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. I don't think I can help here. 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 ? (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. (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 Section 4.1 explains how things work when you build a port, the different phases and all, it is basically giving you the steps the framework goes through if you run `make install`. It is absolutely not about changing things. `make fetch` will only ever fetch a file if it is present in the distinfo file. If you change stuff, you should read section 3, and especially 3.3 is what you should read. I do not think changing 4.1 is a good idea. We should probably just have a chapter on how to update a port. We already have a chapter on how to update a port. (In reply to Mathieu Arnold from comment #11) Right, we do have "Chapter 11. Upgrading a Port" if that's what you are referring to but I feel that it does not explain the process of upgrading a port (apparently, the "make makesum" step is not too obvious). Anything we need to track/do regarding this report? |
