"port upgrade" error message usability

Ryan Schmidt ryandesign at macports.org
Sun Jan 30 10:12:57 UTC 2022

On Jan 30, 2022, at 03:30, Andrew Janke wrote:

> On 1/30/22 4:04 AM, Ryan Schmidt wrote:
>> On Jan 30, 2022, at 02:24, Andrew Janke wrote:
>>> Hi, MacPorts developers,
>>> Long-time Homebrew user and recent MacPorts convert here.
>> Welcome! I'm interested in your impressions of MacPorts as a Homebrew user and if you have any suggestions for changes we can make to make your MacPorts experience more enjoyable.
> Thanks!
> I've been lurking on MacPorts for a while, and my general impressions are that MacPorts is the more "pro" product: more functionality and customizability, and better commitment to back-compatibility and long-term support. But the tools are less user-friendly and less "fun" (where's my beer emojis?), and portfiles are a bit harder to work with that Homebrew formula files (not without reason, from what I can tell). (I'm not just a Homebrew user; I was one of the core Homebrew maintainers for a few years.)
> I'm the primary maintainer for Octave.app (https://octave-app.org/), a "native Mac app" distribution of GNU Octave (https://www.gnu.org/software/octave/index), and I'm getting more in to MacPorts recently because Octave.app is currently built on Homebrew and I'm considering migrating it to MacPorts, because I want to continue supporting macOS 10.14 with it. (10.15+ breaks some apps, so I want to be able to support the diehards (like me) who are sticking with 10.14).)
>> All MacPorts commands operate on a Portfile in the current directory if you don't specify what ports to operate on.
> This was the "implicit knowledge" I was lacking here.

There is admittedly a lot to know, and several different places where things are documented (guide, wiki, manpages). This bit is documented in the first paragraph of "man port":

       port is designed to operate on individual or multiple ports,
       optionally within a single call, based on the requested action. If
       no action is specified the port command enters shell mode, in which
       commands are read via stdin. If no portdir or portname is specified
       for an action, the current working directory is assumed. Batch
       commands may be passed via a cmdfile. Port options are passed as
       key=value pairs and take precedence over individual portname
       options as specified in its Portfile and system-wide settings.

>> "Could not find Portfile in /Users/janke" isn't too unclear, is it?
> IMHO, that would be a nice improvement:

My point was that it already prints that. So I guess you're saying it would be clearer if we printed only that and not the other information?

Maybe we can special-case the situation where no ports are specified and the currently directory doesn't contain a Portfile and print something more helpful, like:

Error: No ports were specified and the current directory /foo/bar does not contain a Portfile

> when I'm working with the `port` command in a shell, I'm thinking in terms of port names and maybe local files; a local filesystem path is more comprehensible to me than a URL (even if it's a "file://..." URL; in theory I know what that means, but maybe not all users will, and just seeing it in URL instead of local file paths kinda throws me off, because that makes me think it's doing some networking thing that I don't understand).

I agree that the appearance of a URL there is a little unexpected. MacPorts does however have the seldom-used capability to act on a full URL, even a network URL, as in this nonsensical example:

$ port info http://www.apple.com
--->  Fetching port http://www.apple.com
Can't map the URL 'http://www.apple.com' to a port description file ("Port extract failed: tar: Error opening archive: Unrecognized archive format").
Please verify that the directory and portfile syntax are correct.
Error: Can't open URL 'http://www.apple.com' as a port
Error: Improper expression syntax while processing parameters

I'm actually not sure what kind of file MacPorts is expecting to find at such a URL. I tried just a Portfile and a gzip-compressed tarball containing a Portfile and files directory; neither worked. Maybe this feature just doesn't even work anymore. I'm not sure why MacPorts ever had this capability. MacPorts was probably designed in the early days to work on any kind of URL, and to transform local port names into file URLs internally, with the assumption that this flexibility might prove useful at some point, but I think it ended up not being needed.

>> There's no reason to suspect that a user who doesn't specify a port meant to specify the pseudoport "outdated". I think it might not necessarily even be known at the time that the list of specified ports is processed which command that set of ports will be handed to.
> Fair enough. That might be an assumption I'm bringing with me from the Homebrew world.

What I mean is: the user might have typed "port info" or "port uninstall" or any other port command. "outdated" is not a reasonable default (or reasonable suggested value) for each of the commands. If you're saying that different port commands should have different suggested values when no port is specified, then we would have to decide what each of those would be and see if the code that prints the error message has access to the information about which command is being run.

More information about the macports-dev mailing list