			    BUILDING YENTA

If you're already using an architecture for which we provide binaries,
you're not planning on making changes, and you trust the distribution
(verifying its signature is an excellent idea), then you can save
yourself some work by just getting a binary and calling it a day.

Yenta currently has binaries for various versions of Linux, NetBSD,
HPUX, Solaris, Irix, and (perhaps) Alpha.  For information, check out
http://yenta.www.media.mit.edu/projects/Yenta/Releases/Documentation/Distribution/.

If you need to make your own binary, read the following AND ALSO
please send mail to bug-yenta@media.mit.edu telling us how it went.
We might also be interested in redistributing your binary so others
don't have to go through the same work.

(0) Make sure you have the following GNU/FSF utilities installed:
      gcc, make, autoconf, automake
    If you don't have these and don't want to get and install
    them first, you are very much on your own.

    Yenta has been built using gcc 2.7.2.2, make 3.76.1,
    automake 1.3, and autoconf 2.12.  Newer versions will
    probably also work.  Older versions are unknown.
    
(1) Unpack the distribution.
    
(2) cd into the top of the tree, and type ./configure.

(3) Type make.

    [NOTE!  You must -always- do your configuring and making
     from the -very top- of the distribution!  It consists
     of three major subtrees (SSLeay, Savant, and SCM), which
     operate mostly independently from each other, but which
     are all kicked off from the toplevel.  Note also that,
     if you are modifying the code, and you don't make any
     modifications in the SCM directory, then the toplevel
     remake will -not- necessarily recompile the SCM binary
     itself---you'll have to manually remove the binary and
     then remake.  There are also issues with makedepend that
     are more complex than described here; eventually some
     better documentation about that will be available.]

(4) At this point, you should be left with a runnable SCM
    in Yenta/App/C/SCM/scm.  Try running it and make sure
    it gives you a prompt; assuming it does, type (quit)
    to exit.  If you don't get a SCM here, you're doomed;
    try asking the maintainers what to do.  Be prepared
    to show an -entire- transcript of your build or you're
    unlikely to get a useful response.  You're also going
    to have to prove that you're running GNU utilities,
    and you should provide the output of "uname -a" or the
    equivalent.

