README

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