search

windelbouwman / ppci

A compiler for ARM, X86, MSP430, xtensa and more implemented in pure Python
https://ppci.readthedocs.io/en/latest/
BSD 2-Clause "Simplified" License
337 stars 36 forks source link

docs: Clarify "python" vs "python3" #14

Closed pfalcon closed 4 years ago

pfalcon commented 5 years ago

It looks like PPCI requires Python3, which is great. It looks like "python -m ppci" syntax is used somewhere in the docs (as suggested in https://github.com/windelbouwman/ppci-mirror/issues/11), which is also great: https://ppci.readthedocs.io/en/latest/reference/lang/java.html#compile-java-ahead-of-time

However, that uses exactly python, and for most users nowadays that will lead to stack trace ending with:

AssertionError: Needs to be run in python version 3.x

Not exactly user friendly (especially for people not familiar with Python, and #11 suggests to keep those in mind).

So, suggested to use python3 consistently in the commands everywhere.

pfalcon commented 4 years ago

@windelbouwman: Do you agree that this makes sense, should I make such a change if see a bare "python" command usage?

windelbouwman commented 4 years ago

Hmm, I don't know, since python2 is officially dead (for some hours ;)), we might assume the default is python3 now? I propose to leave the docs as it is, and improve the error message, which I agree is poor, and should be more explaining.

windelbouwman commented 4 years ago

I added a more explanatory error message 726dea002d8d54afcf2aa966a130e55fbaac1294 do you mean something like this?

pfalcon commented 4 years ago

Hmm, I don't know, since python2 is officially dead (for some hours ;)), we might assume the default is python3 now?

I personally don't think we can. While "official" deadline has been passed, my system still has "python" pointing to "python2". And it's the same for millions of other users, for months to come, and for sizable numbers still, for years to come. And I expect the echo of confusion to roll around for the next 10-20 years. While "python3" is already there, will be there, and even was there all the time.

I propose to leave the docs as it is, and improve the error message, which I agree is poor, and should be more explaining.

Ok, but then I'd suggest to keep this ticket open, and revisit again in some time.

pfalcon commented 4 years ago

I added a more explanatory error message 726dea0 do you mean something like this?

Yes, that's detailed enough, thanks.

pfalcon commented 4 years ago

Ok, in the name of keeping set of open tickets (more) manageable, let's close this ticket (in preference of more "meta" tickets). I for one got that preference is to use bare "python", and followed in e.g. https://github.com/windelbouwman/ppci-mirror/pull/39/files#diff-112623563404e927d73b171234939b31R1 to be consistent within the project, even though I myself would use "pyhon3".

We can reopen if there will be actual user reports of confusion.