#lang scribble/manual
@(require (for-label racket))

@title{02. First Steps}
 Getting Started With SuperCollider@section{categories}
  Tutorials>Getting-Started
@section{related}
  Tutorials/Getting-Started/00-Getting-Started-With-SC

@section{note}
 
This document is written so that it can be used on all supported systems, though having first of all macOS in mind using the application SuperCollider.app (SCapp). Some features, e.g. menu commands, are platform specific, but the principles extend to all platforms. See the helpfile link::Reference/KeyboardShortcuts:: for key commands when using other tools such as SC enhanced editors, e.g. on Linux platforms.
::

@section{section}
 Hello World, I'm SuperCollider

It is traditional when learning a new programming language to start with a simple program called 'Hello World'. This just makes the program print the text 'Hello World!' to well, wherever it prints text. In SC that's a place called the post window. The post window is the one that opened up when you first started SC, and a bunch of stuff was printed there which looks something like this:


@racketblock[
init_OSC
compiling class library..
	NumPrimitives = 587
	compiling dir: '/Applications/SC3/SCClassLibrary'
	pass 1 done
	Method Table Size 3764776 bytes
	Number of Method Selectors 3184
	Number of Classes 1814
	Number of Symbols 7595
	Byte Code Size 180973
	compiled 296 files in 1.34 seconds
compile done
RESULT = 256
Class tree inited in 0.14 seconds
::

Don't worry too much about what all that means just now, just keep in mind that this is where SC will send you information. It's also where we'll get the result of our Hello World program, which you can see below:

]

@racketblock[
"Hello World!".postln;
::

To execute it, simply click to place the cursor somewhere on the same line as the code and then press Shift-Enter (Shift-Return on the Mac). Try this now.

If all went well, you should see this in the post window.

]

