README for Mythryl

Note for github users
=====================

Mythryl incorporates a self-compiling optimizing native compiler.

Consequently it cannot be compiled without seed executables with
which to bootstrap the system.  The critical executables are:

    bin/mythryld-bootstrap
    bin/mythryl-lex
    bin/mythryl-yacc

Github snapshots do not include these binaries because source
code control systems like git freak out (unsurprisingly!) when
asked to store 20MB binaries updated daily.

If the Mythryl distribution you have in hand does not contain
the above binaries you should go to

    http://mythryl.org/download/

and download the latest tarball;  this will contain the binaries
you need to bootstrap your distribution.




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.

Sometime this year I'm going to put together decent Mythryl library
re/configuration support.  For now, however, all my favorite stuff
is just statically linked into the Mythryl runtime, so you'll just
have to install it all.

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

    libc6-dev


By default Mythryl compiles with the gcc -Werror switch
("treat warnings as errors").  This is normally good but
can be a problem if you are using a version of the compiler
more recent than that used by the developers, which generates
additional warnings.  If so, you may disable this by editing
CFLAGS in the relevant makefile(s), most likely

    src/c/o/Makefile.in

and doing

    make dist-clean
    make compiler

to rebuild.

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.


Do
    make compiler
    make rest
    sudo 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. 

To verify operation you can do
    make check
    make benchmarks

If you want to be really thorough you can also
do following sequence to exercise the remaining
code in the system:

    sh/opt add all			# Add all optional modules into codebase: src/opt/* 
    make glue				# Regenenerate much of the src/opt/* codebases.
    make clean				# Remove obsoleted binaries.
    make compiler			# Recompile main codebase with above modules statically linked.
    make rest				# Recompile rest of codebase.
    make install			# Install in /usr/bin where 'make check' expects to find it.
    make check				# Run all available unit tests.
    make benchmarks			# For good measure.


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.

One final hint:  Mythryl has an interactive mode invoked by doing 'my'
at the shell prompt.  This does not currently implement GNU readline
style history etc.  If you run 'my' under x/emacs shell-mode (as I do)
this lack will probably not bother you; if you don't, or if it does,
one popular solution is

   rlwrap

Alternatives available in Debian/Ubuntu/etc include:

    ledit - line editor for interactive programs 
    rlfe - A front-end using readline to "cook" input lines for other programs 
    rlwrap - readline feature command line wrapper 

Happy hacking! :)

 -- Cynbe




Optional Modules
================

Once you have compiled the base Mythryl runtime and libraries,
you may choose to extend it by linking in various Mythryl-coded
facilities and also C libraries attached via appropriate glue.

Optional modules live in src/opt/.  You can list them via

    ls -l src/opt

Optional modules are managed using the Mythryl script

    sh/opt

Invoking this script with no arguments will list both the available
modules and also the modules currently installed in the codebase.

To add or remove one available module 'foo' you may do respectively

    sh/opt add foo
    sh/opt drop foo

To add or remove all available modules you may do respectively

    sh/opt add all
    sh/opt drop all



 ================================================================================
Optional module for GTK 

 You can add Gtk support to your Mythryl codebase by doing

     sh/opt add gtk

 in the root directory of the source distribution.

 Before doing this you will need to install the Gtk packages
 for your Linux distribution.  On Debian or Ubuntu this may mean:

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



================================================================================
Optional module for ncurses 

THIS MODULE IS (PROBABLY NOT USABLE AS-IS.  It establishes the framework;
it should not be too difficult to make it usable, essentially just
by adding more stanzas to

    src/opt/ncurses/etc/ncurses-construction.plan

Completing this is not something I'm likely to have time to do
very soon;  this would be a nice (and fairly easy) project for
someone else to pick up.

You can add Ncurses support to your Mythryl codebase by doing

    sh/opt add ncurses

in the root directory of the source distribution.

Before doing this you will need to install the
Ncurses packages for your Linux distribution.

On Debian or Ubuntu this is likely to mean

    libncurses5-dev
    libncurses5



================================================================================
Optional module for OpenCV 

THIS MODULE IS NOT USABLE AS-IS.  It establishes the framework.
Making it useful is likely to require a good deal of work.
OpenCV is a hodge-podge of unrelated facilities implemented
in C++ and only intended to be used from C++; for example it
re-invents datastructures like Lists which Mythryl already
has in much better forms.  OpenCV is also written in a
cast-everything-to-void*-and-back style and consequently
tends to crash a lot, in my experience at least.   In my
opinion the best way forward for Mythryl is to cherry-pick
selected useful routines, convert them to C, and design
Mythryl bindings for them essentially from scratch.  I
would not link to the actual distributed OpenCV libraries
at all, just raid the OpenCV source code for useful parts
to steal.

You can add Opencv support to your Mythryl codebase by doing

    sh/opt add opencv

in the root directory of the source distribution.

Before doing this you will need to install the
Opencv packages for your Linux distribution.

On Debian or Ubuntu this is likely to mean

    libcv-dev - development files for libcv
    libcv2.4 - computer vision library
    libcvaux-dev - development files for libcvaux
    libcvaux2.4 - computer vision extension library
    libhighgui-dev - development files for libhighgui
    libhighgui2.4 - computer vision GUI library
    opencv-doc - OpenCV documentation and examples


================================================================================
Optional module for OpenGL

You can add OpenGL support to your Mythryl codebase by doing

    sh/opt add opengl

in the root directory of the source distribution.

Before doing this you will need to install the
OpenGL packages for your Linux distribution.
    
On Debian or Ubuntu this is like to mean

    glew-utils -       The OpenGL Extension Wrangler - utilities
    libglew-dev -      The OpenGL Extension Wrangler - development environment
    libglew1.10 -      The OpenGL Extension Wrangler - runtime environment
    libglewmx-dev -    The OpenGL Extension Wrangler - development environment
    libglewmx1.10 -    The OpenGL Extension Wrangler - runtime environment

    libglfw-dev
    libglfw2

The core OpenGL libs to use will depend on various things;
a safe, standard, portable (but low-performance) option is:

    libglu1-mesa
    libgl1-mesa-glx






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 benchmarks         # Run a few simple comparative timing loops.

        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