Notes on running ProfStef, the "quick-start" tutorial for Pharo Smalltalk

Pharo-ProfStef-Notes.txt

Notes on running ProfStef, the "quick-start" tutorial for Pharo Smalltalk:

Where to find ProfStef

'ProfStef' is a 15-minute introduction to Pharo that's built into every Pharo 
image template.  ProfStef will guide you through a "hands-on" tutorial of the 
entire Pharo syntax in 29 steps, using the Pharo IDE.  To run it, you need to 
open a Pharo image; start by downloading and installing the Pharo Launcher app 
for your host platform from https://pharo.org, then clone any template to make 
a new image.  When you launch your new image the first time, it will have the 
"Welcome to Pharo" window already open.  That window has some columns on the 
left side; one of them is "Learn Pharo".  On that page is a link to "ProfStef". 
Click the link to open ProfStef and read & follow the prompts to get started.
However, you'll gain some valuable insights by reading this gist first!

Commandline Evaluation is by 'Select + Do It'

One thing that tends to trip people up when getting started with Pharo is this: 
To execute/evaluate something, you have to select text with the mouse, then 
right-click and pick "Do it" (or "Print it" or "Inspect it") from the context 
menu in order to have Pharo evaluate something.  Typing 'Enter' just gives you
a new line, like typing source code into an editor.  (You can also select text 
with the usual keyboard combinations of 'Shift' and the arrow keys, and/or use 
Ctrl-D, Ctrl-P, or Ctrl-I.)  

You won't get far if you don't realize this!

Pharo is unusual in this respect, but it's necessary in order to give you more 
choices regarding how you want to see the results; it's just something to get 
used to...  One cool advantage of doing things this way: it not only allows you 
to evaluate something you just typed, it also allows you to evaluate any text 
you have access to anywhere in the entire system -- any window or browser! It 
also makes it easy to re-evaluate something later (just select it again and 
evaluate it again, which really helps debugging).

Worried about Platform Issues?

Whether you're using Windows, Mac, or Linux isn't important, because Pharo's 
code is platform-independent.  You can move a Pharo image (essentially a 
container) to another host platform without having to adapt it, recompile & 
link it, etc. The part that's specific to your host is the language virtual 
machine that your image runs on.  If you use Pharo Launcher to manage your 
set of images, it automatically selects & installs the type of VM that matches 
the platform you're using.

The first time you clone a particular image template in Pharo Launcher and 
launch it, it will automatically download the appropriate VM for your platform. 
After that, the particular VM you're using becomes transparent.  Any code you 
write will work on any platform that needs to run it (with some additional 
considerations for using the Foreign Function Interface library, to deal with 
*its* platform dependencies, but much of that is automatic, too).

Using "Print it" within ProfStef:  

When you select "Print it" from the right-click menu in a ProfStef window (or 
press Ctrl-P), Pharo will evaluate the highlighted text, then paste the results 
in the ProfStef window for you.  In general this can be a convenience, but in 
ProfStef it will usually have the undesirable effect of making expressions that 
follow a few lines later look like a syntax error.  (The parser built into 
Pharo runs "behind the scenes" and will 'look ahead', turning syntax errors red 
to let you know there's a problem.)

But in the case of the ProfStef tutorial, this isn't actually a real problem, 
because you're not writing or evaluating an entire method; instead, you're only 
selecting one or two lines and evaluating them independently.  Nevertheless, 
Pharo isn't aware of this and makes it looks like something's not right...  
(Which is not a good thing for an introductory tutorial!)

The best thing to do in this case is to just press the "Delete" key to delete 
the text that gets inserted in the window, eliminating any syntax issues. 
(Note that doing this isn't actually *required*.)  Personally, I don't like 
seeing lines of code turning red, so this, to me, is a tutorial bug.  It 
causes confusion, so it really shouldn't do this, and given that Pharo is so 
malleable, the underlying code could be changed to keep this from happening.

Another potential tripping point in ProfStef...  

Lesson 28 is where you'll run a method that has an intentional bug in it (a 
divide by zero).  Executing "ProfStef next" to reach this method will cause 
Pharo to execute the method, then trap the error and cause the debugger to 
open its window.  This is just what Pharo is supposed to do on encountering
buggy code (and is the point of this lesson), but it may not be clear in the 
tutorial what you should do next -- and you can't go backwards at this point 
to re-read the instructions!

The debugger window has three panes: At the top is a stack trace, listing the 
class/method call chain; the middle pane shows the source code of the method 
that's highlighted in the stack trace; the bottom pane is an inspector on the 
variable state at that point in the stack trace.  The inspector allows you to 
examine objects and their values in the context of the method code displayed 
immediately above.

The code that will be shown in the debugger window when it first opens is the 
source code for the method on the top of the stack, which is the method that 
actually implements throwing the error (i.e., it's the default error handler).  
But that's not where the problem exists in the tutorial!  And this is likely 
not going to be clear to anyone seeing the Pharo debugger for the first time.

The proper strategy is to click down through the stack listing until you reach 
the method that has the divide-by-zero code in it (which in this case is the 
second method call from the top).  The source code for this "divide by zero" 
method contains comments with tutorial instructions for what to do next; you 
need to read them carefully and follow their instructions -- they'll tell you
how to use the debugger to fix the buggy source code, save the changes, and 
then continue running ProfStef.

What Lesson 28 illustrates is one of the best tools in Pharo: You can modify 
the buggy code of an application while it's still running (editing the code in 
the debugger itself), save the fixes, then tell the debugger to resume running, 
all without the typical abort/edit/recompile/rerun cycle that forces you to 
restart everything from the beginning.  You can sweep through your code, going 
from bug to bug, fixing things as you go, and sometimes get everything working 
in one pass!  (Some people prefer to develop applications this way!)

Speaking of going backwards, you can make ProfStef go back a page at any time 
by evaluating 'ProfStef previous'.