(5) You now need to build an actual Yenta world load.  This
    is a copy of the SCM interpreter with all of Yenta's scheme
    code loaded into it, which is then dumped to make the final
    binary.

    If you're going to be handing this binary to normal users
    to run, you want what is referred to below as a "customer"
    world.  If you're going to be debugging, you almost certainly
    want a "devo" (short for developer) world.

    To make such worlds, source the text below in tcsh.  (If
    you'd like to contribute a bash version of this, please do.)

    To build a customer world, cd into the very top of the
    distribution tree and type
      ydump nil
    It will print a bunch of text with -no obvious error messages-
    that finishes with "Dumping to yenta..."  If you get any
    output with ";STACK TRACE" or ";ERROR" in it, it's broken.
    The final result will be a file called "yenta" in the toplevel
    build directory.

    If you'd like a devo world instead, do
      ydump t
    instead.  A file called "yenta-devo" will result.  Devo worlds
    never go into the background; instead, they stay connected to
    the tty and make available a read/eval/print loop, so you can
    type at the running SCM and examine variables, redefine functions,
    etc.  They also print a substantial amount of debugging cruft.

    NOTE that you should -not- use ybdump (e.g., layered incrementals)
    on Linux or Alpha; the second layer will crash instantly on
    startup.  See below (under the tcsh fodder) about "dumping".

(6) Run the resulting world.  It should print its welcoming
    banner and start.  Anything else is an error.

If you have problems, please send mail to bug-yenta@media.mit.edu.
Be as specific as you can.  Provide transcripts.  We'll do our best
to assist you.
    
If you build for a new architecture, please let us know how it went,
and whether you're willing to donate the binary (customer worlds only)
to us.


- - - tcsh fodder below - - -

# Wobbling Yenta worlds.
#
# Unfortunately, it appears that -b is ignored if we call dump.
# This means we have to pipe a "(quit)" into the image via stdin if
# we want the dumper to exit when it's finished.  Note also that,
# if you want to be able to type anything at a world you're just
# loading stuff into (as opposed to dumping), you have to -not-
# use the -l switch, or the image will just exit again.
#
# These assume you're in the toplevel Yenta directory, possibly
# having just done a full remake, for example.
#
# Note that the use of ``echo "(quit)" | yload...'' means that
# an error will cause the dumped image to exit.  This is true
# even if you're just typing at the normal SCM repl (e.g., in
# a yenta-pages-only that doesn't even have an srepl) and do
# "(car 1)" or something.  Doing things "by hand" such that the
# quit isn't piped in fixes this.  I imagine this has something
# to do with not flushing input correctly, or something like that,
# across dumped worlds [possibly the dual of the output-port bug],
# but it's too much work to make a special-case version of kbFlush
# that can cope with this, if this is even the problem.
# 
# Running and/or wobbling Yenta application worlds.
# You probably want "yrun t" or "ydump nil", etc.
alias yload-1    'App/C/SCM/scm -l App/Scheme/Yenta/Utilities/wobbling.scm \!*'	# This image exits when done loading/running, unless it was dumping.
alias yload      'App/C/SCM/scm    App/Scheme/Yenta/Utilities/wobbling.scm \!*'	# This image prompts when done loading/running; do (wb:load-yenta X).
alias yrun       'yload-1 -e "(begin (wb:load-yenta \!*) (wb:start-yenta-browser))"'# Arg nil, t, or digit (customer, devo, + devo/persona, - pages).
alias ybanner    'echo "\n+++ Building \!* +++"'
alias ydump      'ybanner "yenta \!*"; echo "(quit)" | yload-1 -e "(wb:wobble-yenta \!*)"'# Arg is nil, t, or digit (customer, devo, devo/persona).
# Like the above, but starts from a world with UI pages loaded.
alias ypload-1   './yenta-pages-only -l App/Scheme/Yenta/Utilities/wobbling.scm \!*'
alias ypload     './yenta-pages-only    App/Scheme/Yenta/Utilities/wobbling.scm \!*'
alias yprun      'ypload-1 -e "(begin (wb:load-yenta \!*) (wb:start-yenta-browser))"'
alias ypdump     'ybanner "page-loaded yenta t"; echo "(quit)" | ypload-1 -e "(wb:wobble-yenta t)"'	# Must be devo if incremental, so force t.
# Dump both a pages world and some other type of world.  [Actually, must be devo---since the pages world assumes it's devo, so force t.]
alias ybdump     'ydump -3; ypdump t'

# Dealing with Purify, if you have it.  You'll have to do "make pure"
# to build the initial SCM, since Purify cannot cope with GNU malloc.
# Also, Purify cannot cope with dumped worlds, so you'll have to load
# all of Yenta's code into a SCM and just run that.  It will be -slow-.
alias ypure       'App/C/SCM/scm.pure -l App/Scheme/Yenta/Utilities/wobbling.scm -e "(begin (wb:load-yenta \!*) (wb:start-yenta))"'

- - - End of tcsh fodder - - -

Here are some more notes on building for new architectures, for which
we have never built before.  You should be aware of the following
tricks:

(1) The versions of SCM and SSLeay used herein are -not- exactly like
    the versions you'll find mirrored from their authors.  We've made
    extensive patches to them.  In addition, we've autoconfiscated
    them, e.g., used autoconf and automake.  Their original authors
    did -not- do this.  Thus, you'll find that diffing the originals
    and our versions will yield lots of changes.  This is one of the
    reasons why going to newer versions of these will take some work,
    but if anyone would like to volunteer, we'd like to encourage you.
    
(2) Since we collaborate with the authors of Savant, that code is
    autoconfiscated both from them and from us.  However, Yenta has
    its own local patches to it.  Again, you'll have to diff against
    their distribution if you'd like to find out what those are.

(3) One of the hardest things to get right is dumping.  We've used the
    code from Emacs 20.3 (20.2 is -too old-!), and used the dumping
    code for each particular machine that we support.  We have
    modified these files slightly from the distribution!  But we have
    only done this for the ones we use for architectures we dump from!
    We nonetheless -distribute- all of them, so beware.  You'll no
    doubt have to modify some of the ones we distribute if you start
    using them.  Therefore, if you're supporting a new architecture:
    (a) Try building the SCM binary, and then running an -undumped-
        version first (e.g., the "yrun" command from the tcsh aliases
        above).  If that works, then at least it's worth trying to
        dump a binary.
    (b) If Emacs 20.3 doesn't support your machine, e.g., you cannot
        make a correctly-working dumped Emacs on that machine, you are
        totally on your own.  If you manage to get it working, though,
        tell us!  (Also, tell the Emacs maintainers.)
    (c) Modify the machine-specific files.  The easiest way to figure
        out what to do is to diff one of ours (e.g., hpux, irix,
        netbsd, linux, or alpha) against the 20.3 distribution, and
        then mirror the changes in your own machine's file.
    (d) Dumps often work -only- if the image is dynamically linked, or
        -only- if it's not.  It's a toss-up.  If it doesn't work,
        change your link flags to the other and try again.
    
    A quick way to test the dump is just to start the bare SCM binary
    (without all the Yenta-specific files), and immediately dump it
    via (dump "test-me").  Then do ./test-me.  If you don't get the
    SCM banner, and instead get a coredump or an immediate error about
    a corrupted heap, then your dump didn't work.  If the dump starts
    up correctly, then it's worth bothering to load the rest of Yenta
    in a bare SCM and dumping -that-.

    Some architectures apparently don't support layered incrementals,
    e.g., neither Linux nor the Alpha work correctly if you dump SCM
    to A, then start A and dump to B.  B will crash.  Thus, don't use
    the "ybdump" alias on those architectures, and be aware that this
    may be a problem for new architectures.  (If you figure out how to
    make this work, please tell us!)  It might be interested to try
    the equivalent when building Emacs and see what happens.  We haven't.

(4) If you change anything that requires autoconf or automake to be
    rerun, you'll have to build in a two-phase manner to get the
    Makefiles to continue to include their dependency information.
    Failing to do this will give you a zillion spurious differences
    between the distributed makefiles and the ones you wind up with.
    Here's a quick summary:

	As far as I can tell, automake will only put dependency information in
	makefiles when (1) the relevant .deps/*.P files exist and (2) you
	invoke it as something like

		automake --foreign --include-deps --build-dir=`pwd` --srcdir-name=.

	To keep the info around when you don't change any Makefile.am s, it
	suffices to keep the Makefile.in s newer than both them and the
	relevant configure.in so automake doesn't think it needs to rebuild
	them.  When you do change a Makefile.am, the following commands in the
	top of the relevant package (SCM, Savant, or SSLeay) generally do what
	you want:

		automake --foreign
		make -n  [As of automake 1.3, this must not be "-n"!  --- Foner]
		automake --foreign --include-deps --build-dir=`pwd` --srcdir-name=.

	Exception: when pulling dependency information into
	SSLeay/apps/Makefile.in, automake likes to put bogus "../"s before
	testdsa.h and testrsa.h in speed.o's dependencies.  You need to remove
	them by hand.  I never got around to reporting this bug. :-/

(5) If you're new to dealing with autoconf/automake, you probably
    shouldn't be trying to modify lots of things anyway, but here are
    some clues that might get you started:

	Within each package (Savant, SCM, etc.), the only
	configuration-related files you should edit are configure.in,
	acconfig.h, .../Makefile.am, and possibly acsite.m4.  Everything else
	is generated from them as follows:

	file		generated by	generated from
	----		------------	--------------
	aclocal.m4	aclocal		acsite.m4, configure.in
	configure	autoconf	aclocal.m4, configure.in
	config.h.in	autoheader	aclocal.m4, configure.in
	.../Makefile.in	automake	aclocal.m4(?), configure.in, .../Makefile.am
	config.h	configure	config.h.in
	.../Makefile	configure	.../Makefile.in

	To add a file to a library in that package:
		Add it to libwhatever_a_SOURCES in the Makefile.am in that directory.
		Run automake --foreign at the top of the package.
		Run configure or config.status at the top of the package.

	To add a directory to a package:
		Add its Makefile to the list of files to produce in its configure.in.
		Add it to SUBDIRS in its parent's Makefile.am.
		Run configure or config.status at the top of the package.

	To bump the version number of a package:
		Change the number in AM_INIT_AUTOMAKE in its configure.in.
		Rerun autoconf.
		Rerun aclocal, automake --foreign, and autoheader to placate make.
		(It'll want to rerun them anyway because configure.in changed.)
		Run configure or config.status at the top of the package.

	For more information, consult the texinfo documentation for autoconf
	and automake.

Good luck!
