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