Build Requirements ------------------ Building Slate requires: (1) A C compiler and associated toolchain, currently supporting GCC and VC. (2) A downloaded tarball from the Slate website, or a checkout of Slate code repository contents plus bootstrap materials: (1) A bootstrap image: "kernel.little.32.image" for little-endian platforms, or "kernel.big.32.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. If you can use GNU make, it will download the materials for you via the program specified in common.mk (defaults to wget; curl also works). Unix(-like) platforms --------------------- Ensure the image and generated C-sources are in the top directory. Then review and edit the options in the following build files; for the most part, no customization should be needed other than your preferred installation area (the "prefix" variable as /usr/ or /usr/local/ or ~/ in ./common.mk): ./common.mk ./Makefile ./src/mobius/vm/platform/unix/Makefile The Makefiles use specific GNU make features and libtool. Overview of ./Makefile: default - Builds the VM from its sources. plugins - Extra code from src/plugins/ to use native libraries. bootstrap - VM and fully-initialized image. all - VM + plugins + bootstrap. install - Places the VM, headers, emacs mode, etc. in specified places. edit - Opens Slate in Emacs with REPL and Workspace. newboot - Performs a complete build of Slate from initial sources. check - Runs all standard included tests. benchmark - Runs some benchmarks. clean - Cleans out the VM and plugin build results. distclean - clean + Removes vm.c, vm.h, kernel images. The recommended build sequence is to just run "make all" or "make distclean all" to ensure a full upgrade to new system features. If the VM build 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" and a new Slate image titled slate.image. 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 as mentioned above. The VM by default will be installed as "slate". Windows (via MSYS, aka MinGW) ----------------------------- Follow the Unix build instructions. The platform specific Makefile for MSYS is located at "./src/mobius/vm/platform/windows/Makefile". The Unix platform's Makefile will not affect your builds. 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. Windows (Visual Studio) ----------------------- 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. MacOS X (XCode) --------------- An XCode project is provided under: src/mobius/vm/platform/mac/ It mainly wraps the existing Makefile structure for now and refers to relevant VM source files. To include the output binary, you must add it yourself as a "custom executable" since XCode will only save such things to user-specific configuration files. Starting Slate -------------- Execute "vm -i slate.image". This will start Slate with a basic set of libraries and an interactive compilation (read-eval-print) loop. If Emacs is available on your system, it will provide a better environment that you can access via "make edit" or "run-in-emacs.bat". 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("!"). Type "help." in the context to see what the specific interaction tool offers (the REPL, the Debugger, the Inspector). Otherwise, 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. To load more libraries, type: "load: 'fileName'." 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 -i 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. If you encounter errors and want to debug them, "repl noviceMode: False." will enable debugger use on every error. Following Slate Development --------------------------- If you intend to track our source code repository's latest code, perform a separate checkout via darcs get from one of the repositories at: http://slate.tunes.org, and issue the `make distclean bootstrap' command, which removes existing bootstrap core materials, invokes wget to download the latest VM sources and images and build a new VM from them. The bootstrap part then builds a new slate.image from the VM and kernel image. When a full bootstrap is required to integrate new features (announced via the mailing list), repeat this procedure. 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 define: #new -> (VM Definition newNamed: 'vm.new') generate. 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): (Image Definition newNamed: 'kernel.new' basedOn: VM new &littleEndian: False) generate. 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. If you need to produce both a new VM and new images you can do both in a single step with: fullCleanBootstrap. (After having loaded 'src/mobius/init.slate'; "make newboot" automates this). This will produce both big and little images however so you may find it faster to generate the VM and image seperately as outlined above. This method also saves a boot.image file, which will begin executing the specific image-generation code (skipping the VM generation) when you start Slate with it.