HelpSource/Tutorials/Getting-Started/02-First-Steps.schelp

   1 title:: 02. First Steps
   2 summary:: Getting Started With SuperCollider
   3 categories:: Tutorials>Getting-Started
   4 related:: Tutorials/Getting-Started/00-Getting-Started-With-SC
   5
   6 note::
   7 This document is OSX (SCapp) specific in key commands, though the principles extend to all platforms. See the helpfile link::Reference/KeyboardShortcuts:: for key commands in other editors.
   8 ::
   9
  10 section::Hello World, I'm SuperCollider
  11
  12 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:
  13
  14 code::
  15 init_OSC
  16 compiling class library..
  17         NumPrimitives = 587
  18         compiling dir: '/Applications/SC3/SCClassLibrary'
  19         pass 1 done
  20         Method Table Size 3764776 bytes
  21         Number of Method Selectors 3184
  22         Number of Classes 1814
  23         Number of Symbols 7595
  24         Byte Code Size 180973
  25         compiled 296 files in 1.34 seconds
  26 compile done
  27 RESULT = 256
  28 Class tree inited in 0.14 seconds
  29 ::
  30
  31 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:
  32
  33 code::
  34 "Hello World!".postln;
  35 ::
  36
  37 To execute it, simply click to place the cursor on the same line as the code and then press the enter key. Note that the 'enter' key is not the same as the 'return' key. The 'enter' key is the one that is on the number pad. On Mac laptops there is usually a separate enter key down at bottom of the keyboard towards the right, or you can hold down the 'fn' or function key, and press 'return'. If you don't have an enter key, then you can use ctrl-Return, Ctrl-c, fn-Return( on Some Macs), or Shift-Return. Try this now.
  38
  39 If all went well, you should see this in the post window.
  40
  41 code::
  42 Hello World!
  43 Hello World!
  44 ::
  45
  46 Now let's take a closer look at the code. The first bit, code::"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.
  47
  48 The second bit, code::.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.
  49
  50 Why did it print twice? Well, when you execute code in SC, it always posts the last thing executed. So in this case we didn't really need the code::postln:: bit. But in the following example we would. Select both lines of text by clicking and dragging over them, and then press enter.
  51
  52 code::
  53 "Hello World!".postln;
  54 "Hello SC!".postln;
  55 ::
  56
  57 The first line, 'Hello World' would not have printed if we didn't have the explicit postln. Note also that each line of code ends with a semi-colon. This is how you separate lines of code in SC. If we didn't have a semi-colon between the two lines we would get an error.
  58
  59 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. This is convenient as it allows you to select the whole block of code by double clicking just inside one of the parentheses. Try it out on the example below.
  60
  61 code::
  62 (
  63 "Call me,".postln;
  64 "Ishmael.".postln;
  65 )
  66 ::
  67
  68 When code is not surrounded by parentheses it is generally intended to be executed one line at a time.
  69
  70 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, as it's how SC knows where to separate commands. Without a semi-colon above, you would get an error posted.
  71
  72 code::
  73 (
  74 "Call me?".postln
  75 "Ishmael.".postln;
  76 )
  77 ::
  78
  79 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 code::"Ishmael."::.
  80
  81 code::
  82 ERROR: Parse error
  83    in file 'selected text'
  84    line 3 char 11 :
  85         "Ishmael.".postln;
  86 ::
  87
  88 Usually the problem actually occurs a little before that, so that's where you should look. In this case of course, it's the lack of a semi-colon at the end of the previous line.
  89
  90 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.
  91
  92 code::
  93 "Call me ".post; "Ishmael?".postln;
  94 ::
  95
  96 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.
  97
  98 By convention this kind of key sequence is written Cmd - \
  99
 100 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-k (hold down the command key and the shift key, and then press k).
 101
 102 section::The World According to SuperCollider
 103
 104 SuperCollider is actually two programs: The language or 'client' app, which is what you're looking at now, and the server, which does the actual synthesis and calculation of audio. The former is a graphical application with menus, document windows, nice GUI features and a sophisticated programming language; and the latter is a mean, lean, efficient UNIX command line application (meaning it runs without a nice modern GUI).
 105
 106 The two 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 diffferent 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.
 107
 108 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.
 109
 110 But first let's have a little fun, and make some sound...
 111
 112 For more information see:
 113
 114 link::Guides/How-to-Use-the-Interpreter::, link::Reference/Literals::, link::Classes/String::, link::Guides/ClientVsServer::, link::Reference/Server-Architecture::
 115
 116 section::Suggested Exercise
 117
 118 Open a new window by pressing Cmd-n or selecting 'New' from the File menu.Copy some of the posting code from the examples above and paste it into the new document. (The standard Mac Cmd-c and Cmd-v work for copy and paste, or use the Edit menu.)
 119
 120 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!
 121
 122 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.
 123
 124 ____________________
 125
 126 This document is part of the tutorial strong::Getting Started With SuperCollider::.
 127
 128 Click here to go on to the next section: link::Tutorials/Getting-Started/03-Start-Your-Engines::
 129
 130 Click here to return to the table of Contents: link::Tutorials/Getting-Started/00-Getting-Started-With-SC::