Information for the Slate Distribution
--------------------------------------

 The reference site for this Distribution is at http://slate.tunes.org/

 Bug reports and requests for information can be made via the Slate mailing
 list, described at: http://lists.tunes.org/mailman/listinfo/slate

License
-------

 Slate is released freely by Lee Salzman and Brian T. Rice for modification 
 and usage under the MIT Public License, as described in the file
 LICENSE provided with this Distribution.

Release Notes
-------------

 See the NEWS file in this Distribution.

Outstanding Issues
------------------

 See the BUGS file in this Distribution.

Building Slate
--------------

 Building Slate requires a C compiler and associated toolchain, and a
 downloaded tarball from the Slate website, or a checkout of Slate code
 repository contents plus bootstrap materials:
 (1) A bootstrap image: "little.image" for little-endian platforms,
     or "big.image" for big-endian platforms.
 (2) Slate-output virtual machine sources, titled "vm.c" and "vm.h".

 The "alpha" repository on the Slate website provides these materials.

 Unix(-like) platforms
 ---------------------

  Ensure the image and generated C-sources are in the top directory,
  and review and edit the options in the files:
    ./Makefile.inc
    ./Makefile
    ./src/mobius/vm/platform/unix/Makefile

  Then, issue the `make' command in the top directory to build the virtual
  machine. If the process reports errors (vice warnings), please submit a bug
  report with the relevant part of the output (and system information) after
  verifying that your C compiler has been invoked correctly.

  Once done, you should have an executable in the top directory named "vm".

  Once Slate is built per the instructions above, issuing `make install' will
  place the binaries, emacs mode code, and VM header file into the appropriate
  places for Unix-like systems. The locations may be customized by editing
  their default values in ./Makefile.inc. The VM by default will be installed
  as "slate".

  Extra plugin functionality can be enabled by issuing `make plugins' or
  `make all' which builds both the VM and plugins at once.

 Windows (NT and derivatives)
 ----------------------------

 VC++ 2005 Beta Project and Solution files are available under:
   src/mobius/vm/platform/windows/

 WARNING: Compiling Slate using Microsoft Visual C with global optimizations
 will not work due to bugs (beyond our control) in Microsoft's compiler. We 
 recommend you use GCC (via MinGW or Cygwin) on Windows platforms. 

 The plugins on the Windows platform are largely driven directly via dynamic
 linking, so this is all done in Slate and requires no build procedure.

 The MinGW Makefile target will use all of the Windows-specific VM sources, so
 you will not need a special environment (as in Cygwin) to use it.

Starting Slate
--------------

 Execute "vm little.image" (or big.image if your system has big-endian byte
 ordering). This will start Slate with a basic set of libraries and an
 interactive compilation (read-eval-print) loop.

 Now you can enter some basic expressions, but note that the REPL does not
 complete as a loop until a stop (".") is entered at the top-level. Consider
 it equivalent to Smalltalk's bang("!").

 There is little online help yet, so we must refer you to the programmer's
 manual in HTML under doc/progman/ or PostScript/PDF under the doc/ directory.
 Slate source files are considerably-commented and are the next step to
 learning. It is helpful to start with "src/lib/inspect.slate" to learn the
 Inspector tool and to use that to navigate the system. Or type "help." in
 the context to see what the specific interaction tool you're using offers.

 To load more libraries, use the "load: 'fileName'." command.
 Some libraries have "auto-loaders" installed which mean you can merely
 mention a feature to have it transparently loaded and used during evaluation.
 To exit, enter "quit.".
 To save Slate memory contents for quick loading as a whole, type:
 "Image save &name: 'my.image'." or "Image saveNamed: 'my.image'.".

 to create a file named my.image which can be loaded via "vm my.image"
 from the command-line. Once saved, an image will remember the filename it is
 associated with, so that calling "Image save." subsequently will save to the
 same file. This default filename starts as "slate.image" which the VM will
 look for if not provided an image argument.

Guide to the Slate directories
------------------------------

demo/ - Included demonstration code.
doc/ - Various guides and system manuals.
etc/ - Extra configuration files, and editing modes for Vim, Emacs, and KDE.
src/ - Slate's libraries.
    i18n/ - Internationalization / language encoding support libraries.
    lib/ - Base utilities (data structures, streams, and utilities).
    mobius/ - Self-hosted implementation.
	bootstrap/ - Bootstrap code, for the future run-time builds.
	c/ - Dealings with C-specific compiler backend and types/syntax.
	syntax/ - Parser and high-level compiler.
	optimizer/ - Optimization framework.
	    ir/ - Intermediate representation of code and optimizations.
	    mr/ - Machine representation of code for generation.
	vm/ - VM-related code.
	    base/ - Core layout definitions and protocols.
	    ext/ - Extensions and primitive methods.
	    gc/ - Garbage collectors / memory managers.
	    interp/ - Bytecode interpreter userland libraries.
	    platform/ - Platform-specific support.
    mop/ - Meta-object protocol.
    plugins/ - Implementation extensions and userland support code.
    smalltalk/ - Smalltalk compatibility framework.
    ui/ - User interface system, primarily graphics-related.
	SDL/ - The Simple Directmedia Library support.
	X11/ - The X11 server protocol support.
tests/ - Validation suites for the various Slate libraries.

Extending Slate
---------------

 If you only want to customize the list of files loaded on the distribution
 core image start-up, just edit src/mobius/vm/post-bootstrap.slate to include
 whatever libraries you find useful.

 If you just need to build a plugin to access some optional binding to an
 external library or fast-compiled routines, use the src/plugins/ directory
 structure and use an existing plugin as a template, with its own Makefile.
 Then the `make plugins' directive will work on it as well.

 If you need to build a modified or extended virtual machine (the details
 of modification involved are described in the Mobius manual) or core image,
 there is a more involved process called bootstrapping. Simply execute:

 load: 'src/mobius/init.slate'.
 VM generate &named: 'NewVM'.

 If the VM's interface somehow changes: added primitives or modified image
 format of some sort, an image which links to that VM interface must be
 built within a Slate system that has that VM's information. This means that
 you should execute the following, within the same image that the VM was
 built, after the VM build (substituting the correct endianness value for
 your platform):

 VM buildImage &named: 'NewImage' &littleEndian: True.

 and then repeat the instructions above to build the virtual machine, with
 appropriately-changed options as necessary. NOTE: even if you only modify
 the image, it must still be built within a Slate system which has created
 a VM definition and stored it, as that information is re-used to define
 the image.

Following Slate Development
---------------------------

 If you intend to track our source code repository's latest code, perform a
 separate checkout via darcs get, and issue the `make update-source' command
 (which invokes wget) to obtain the latest VM sources and images; rebuild the
 VM with the usual make command as needed; this command is necessary whenever
 a full bootstrap is required to integrate new features.