@racketblock[
Hello World!
Hello World!
::

Alternatively you can also first select the code you wish to execute and then press Ctrl-Enter (Cmd-Return on the Mac). Try this now.

Now let's take a closer look at the code. The first bit, ]

@racketblock["Hello World!"::, is a kind of emphasis::Object::, called a String. An object is basically just a way of representing something in the computer, for instance a bit of text, or an oscillator, that allows you to control it and send messages to it. More about that later, but for now just understand that a String is a way of representing a bit of text.

The second bit, ]

@racketblock[.postln;::, says 'print me (or a meaningful description of me) to the post window.' Remember postln, it's your friend. You can apply it to almost anything in SC and get something meaningful back. This can be very handy when tracking down bugs in your code.

Why did it print twice? Well, when you execute code in SC, it always posts the result of the last bit of code (the last statement). So it first prints because we explicitly told it to print, and then it prints the result of this operation, which happens to be the same in this case.

So in this case we didn't really need the ]

@racketblock[postln:: bit. But in the following example we would. Select both lines of text by clicking and dragging over them, and then execute, i.e. press Ctrl-Enter (Cmd-Return on the Mac).

]

@racketblock[
"Hello there, I'm SuperCollider!".postln;
"Hello World!".postln;
::

The first line, 'Hello there, I'm SuperCollider!' would not have printed if we didn't have the explicit postln.

In general when you are meant to execute several lines of code at the same time they will be surrounded by parentheses, as in the example below. You can have your cursor anywhere in this region (or on the line of the parentheses on the Mac), then double-click and press Ctrl-Enter or Shift-Enter (Cmd-Return or Shift-Return on the Mac) - this selects the whole region and executes it. Try it out on the example below.

]

@racketblock[
(
"Call me,".postln;
"Ishmael.".postln;
)
::

Double clicking inside a pair of enclosing parentheses may not select the entire region on all systems, notably not on modern Macs. On some it may only select the double clicked word. Thus it may be good, to make it a habit to stick to a particular technique. E.g. to first always check you have selected all of the intended code, regardless of the selection technique, before pressing either Ctrl-Enter or Shift-Enter (Cmd-Return or Shift-Enter on the Mac). Then stick to the technique that works best for you. Experiment with this to learn how your system behaves.

When code is not surrounded by parentheses it is generally intended to be executed one line at a time. You can have your cursor anywhere in a line of code and press Ctrl-Enter or Shift-Enter (Cmd-Return or Shift-Return on the Mac) - this selects the whole line and executes it.

Note that each of the lines within the block of code ends with a semi-colon. This is very important when executing multiple lines of code. Try what happens when you execute following variant of the almost identical code.

]

@racketblock[
(
"Call me?".postln
"Ishmael.".postln;
)
::

Executing the code above results in a 'Parse Error'. With an error of this kind, the dot in the error message shows you where SC ran into trouble. Here it happens just after ]

@racketblock["Ishmael."::.

]

@racketblock[
ERROR: syntax error, unexpected STRING, expecting DOTDOT or ':' or ',' or ')'
in file 'selected text'
line 3 char 10:

"Ishmael.".postln;
^^^^^^^^^
)
::

Usually the problem actually occurs a little before that, so that's where you should look.  In this case, it's the lack of a semi-colon at the end of the previous line.  Note that each line of code ends normally with a semi-colon.  This is how you separate lines of code in SC. Since we didn't have a semi-colon between the two lines we have gotten an error. 

Using semi-colons it's possible to have more than one line of code in the same line of text. This can be handy for execution.

]

@racketblock[
"Call me ".post; "Ishmael?".postln;
::

Note also, having an extra semi-colon at the very end of the last piece of code does not hurt and is tolerated by SC for reasons of convenience. 

A couple of more notes about the post window. It's very useful to be able to see it, but sometimes it can get hidden behind other windows. You can bring it to the front at any time by holding down the Command key, and pressing \ . The Command key is the one with the apple symbol on it.

By convention this kind of key sequence is written Cmd - \

As well, sometimes the post window becomes full of stuff and hard to read. You can clear it at any time by pressing Cmd-shift-p (hold down the command key and the shift key, and then press p).

]
@section{section}
 The World According to SuperCollider

SuperCollider is actually three programs:
@section{list}
 
##The text editor (or IDE) which you are looking at,
##the language (sclang, or 'client' app),
##and the server, which does the actual synthesis and calculation of audio.
::
The sclang part is a sophisticated programming language with nice GUI features; and the server part is a mean, lean, efficient UNIX command line application (meaning it runs without any GUI representation).

They communicate by a protocol called Open Sound Control (OSC), over either UDP or TCP, which are network protocols also used on the internet. Don't think from this that the two applications must run on different computers (they can, which can have definite performance advantages), or that they need to be connected to the internet (although it is possible to have clients and servers in different parts of the world communicating!!). Most of the time they will be running on the same machine, and the 'networking' aspect of things will be relatively transparent for you.

You can only communicate with the server using OSC messages over the network, but luckily the language app has lots of powerful objects which represent things on the server and allow you to control them easily and elegantly. Understanding how exactly that works is crucial to mastering SC, so we'll be talking about that in some depth.

But first let's have a little fun, and make some sound...

For more information see:

link::Guides/How-to-Use-the-Interpreter::, link::Reference/Literals::, link::Classes/String::, link::Guides/ClientVsServer::, link::Reference/Server-Architecture::

@section{section}
 Suggested Exercise

Open a new window by pressing Ctrl-N (Cmd-N on a Mac) or choose 'New' from the File menu. Save the document by giving it any name such as 'My first SC code.scd'. Note, you should always use extension '.scd' for files containing SC code. Copy some of above code examples and paste them into the new document (The standard shortcuts Ctrl-C and Ctrl-V (Cmd-C and Cmd-V on a Mac) work for copy and paste, or use the Edit menu).

SC will let you edit the help files and documentation, so it's always a good idea to copy text over before changing it so as to avoid accidentally saving altered files!

Experiment with altering the text between the quotes to print different things to the post window. Do this with both blocks of text wrapped in parentheses, and single lines.

____________________

This document is part of the tutorial strong::Getting Started With SuperCollider::.

Click here to go on to the next section: link::Tutorials/Getting-Started/03-Start-Your-Engines::

Click here to return to the table of Contents: link::Tutorials/Getting-Started/00-Getting-Started-With-SC::