README.md

   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://github.com/briantrice/slate-language.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 the save-heap snapshot named <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 Slate Code
 100 --------------------
 101
 102 Within the REPL, if an error arises, a debugger prompt will appear:
 103     slate[1]> foo.
 104     Debugging: MethodNotFound traitsWindow
 105     The following condition was signaled:
 106     The method #foo was not found for the following arguments:
 107     {(previousREPLMethod)}
 108
 109     Available Restarts:
 110     restart: 0  Abort evaluation of expression
 111     restart: 1  Quit Slate
 112
 113     Enter 'help.' for instructions.
 114     slate-debug[0..1][frame: 0]>
 115
 116 Type in `help.` to see other commands or `restart: 0.` or just `0.` to escape usually.
 117
 118 Debugging the VM
 119 ----------------
 120
 121     make vmclean && make DEBUG=1
 122     gdb slate
 123     r -i <image-file>
 124     (on crash or Ctrl-c)
 125     bt
 126     f <n> (change frame to one with an 'oh' object (struct object_heap*))
 127
 128 See the slate backtrace -> `print print_backtrace(oh)`
 129 Inspect an object       -> `print print_detail(oh, struct Object*)`
 130 See the stack           -> `print print_stack_types(oh, 200)`
 131
 132
 133 Build flags (e.g.  `make vmclean && make DEBUG=1
 134 EXTRACFLAGS="-DGC_BUG_CHECK -DSLATE_DISABLE_METHOD_OPTIMIZATION
 135 -DSLATE_DISABLE_PIC_LOOKUP"`):
 136
 137 `GC_BUG_CHECK`: extra features for debugging the GC
 138
 139 `GC_INTEGRITY_CHECK`: check all the object memory to make sure it
 140 looks good after a GC
 141
 142 `SLATE_DISABLE_METHOD_OPTIMIZATION`: Don't optimize methods after
 143 calling them a lot. Right now it sets method->oldCode to the current
 144 code. In the future it should do inlining.
 145
 146 `SLATE_DISABLE_PIC_LOOKUP`: At the call site in the current method there
 147 is a cache of called functions which is checked after the global cache
 148 when doing method dispatch.
 149
 150 `SLATE_DISABLE_METHOD_CACHE`: Disable the global cache when doing method
 151 dispatch.
 152
 153 `SLATE_USE_MMAP`: Use mmap to allocate the object memory. You should be
 154 able to get constant pointers between runnings so that you can debug
 155 by learning memory addresses from previous runs.
 156
 157 `PRINT_DEBUG` and the many PRINT_DEBUG_*: Print more verbose output to
 158 the console.
 159
 160 `ALWAYS_FULL_GC`: Never do a new-generation garbage collection.
 161
 162 `GC_MARK_FREED_MEMORY`: Mark freed memory with 0xFE in case someone
 163 tries to use it again. (Slow)
 164
 165 See the source for more.
 166
 167 Source directory structure
 168 --------------------------
 169
 170 Under src:
 171 * vm: The C files for the VM. Interprets bytecode and provides necessary facilities for primitives, gc, etc.
 172 * mobius: The slate files for the compiler, lexer, bootstrap, and close-to-vm? facilities etc.
 173 * core: The core libraries for the default slate system.
 174 * lib: The standard but optional libraries.
 175 * plugins: C code for slate FFI calls. `make plugins' to build
 176 * ui: The slate UI code that probably calls plugins to draw the basics. load: 'src/ui/init.slate'.
 177 * ui/gtk: The slate GTK interface. load: 'src/ui/gtk/demo.slate'.
 178 * net: The slate networking code. load: 'src/net/init.slate'.
 179
 180 Finding source code
 181 -------------------
 182
 183 Besides using grep, there are a few facilities:
 184
 185     #as: implementations do: [|:each| each definitionLocation ifNotNilDo: [|:l| inform: (l as: String) ]].
 186
 187     (#parseExpression findOn: {Syntax Parser}) definitionLocation
 188
 189 See the slate manual for more details.
 190