guile-tutorial/up-and-running.skb

(section
 :title [Installing Guile and friends]

 (p [To use this tutorial, you'll need to install Guile onto your computer.
     If you don't have Guile yet,
       ,(ref :url [https://www.gnu.org/software/guile/download/]
             :text [go install it])
       then come back.])

 (p [You'll also need a text editor of some sort.
     You will want to use something that edits plain text, which means
       you don't want to use a word processor (so, no Libreoffice!),
       you want an editor to edit programs.
     If you already have an editor you like to use, great use that!
     Most Guile developers find that the best editor to use is
       ,(ref :url [https://www.gnu.org/software/emacs/]
             :text [Emacs])
       combined with
       ,(ref :url [http://www.nongnu.org/geiser/]
             :text [Geiser]),
       but if you aren't already an Emacs user, it can be overwhelming
       to learn multiple things at once.
     (If do learn to use Emacs with Geiser, there are even more
       fun things you can do than what we show here.
      ,(ref :url [http://www.nongnu.org/geiser/geiser_3.html#The-REPL]
            :text [See the Geiser manual])
        for more information!)
     If you've never programmed before, you might want to start with
       something simple, like ,(code [gedit]) for
       ,(ref :url [http://gnome.org/]
             :text [Gnome]).
     You can always set up a more advanced setup later!]))

(section
 :title [Running Guile]

 (p [So let's get started.
     Open a terminal and run ,(code [guile]).
     You should see something like this:])

 (frame
  (prog :line #f
        "GNU Guile 2.0.11
Copyright (C) 1995-2014 Free Software Foundation, Inc.

Guile comes with ABSOLUTELY NO WARRANTY; for details type `,show w'.
This program is free software, and you are welcome to redistribute it
under certain conditions; type `,show c' for details.

Enter `,help' for help.
scheme@(guile-user)> "))

 (p [Great!
     That means Guile is working just fine.
     Now let's try entering a small command.
     Type ,(code "(display \"Hello world!\\n)") and hit enter, like this:])

 (frame
  (prog :line #f
        "scheme@(guile-user)> (display \"Hello world!\\n\")
Hello world!
scheme@(guile-user)> "))

 (p [Excellent!
     You just wrote your first piece of Guile code!])

 (p [Now you might be wondering, how do I get out of this thing?
     You can type ,(code "(quit)") to quit.
     (Or, if you want to be a bit more fancy and hit two buttons at once,
       you can press ,(code [Ctrl-d]) instead.)])

 (p [This fancy "enter code and experiment with it" thing is called
       Guile's "REPL" (Read Eval Print Loop) and is a great way to experiment
       with code.]))

(section
 :title [Making your life easier: readline and editor friends]
 (p [Two more things.
     These aren't required to continue with this tutorial, but they will
       make it much more pleasant.
     The first is that you may want to
       ,(ref :url [https://www.gnu.org/software/guile/manual/html_node/Loading-Readline-Support.html#Loading-Readline-Support]
             :text [add readline support])
       to your REPL.
     This will make playing around much nicer, because you can now
       keep a "history" of commands around.])

 (p [You also might build up some fun toys while running through this
       tutorial.
     You might want to play with them and re-use them without having
       to type them in all over again.
     This is where your text editor comes into play!
     Try opening a new file, we'll call it "sandbox.scm".
     When you build something in this tutorial you'd like to use
       over and over again without retyping it between REPL sessions,
       you can put it here.
     Let's try putting something there now:])

 (frame
  (prog :line #f
        "(define my-friends 'your-friends)"))

 (p [Now start up ,(code [guile]) again, in the same directory
       as your "sandbox.scm" file.
     We can use a nifty tool called ,(code [load]) to pull toys
       from our sandbox file into our REPL.
     Let's try it!])
 
 (frame
  (prog :line #f
        "scheme@(guile-user)> (load \"sandbox.scm\")
sheme@(guile-user)> my-friends
$1 = your-friends"))

 (p [It looks like it worked!
     We also see that my friends are your friends.
     We're all friends here!])

 (p [Note the ,(code "$1 = your-friends") line.
     When at the REPL, you can refer to the value you got back by
       making use of this number again:])

 (frame
  (prog :line #f
        "scheme@(guile-user)> $1
$2 = your-friends"))

 (p [However, for the rest of the tutorial, we'll be dropping the
       dollar-sign-number pattern and showing things like this,
       just so we don't have to keep track of numbers:])

 (frame
  (prog :line #f
        "scheme@(guile-user)> (+ 1 2)
;; => 3"))

 (p [... which of course means you got 3 back as a result.])

 (p [Okay, that's enough setting things up.
     We have our sandbox, we're in our REPL playground.
     Lets break out the toys and have some fun!]))