README

   1 Information for the Slate Distribution
   2 --------------------------------------
   3
   4  Slate is a prototype-based, multi-dispatch object-oriented language that
   5  runs from a highly-customizable live environment. The implementation is
   6  highly portable and relatively lightweight.
   7
   8  The reference site for this Distribution is at http://www.slatelanguage.org
   9  and the Google Code project at: http://code.google.com/p/slate-language/
  10
  11  Bug reports and requests for information can be made via the Slate mailing
  12  list, described at: http://groups.google.com/group/slate-language
  13
  14  See the wiki for more detailed documentation:
  15  http://code.google.com/p/slate-language/w/list
  16
  17  See our bug-tracker for issues:
  18  http://code.google.com/p/slate-language/issues/list
  19
  20 Setup
  21 -----
  22
  23 'make' builds the VM.
  24 'make slate.image' builds a standard saved image.
  25 'make edit' launches the VM and standard image in Emacs with a scratch area.
  26
  27 Read common.mk for more options.
  28
  29 ./slate -i kernel.image                 "initial bootstrap (see below for more details)"
  30 Image saveNamed: 'my.image'.         "save current image"
  31 ./slate my.image                     "load a saved image"
  32
  33 Command Line
  34 ------------
  35
  36 ./slate -i <image>
  37
  38 This starts slate using <image>.
  39
  40 Run 'slate -h' for more details.
  41
  42 Learning Slate
  43 --------------
  44
  45 Read the TUTORIAL
  46
  47 Bootstrapping
  48 -------------
  49
  50 If you make changes to core slate files (like adding a new field to
  51 CompiledMethods), sometimes the only easy way to make those changes
  52 throughout the system is to bootstrap again. Here is how you generate
  53 a new kernel image:
  54
  55 Run slate to get a repl.
  56
  57 [
  58 load: 'src/mobius/init.slate'.
  59 Image littleEndian: True bitSize: 64.
  60 ] do.
  61
  62 or
  63
  64 [
  65 load: 'src/mobius/init.slate'.
  66 Image littleEndian: True bitSize: 32.
  67 ] do.
  68
  69 Then you will load it like a regular image:
  70
  71 ./slate kernel.new.<endian>.<wordsize>.<timestamp>.image
  72
  73 Debugging
  74 ---------
  75 make vmclean && make DEBUG=1
  76 gdb slate
  77 r <image-file>
  78 (on crash or Ctrl-c)
  79 bt
  80 f <n> (change frame to one with an 'oh' object (struct object_heap*))
  81
  82 See the slate backtrace -> print print_backtrace(oh)
  83 Inspect an object       -> print print_detail(oh, struct Object*)
  84 See the stack           -> print print_stack_types(oh, 200)
  85
  86 Source directory structure
  87 --------------------------
  88
  89 src/vm -> The C files for the VM. Interprets bytecode and provides necessary facilities for primitives, gc, etc.
  90 src/mobius -> The slate files for the compiler, lexer, bootstrap, and close-to-vm? facilities etc.
  91 src/lib -> The core and not-so-core libraries for slate
  92 src/plugins -> C code for slate FFI calls. `make plugins' to build
  93 src/ui -> The slate UI code that probably calls plugins to draw the basics. load: 'src/ui/init.slate'.
  94 src/ui/gtk -> The slate GTK interface. load: 'src/ui/gtk/demo.slate'.
  95 src/net -> The slate networking code. load: 'src/net/init.slate'.
  96
  97 Stack format
  98 ------------
  99
 100 The caller is about to call the callee.
 101 fp at the time of the activation is equal to the current stack pointer plus the function frame size (6).
 102
 103 stack[fp-6] -> the stack pointer before the stack allocation for this frame + localvars + registers is done
 104 stack[fp-5] -> the absolute position (stack location) of where the callee should place its result
 105 stack[fp-4] -> the current code pointer (ip) of the caller
 106 stack[fp-3] -> the callee's closure/method
 107 stack[fp-2] -> the callee's lexical context (nil for stack allocated frames)
 108 stack[fp-1] -> frame pointer of caller
 109 stack[fp+0] .. stack[fp+lvCount+registerCount] -> local variables + registers
 110
 111 When you return from a function and you want to restore the frame in
 112 the interpreter object to what it was before the call, you restore
 113 everything based on fp (interpreter's current fp) except the closure
 114 and the lexical context which are restored based on the saved
 115 framepointer (at fp-1) using the previous frame (notice callee
 116 vs. caller).
 117
 118 Compiler
 119 --------
 120
 121 A simple example:
 122
 123 [ | :c genCode|
 124 genCode: (c generate:
 125 [
 126  1 + 1
 127 ]
 128 method sourceTree result: Nil &topLevel: True) code.
 129 c decompile: genCode
 130 ] applyWith: VM SSACompiler new.
 131
 132
 133
 134 Inside a function definition:
 135
 136
 137 [ | :c genCode|
 138 genCode: (c generate:
 139 [
 140  block@(Method traits) on: c@(Condition traits) do: handler
 141 [| context |
 142   context: (c cloneSettingSlots: #(handlers exitContinuation)
 143               to: {{handler}. [| :result | ^ result]}).
 144   conditionStack push: context.
 145   block ensure: [conditionStack pop]
 146 ].
 147
 148 ]
 149 method sourceTree result: Nil &topLevel: True) code.
 150 c decompile: genCode third code
 151 ] applyWith: VM SSACompiler new.
 152
 153
 154 Inside the closure:
 155
 156 [ | :c genCode|
 157 genCode: (c generate:
 158 [
 159  block@(Method traits) on: c@(Condition traits) do: handler
 160 [| context |
 161   context: (c cloneSettingSlots: #(handlers exitContinuation)
 162               to: {{handler}. [| :result | ^ result]}).
 163   conditionStack push: context.
 164   block ensure: [conditionStack pop]
 165 ].
 166
 167 ]
 168 method sourceTree result: Nil &topLevel: True) code.
 169 c decompile: (genCode third code at: 13) code
 170 ] applyWith: VM SSACompiler new.
 171
 172
 173 "see what is getting called"
 174 VM SSACompiler new decompile: (#handle: findOn: {mainWindow. PaintEvent newContext: mainWindow context}) method code.
 175
 176
 177 Finding source code
 178 -------------------
 179
 180 Besides using grep (which is better since it will find bootstrap
 181 code), there are a few facilities. See the slate manual for more
 182 details.
 183
 184 #as: implementations do: [|:each| each definitionLocation ifNotNilDo: [|:l| inform: (l as: String) ]].
 185
 186 (#parseExpression findOn: {Syntax Parser}) definitionLocation
 187