as a newbie I'd like to learn from the tutorial how to make the debug output from Pony code

[vak]

As title says.
A simple example on how to configure and use the "debug" package is very welcome in tutorial

[SeanTAllen]

Thanks for starting this discussion @vak.

I'm dubious that this is "tutorial" material. Standard library packages should have their own documentation. We can raise the issue how "standard library discovery" might be suboptimal. However, filling the tutorial with standard library discovery material isn't a good idea in my mind.

We need more "how to debug pony programs" material but I'm not at all sure that is tutorial material. For me, the tutorial should be the basics of how Pony works. There can be other materials beyond the tutorial to address other issues. For example, we have Pony Patterns for cookbook type solutions. Having more information on the website on how to debug is something I plan on.

I'm interested in hearing from other Pony committers how they see the tutorial. When we had previously discussed I believe everyone was more or less in line with the above, but it would be good to revisit.

[jemc]

I can see both sides of the argument, and I'd be happy with either solution.

If we put the mention of the debug package somewhere else, I just think we should make sure that the "somewhere else" is easily discoverable for a user finishing the tutorial. I just looked at the tutorial again, and the "Where Next?" section we already have seems to fit that description.

[vak]

Sean, I see your point re "tutorial != std lib doc" and do like this.

OTOH, tutorial is the first source of Pony-knowledge today and i was as a newbie in a very simple situation like:

1. let's try to do something with those cool actors and print "hello, world" out of actor's behavior!
2. oops, printing is tied to env.out and i don't wan't to pass it all the time... no hints on printing from behavior in tutorial ==> ask Pony community! (it means each newcomer will ask this again!)
3. hm, if I was not able to print, maybe I won't be able to do a debug output?.. what says the tutorial, btw? nothing! ==> ask Pony community! (it means each newcomer will ask this also again!)

perhaps, this workflow of really simple questions could be optimized.

[SeanTAllen]

I feel like that is pointing towards a good FAQ to act as an overall guide.

Something along the lines of:

Where do I go to learn about "common thing folks are always asking about".

Which is my mind is a good use of a FAQ.

[vak]

One day Pony FAQ will be served by the stackoverflow (whether they like this or not), but before this some hand-made FAQ is rather needed. Anyway for developer it is very important that a question is quickly answered and it doesn't much matter if it is googling or CTRL-F
...well, ideally one entry-point for search, perhaps google :)

[Schwarzbaer]

At this point, the tutorial has a chapter on PonyTest. I think that that's something people would use after having already used debug output, implying that it should be in the tutorial (or that the PonyTest chapter shouldn't be).

[rhagenson]

I think debug and PonyTest should both be elsewhere for involving stdlib packages. However, until such time that there is a sufficient "elsewhere" to put this, I see no reason why a brief subsection on debug should not be added. I would put both of these under a revised header (changing "Testing) to be "Standard Library Examples" or something similar.

(Note that debug is already mentioned in the FAQ to show .create() versus .apply() and provides a link to the playground to run the code.)

[SeanTAllen]

I think that Debug should go in the compile-time options section discussed in another issue as it doesn't "work" unless you use the --debug compile-time option.

[rhagenson]

Permission to do a larger reformat of the content on appendices->compiler-args to promote the "most useful" options into subsections on the page? Otherwise I think adding use of Debug breaks the list up too much and would just require a reformat later to make it easier to read on first pass anyhow.

Basically:

Useful options

The most useful options are --debug, --path or just -p, ..., lib<directory>.

--debug

Skips the LLVM optimizations passes. This should not be mixed up with make config=debug, the default make configuration target. config=debug will create DWARF symbols, and add slower assertions to ponyc, but not to the generated binaries. For those, you can omit DWARF symbols with the --strip or -s option.

--debug allow enable use of the Debug actor for printf style debugging in a concurrent setting...

[SeanTAllen]

see issue #216 as it is related.

[SeanTAllen]

@rhagenson reformat away!

[rhagenson]

@SeanTAllen Got it.

[rhagenson]

Oh goodness, I never did the reformatting on this! Well only a year and a pandemic later for me to realize, eh? I will get that handled in the next few days and if not then Sync will be a moment of shame for me. 😅