README

   1 Information for the Slate Distribution
   2 --------------------------------------
   3
   4 Copyright/License Information
   5 -----------------------------
   6
   7 See the LICENSE file.
   8
   9 What is Slate?
  10 --------------
  11
  12 Slate is a prototype-based, multi-dispatch object-oriented language that
  13 runs from a highly-customizable live environment. The implementation is
  14 highly portable and relatively lightweight.
  15
  16 Where do I learn more?
  17 ----------------------
  18
  19 The reference site for this Distribution is at http://www.slatelanguage.org
  20 and the Google Code project at: http://code.google.com/p/slate-language/
  21
  22 Bug reports and requests for information can be made via the Slate mailing
  23 list, described at: http://groups.google.com/group/slate-language
  24
  25 See the wiki for more detailed documentation:
  26  http://code.google.com/p/slate-language/w/list
  27
  28 See our bug-tracker for issues:
  29  http://code.google.com/p/slate-language/issues/list
  30
  31 Obtaining Slate
  32 ---------------
  33
  34 To get a slate repository on your computer to play with, run:
  35   git clone git://repo.or.cz/cslatevm.git
  36
  37 Setup
  38 -----
  39
  40 'make' builds the VM.
  41 'make slate.image' builds a standard saved image from a kernel image.
  42 'make edit' launches the VM and standard image in Emacs with a scratch area.
  43 '(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".
  44 'make plugins' builds the plugins that you need for the GUI and FFI-related stuff.
  45
  46 Read common.mk for more options.
  47
  48 Command Line
  49 ------------
  50
  51 ./slate -i <image>
  52
  53 This starts slate using <image>.
  54
  55 Run 'slate -h' for more details.
  56
  57 Learning Slate
  58 --------------
  59
  60 Read the online tutorials (from newest to oldest):
  61
  62 * http://slatelanguage.org/tutorial/
  63 * http://code.google.com/p/slate-language/wiki/GettingStarted
  64
  65 Bootstrapping
  66 -------------
  67
  68 If you make changes to core slate files (like adding a new field to
  69 CompiledMethods), sometimes the only easy way to implement those changes
  70 throughout the system is to rebuild Slate completely. Here is how you
  71 generate a new kernel image:
  72
  73 From the shell:
  74
  75  make bootstrap WORD_SIZE=64 && make slate.image WORD_SIZE=64
  76 or
  77  make bootstrap WORD_SIZE=32 && make slate.image WORD_SIZE=32
  78
  79 From within Slate:
  80
  81 At the Slate REPL, execute:
  82  load: 'src/mobius/init.slate'.
  83 then:
  84  Image bootstrap &littleEndian: True &bitSize: 32.
  85 or
  86  Image bootstrap &littleEndian: True &bitSize: 64.
  87
  88 Then you will load the resulting kernel image like a regular image:
  89
  90  ./slate -i kernel.new.<endian>.<wordsize>.<timestamp>.image
  91
  92 After the image is loaded, you will want to save it so you
  93 don't have to go through loading the kernel again:
  94
  95  Image saveNamed: 'slate.image'.
  96
  97
  98 Debugging the VM
  99 ----------------
 100
 101 make vmclean && make DEBUG=1
 102 gdb slate
 103 r -i <image-file>
 104 (on crash or Ctrl-c)
 105 bt
 106 f <n> (change frame to one with an 'oh' object (struct object_heap*))
 107
 108 See the slate backtrace -> print print_backtrace(oh)
 109 Inspect an object       -> print print_detail(oh, struct Object*)
 110 See the stack           -> print print_stack_types(oh, 200)
 111
 112
 113 Build flags (e.g.  make vmclean && make DEBUG=1
 114 EXTRACFLAGS="-DGC_BUG_CHECK -DSLATE_DISABLE_METHOD_OPTIMIZATION
 115 -DSLATE_DISABLE_PIC_LOOKUP"):
 116
 117 GC_BUG_CHECK: extra features for debugging the GC
 118
 119 SLATE_DISABLE_METHOD_OPTIMIZATION: Don't optimize methods after
 120 calling them a lot. Right now it sets method->oldCode to the current
 121 code. In the future it should do inlining.
 122
 123 SLATE_DISABLE_PIC_LOOKUP: At the call site in the current method there
 124 is a cache of called functions which is checked after the global cache
 125 when doing method dispatch.
 126
 127 SLATE_DISABLE_METHOD_CACHE: Disable the global cache when doing method
 128 dispatch.
 129
 130 SLATE_USE_MMAP: Use mmap to allocate the object memory. You should be
 131 able to get constant pointers between runnings so that you can debug
 132 by learning memory addresses from previous runs.
 133
 134 PRINT_DEBUG and the many PRINT_DEBUG_*: Print more verbose output to
 135 the console.
 136
 137 ALWAYS_FULL_GC: Never do a new-generation garbage collection.
 138
 139 GC_MARK_FREED_MEMORY: Mark freed memory with 0xFE in case someone
 140 tries to use it again. (Slow)
 141
 142 See the source for more.
 143
 144 Source directory structure
 145 --------------------------
 146
 147 src/vm
 148 : The C files for the VM. Interprets bytecode and provides necessary facilities for primitives, gc, etc.
 149 src/mobius -> The slate files for the compiler, lexer, bootstrap, and close-to-vm? facilities etc.
 150 src/core
 151 : The core libraries for the default slate system.
 152 src/lib
 153 : The standard but optional libraries.
 154 src/plugins
 155 : C code for slate FFI calls. `make plugins' to build
 156 src/ui
 157 : The slate UI code that probably calls plugins to draw the basics. load: 'src/ui/init.slate'.
 158 src/ui/gtk
 159 : The slate GTK interface. load: 'src/ui/gtk/demo.slate'.
 160 src/net
 161 : The slate networking code. load: 'src/net/init.slate'.
 162
 163 Finding source code
 164 -------------------
 165
 166 Besides using grep, there are a few facilities:
 167
 168  #as: implementations do: [|:each| each definitionLocation ifNotNilDo: [|:l| inform: (l as: String) ]].
 169
 170  (#parseExpression findOn: {Syntax Parser}) definitionLocation
 171
 172 See the slate manual for more details.
 173