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 from a kernel image.
  25 'make edit' launches the VM and standard image in Emacs with a scratch area.
  26 '(sudo) make install' installs the VM and images in global directories (/usr/local/ by default) so that the VM can be invoked as just "slate".
  27
  28 Read common.mk for more options.
  29
  30 Command Line
  31 ------------
  32
  33 ./slate -i <image>
  34
  35 This starts slate using <image>.
  36
  37 Run 'slate -h' for more details.
  38
  39 Learning Slate
  40 --------------
  41
  42 Read the online tutorials (from newest to oldest):
  43
  44 * http://slatelanguage.org/tutorial/
  45 * http://code.google.com/p/slate-language/wiki/GettingStarted
  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 rebuild Slate completely. Here is how you
  53 generate a new kernel image:
  54
  55 From the shell:
  56
  57  make bootstrap WORD_SIZE=64 && make slate.image WORD_SIZE=64
  58 or
  59  make bootstrap WORD_SIZE=32 && make slate.image WORD_SIZE=32
  60
  61 From within Slate:
  62
  63 At the Slate REPL, execute:
  64  load: 'src/mobius/init.slate'.
  65 then:
  66  Image bootstrap &littleEndian: True &bitSize: 32.
  67 or
  68  Image bootstrap &littleEndian: True &bitSize: 64.
  69
  70 Then you will load the resulting kernel image like a regular image:
  71
  72  ./slate -i kernel.new.<endian>.<wordsize>.<timestamp>.image
  73
  74 After the image is loaded, you will want to save it so you
  75 don't have to go through loading the kernel again:
  76
  77  Image saveNamed: 'slate.image'.
  78
  79
  80 Debugging the VM
  81 ----------------
  82
  83 make vmclean && make DEBUG=1
  84 gdb slate
  85 r -i <image-file>
  86 (on crash or Ctrl-c)
  87 bt
  88 f <n> (change frame to one with an 'oh' object (struct object_heap*))
  89
  90 See the slate backtrace -> print print_backtrace(oh)
  91 Inspect an object       -> print print_detail(oh, struct Object*)
  92 See the stack           -> print print_stack_types(oh, 200)
  93
  94
  95 Source directory structure
  96 --------------------------
  97
  98 src/vm
  99 : The C files for the VM. Interprets bytecode and provides necessary facilities for primitives, gc, etc.
 100 src/mobius -> The slate files for the compiler, lexer, bootstrap, and close-to-vm? facilities etc.
 101 src/core
 102 : The core libraries for the default slate system.
 103 src/lib
 104 : The standard but optional libraries.
 105 src/plugins
 106 : C code for slate FFI calls. `make plugins' to build
 107 src/ui
 108 : The slate UI code that probably calls plugins to draw the basics. load: 'src/ui/init.slate'.
 109 src/ui/gtk
 110 : The slate GTK interface. load: 'src/ui/gtk/demo.slate'.
 111 src/net
 112 : The slate networking code. load: 'src/net/init.slate'.
 113
 114 Finding source code
 115 -------------------
 116
 117 Besides using grep, there are a few facilities:
 118
 119  #as: implementations do: [|:each| each definitionLocation ifNotNilDo: [|:l| inform: (l as: String) ]].
 120
 121  (#parseExpression findOn: {Syntax Parser}) definitionLocation
 122
 123 See the slate manual for more details.
 124
 125 Compiler
 126 --------
 127
 128 A simple example:
 129
 130 ~~~
 131
 132 [ | :c genCode|
 133 genCode: (c generate:
 134 [
 135  1 + 1
 136 ]
 137 method sourceTree result: Nil &topLevel: True) code.
 138 c decompile: genCode
 139 ] applyWith: VM SSACompiler new.
 140
 141 ~~~
 142
 143 Inside a function definition:
 144
 145 ~~~
 146
 147 [ | :c genCode|
 148 genCode: (c generate:
 149 [
 150  block@(Method traits) on: c@(Condition traits) do: handler
 151 [| context |
 152   context: (c cloneSettingSlots: #(handlers exitContinuation)
 153               to: {{handler}. [| :result | ^ result]}).
 154   conditionStack push: context.
 155   block ensure: [conditionStack pop]
 156 ].
 157
 158 ]
 159 method sourceTree result: Nil &topLevel: True) code.
 160 c decompile: genCode third code
 161 ] applyWith: VM SSACompiler new.
 162
 163 ~~~
 164
 165 Inside the closure:
 166
 167 ~~~
 168
 169 [ | :c genCode|
 170 genCode: (c generate:
 171 [
 172  block@(Method traits) on: c@(Condition traits) do: handler
 173 [| context |
 174   context: (c cloneSettingSlots: #(handlers exitContinuation)
 175               to: {{handler}. [| :result | ^ result]}).
 176   conditionStack push: context.
 177   block ensure: [conditionStack pop]
 178 ].
 179
 180 ]
 181 method sourceTree result: Nil &topLevel: True) code.
 182 c decompile: (genCode third code at: 13) code
 183 ] applyWith: VM SSACompiler new.
 184
 185 ~~~
 186
 187 See what is getting called:
 188
 189 ~~~
 190
 191 VM SSACompiler new decompile: (#handle: findOn: {mainWindow. PaintEvent newContext: mainWindow context}) method code.
 192
 193 ~~~