README for Mythryl

Installing Mythryl
==================

Mythryl is currently developed on 32-bit x86 Debian Linux. ("stable".)
The distribution provided should build on most (all?) x86 Linux
platforms, and perhaps some x86 BSDs.  It is known not to install
on Mac OS X.  It definitely will NOT install on non-x86 platforms
as distributed.

(Since Mythryl is a self-compiling system, this source distribution
necessarily also includes a set of seed binary files for bootstrap
purposes, hence the comparatively large size of the tarball.)

You may unpack it on most platforms by doing

    tar -xjf mythryl.110.58*tar.bz2

Next, 'cd' into the directory thus created.

Before compiling, make sure you have the standard C and Gtk
development libraries and header files installed.
On Debian or Ubuntu this will include

    libc6-dev
    libgtkglext1-dev
    libgtk2.0-0
    libgtk2.0-bin
    libgtk2.0-common
    libgtk2.0-dev


If Mythryl segfaults it will generate an informative heapdump
for debugging purposes.  This will include disassembly of the
compiled Mythryl x86 code if libdisasm is present.  This
library is available from

    http://bastard.sourceforge.net/libdisasm.html

which on Debian (and Debian-derived Linux distros like Ubuntu) 
is available via the packages

    libdisasm0
    libdisasm-dev

Lack of these libraries will seldom if ever matter to the
typical Mythry user or Mythryl application programmer.


# To play with the (currently nonfunctional) Mythryl OpenCV
# library bindings, you'd also need the OpenCV development
# libraries and header files:
#    libcv1
#    libcv-dev
#    libcvaux1
#    libcvaux-dev
#    libhighgui1
#    libhighgui-dev
# NB:  The "make check" code exercising these is currently
# commented out in   src/lib/test/unit-tests.make7
# and                src/lib/test/all-unit-tests.pkg 

Do
    make compiler

As root do

    make install

This will install the following executables:

    /usr/bin/mythryl                    # The wrapper C program which makes script-style Mythryl shebang invocation work.
    /usr/bin/mythryl-runtime-intel32    # The C-coded runtime which actually executes the 'mythryld' heap image.
    /usr/bin/mythryld                   # The compiler proper, with all major libraries preloaded, as an "executable" heap image.
    /usr/bin/my                         # Symlink to the above, for brevity and interaction. 
    /usr/bin/mythryl-gtk-slave          # Mythryl Gtk library support. This is a work in progress.

With that done, you should be able to execute
the provided

    try/hello

Mythryl script.  At that point I suggest
consulting the tutorial pages at

    http://mythryl.org

If you find Mythryl interesting, you may wish to
subscribe to the mailing list to get announcements
of new releases:

    http://mythryl.org/mailman/listinfo/mythryl

This is a low-traffic list.

Happy hacking! :)

 -- Cynbe



Mythryl Development Cycle
=========================

For what it is worth, the compiler development cycle I use is:

    loop {

        edit madly              # In xemacs, of course! :)

        make compiler           # Build the compiler and core libraries.
        make rest               # Build the rest of the distribution -- x-kit &tc.

        sudo make install       # Install executables in /usr/bin

        make check              # Verify that nothing obvious is broken.
                                # These checks run the /usr/bin copies
                                # of the executables, so if you skip the
                                # above install, you're testing the wrong
                                # version.  (I actually do "make cheg" rather
                                # than "make check", which exercises some
                                # additional code, but "make check" should do
                                # nicely for most developers.)

        make tar                # Save a known-good copy of the codebase.
                                # (I actually do "make tart", which also
                                # rebuilds the emacs "tags" file.) 
    }

I usually run the above cycle roughly once an hour
during development.

If something breaks, I rarely debug.  Instead I go back
to the most recent known-good tarball and set forth
again from it, only more carefully this time.

Once a day or so, I make a remote backup of a known-good
tarball.

Once a month or so, I prune my collection of old tarballs
down to one per day.

When I wake up with my finger on the 'j' key and a screenful
of 'j's, I go to bed. :)



Additional Resources
====================

The latest development snapshots of Mythryl may be found at:

    http://github.com/Mythryl/
  
For Debian Linux users, Michel Bini established and maintains a
.deb Mythryl repository at:

    https://launchpad.net/~michele-bini/+archive/ppa-mbxxii

Direct link to the Mythryl 6.1.0 .deb:

    https://launchpad.net/~michele-bini/+archive/ppa-mbxxii/+files/mythryl_6.1.0-1ppamb41_i386.deb

For emacs and xemacs users Michele Bini has taken over maintainance of Phil Rand's
mythryl-mode.el at:

    https://github.com/rev22/mythryl-mode

Direct link to .deb package for mythryl-mode.el:

    https://launchpad.net/~michele-bini/+archive/ppa-mbxxii/+files/mythryl-mode_2.4.6.deb3_all.deb


Building on Mac OS X: Lion (darwin > 3)
=======================================
download and install http://download.mono-project.com/archive/2.10.9/macos-10-x86/10/MonoFramework-MDK-2.10.9_10.macos10.xamarin.x86.dmg
download and install http://www.ient.rwth-aachen.de/~asbach/OpenCV-Private-Framework-1.2.dmg
(install with sudo cp -r /Volumes/OpenCV\ Private\ Framework/OpenCV.framework/ /Library/Frameworks/OpenCV.framework)
build with: PKG_CONFIG_PATH=/Library/Frameworks/Mono.framework/Versions/2.10.9/lib/pkgconfig:/Library/Frameworks/OpenCV.framework make compiler
(until I can figure out how to set that automatically)

When you build you'll get a bunch of errors on prim.s/o. The problem is the generated Makefile doesn't know to use the -arch i386 on the assembler step.

Build is currently failing on mythryld with:

/Users/ola/Documents/mythryl-omork/bin/mythryl-runtime-intel32: Nonfatal error:  Unable to map 8519680 bytes, errno = 19
/Users/ola/Documents/mythryl-omork/bin/mythryl-runtime-intel32: Fatal error:  Unable to allocate ram region for book_to_sibid__global
             sh/make-compiler-executable:   Compiler link failed, no mythryld executable