| blob | 2ae7b7bc3d0b8531ae09ebcc55155415d887c49f |
1 Information for the Slate Distribution
2 --------------------------------------
4 Copyright/License Information
5 -----------------------------
7 See the LICENSE file.
9 What is Slate?
10 --------------
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.
16 Where do I learn more?
17 ----------------------
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/>
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>
25 See the wiki for more detailed documentation:
26 <http://code.google.com/p/slate-language/w/list>
28 See our bug-tracker for issues:
29 <http://code.google.com/p/slate-language/issues/list>
31 Obtaining Slate
32 ---------------
34 To get a slate repository on your computer to play with, run:
35 git clone git://github.com/briantrice/slate-language.git
37 You must download a Slate image snapshot from Google Code:
38 <http://code.google.com/p/slate-language/downloads/>
40 Setup
41 -----
43 'make' builds the VM.
44 'make edit' launches the VM and standard image in Emacs with a scratch area.
45 '(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".
46 'make plugins' builds the plugins that you need for the GUI and FFI-related stuff.
48 Read common.mk for more options.
50 Command Line
51 ------------
53 ./slate -i <image>
55 This starts slate using the save-heap snapshot named <image>.
57 Run `slate -h` for more details.
59 Learning Slate
60 --------------
62 Read the online tutorials (from newest to oldest):
64 * <http://slatelanguage.org/tutorial/>
65 * <http://code.google.com/p/slate-language/wiki/GettingStarted>
67 Bootstrapping
68 -------------
70 If you make changes to core slate files (like adding a new field to
71 CompiledMethods), sometimes the only easy way to implement those changes
72 throughout the system is to rebuild Slate completely. Here is how you
73 generate a new kernel image:
75 From the shell:
77 make bootstrap WORD_SIZE=64 && make slate.image WORD_SIZE=64
78 or
79 make bootstrap WORD_SIZE=32 && make slate.image WORD_SIZE=32
81 From within Slate:
83 At the Slate REPL, execute:
84 load: 'src/mobius/init.slate'.
85 then:
86 Image bootstrap &littleEndian: True &bitSize: 32.
87 or
88 Image bootstrap &littleEndian: True &bitSize: 64.
90 Then you will load the resulting kernel image like a regular image:
92 ./slate -i kernel.new.<endian>.<wordsize>.<timestamp>.image
94 After the image is loaded, you will want to save it so you
95 don't have to go through loading the kernel again:
97 Image saveNamed: 'slate.image'.
99 The same steps can also be accomplished with:
100 make slate.image
102 Debugging Slate Code
103 --------------------
105 Within the REPL, if an error arises, a debugger prompt will appear:
106 slate[1]> foo.
107 Debugging: MethodNotFound traitsWindow
108 The following condition was signaled:
109 The method #foo was not found for the following arguments:
110 {(previousREPLMethod)}
112 Available Restarts:
113 restart: 0 Abort evaluation of expression
114 restart: 1 Quit Slate
116 Enter 'help.' for instructions.
117 slate-debug[0..1][frame: 0]>
119 Type in `help.` to see other commands or `restart: 0.` or just `0.` to escape usually.
121 Debugging the VM
122 ----------------
124 make vmclean && make DEBUG=1
125 gdb slate
126 r -i <image-file>
127 (on crash or Ctrl-c)
128 bt
129 f <n> (change frame to one with an 'oh' object (struct object_heap*))
131 See the slate backtrace -> `print print_backtrace(oh)`
132 Inspect an object -> `print print_detail(oh, struct Object*)`
133 See the stack -> `print print_stack_types(oh, 200)`
136 Build flags (e.g. `make vmclean && make DEBUG=1
137 EXTRACFLAGS="-DGC_BUG_CHECK -DSLATE_DISABLE_METHOD_OPTIMIZATION
138 -DSLATE_DISABLE_PIC_LOOKUP"`):
140 `GC_BUG_CHECK`: extra features for debugging the GC
142 `GC_INTEGRITY_CHECK`: check all the object memory to make sure it
143 looks good after a GC
145 `SLATE_DISABLE_METHOD_OPTIMIZATION`: Don't optimize methods after
146 calling them a lot. Right now it sets method->oldCode to the current
147 code. In the future it should do inlining.
149 `SLATE_DISABLE_PIC_LOOKUP`: At the call site in the current method there
150 is a cache of called functions which is checked after the global cache
151 when doing method dispatch.
153 `SLATE_DISABLE_METHOD_CACHE`: Disable the global cache when doing method
154 dispatch.
156 `SLATE_USE_MMAP`: Use mmap to allocate the object memory. You should be
157 able to get constant pointers between runnings so that you can debug
158 by learning memory addresses from previous runs.
160 `PRINT_DEBUG` and the many PRINT_DEBUG_*: Print more verbose output to
161 the console.
163 `ALWAYS_FULL_GC`: Never do a new-generation garbage collection.
165 `GC_MARK_FREED_MEMORY`: Mark freed memory with 0xFE in case someone
166 tries to use it again. (Slow)
168 See the source for more.
170 Source directory structure
171 --------------------------
173 Under src:
174 * vm: The C files for the VM. Interprets bytecode and provides necessary facilities for primitives, gc, etc.
175 * mobius: The slate files for the compiler, lexer, bootstrap, and close-to-vm? facilities etc.
176 * core: The core libraries for the default slate system.
177 * lib: The standard but optional libraries.
178 * plugins: C code for slate FFI calls. `make plugins' to build
179 * ui: The slate UI code that probably calls plugins to draw the basics. load: 'src/ui/init.slate'.
180 * ui/gtk: The slate GTK interface. load: 'src/ui/gtk/demo.slate'.
181 * net: The slate networking code. load: 'src/net/init.slate'.
183 Finding source code
184 -------------------
186 Besides using grep, there are a few facilities:
188 #as: implementations do: [|:each| each definitionLocation ifNotNilDo: [|:l| inform: (l as: String) ]].
190 (#parseExpression findOn: {Syntax Parser}) definitionLocation
192 See the slate manual for more details.