
    This file provides basic information about Autoconf 
    and the new XSB setup. Mostly the developer stuff.

    For *NIX only. See ../INSTALL_WINDOWS for the info
    on that other OS.


The good news is that you don't really need to know much about
Autoconf---the hard work has already been done! The following is primarily
intended to make sure that no one deletes the files that Autoconf needs ;-)

The new setup makes XSB much more flexible as a platform for building other
systems. XSB can be built in-place or installed in another place after the
compilation. The executable code can be moved around without the fear of
breaking the system.  XSB can be compiled for different architectures from
the same source tree, and there will be no conflict between the
architecture-specific files. Moreover, at run time XSB can find 
libraries specific to its current configuration and use them.

One limitation: you cannot build XSB for several different architectures
simultaneously, since `configure' and `make' use the same output
files. However, after you have built for one architecture (configure
followed by makexsb; see below), the scripts clean up after themselves, and
the source tree is ready to be built for the next architecture. XSB can
then be run on all architectures for which it was built.


configure.in	  - this is the main workhorse that Autoconf uses to create 
		    the configure script. It is a shell script interspersed 
		    with m4 macros.

aclocal.m4	  - some m4 macros customized for the XSB build.
accconfig.h	  - a set of undef statements that autoheader uses to
		    create def_config.h. Autoconf then uses def_config.h to 
		    create the file config/<architecture>/xsb_config.h.

topMakefile.in	  - the Makefile template from which the main makefile is
		    produced. 
emuMakefile.in	  - the Makefile template from which the makefile for the
		    emu directory is derived.
MSVC_Makefile.mak - the Makefile for building using MS Visual C++ on Windows.
MSVC.sh           - shell script that creates dependencies for Microsoft NMAKE
MSVC.sed          - sed script used by MSVC.sh

def_config_wind.in  - Out of this, configure generates a config.h file for
		     Windows NT/95/98.
def_debug.h.in	  - the template from which debug.h is produced. Debug.h is 
		    a new file, automatically generated by Autoconf, which
		    contains the defines for DEBUG, PROFILE, and DEBUG_ORACLE.
		    Other things may be added later.
		    If resides in emu/debugs/

config.sub
config.guess	  - scripts that automatically guess the computer
		    architecture and the OS you are running.

install-sh	  - the installation script. We don't use it that much, but 
		    autoconf likes to have it around.

version.sh	  - this is where you specify the version of XSB you are
		    building. This information is no longer hard-wired into
		    the source code (and it should never have been!!!).

register.sh	  - the registration shell script
sendlog.msg
registration.msg  - data files for register.sh

banner.in    	  - template for the banner message that XSB displays on
		    startup. This produces config/<archlib>/banner.msg

xsb.in		  - Autoconf uses this to create bin/xsb.

		    This script automatically guesses your computer/OS
		    configuration and dispatches the right executable for you.
		    It is just a convenience that saves you some typing.

makexsb.in	  - Input for producing the `makexsb' script. You run
		    `makexsb' instead of `make'. The purpose of `makexsb'
		    is to find the appropriate architecture-specific make
		    file and then run make on it. 

pkg_config.sh
copysubdirs.sh    - Scripts used in topMakefile to configure packages and
		    copy subdirectories when the user types `makexsb install'.

If you change any of the above files, run

   autoconf

in the build directory to update the `configure' script!!!
Of course, you need Autoconf to be installed to do this, but to distribute
XSB we don't need to distribute Autoconf. We only need to include the
configure script and the *.in files.

YOU NEED TO RUN autoconf IFF YOU ENHANCE THE SETUP OR FIX A BUG!


The new directory structure:

    emu		  - C source code for XSB
    emu/debugs/   - debug include files. The files are:

				  debug_biassert.h 
				  debug_delay.h
				  debug_residual.h
				  debug_tries.h
				  debug_tables.h

		    These are NOT created automatically. I went into the
		    trouble of sorting out the various debug variables left 
		    in the code and classified them into categories.
		    The various .c files include only the relevant debug*.h
		    files.
		    If you want to turn some debug feature on, DON'T DO IT
		    IN THE MAIN .c file!!! Instead, change the #undef
		    statement in the appropriate debug*.h file.

		    In the future, PLEASE FOLLOW THIS SCHEMA, so it would
		    be easier to track down what each particular flag is for.

    lib/
    syslib/
    cmplib/       - no changes here

    config/	  - this is the directory that stores the various
		    configuration-specific stuff, including the executables 
		    and the object code.
		    You can compile for various architectures from the same 
		    source and keep the object codes around, so building
		    for a new architecture won't wipe out the object code
		    of the other ones!

    packages/	  - XSB packages

    prolog_includes/ - .h files that can be included by the C preprocessor
		       into Prolog programs (files that are included into C
		       programs and both C and Prolog programs are kept in
		       the emu/ directory).

The structure of the config directory:

    config/ has a subdirectory for each architecture. For instance:

    config/sparc-sun-solaris2.6/
    config/sparc-sun-sunos4.1.4/
    config/mips-sgi-irix6.2/

    The architecture name has the structure: cpu-vendor-os

    Each of these directories has, in turn, these subdirectories:

	 bin/
	 saved.o/
	 lib/

    The bin/ directory contains the XSB executable for the configuration
    at hand. The saved.o/ directory contains copies of the object code for
    the files from the emu/ directory. This is used by `make' to avoid
    recompilation of the entire source when XSB is built for multiple
    architectures from the same source tree. The lib/ directory is intended 
    to keep architecture-specific .P and .so files (i.e., Prolog code and
    dynamically loaded libraries). We envision that it will mostly contain
    .so files, since Prolog code doesn't depend on the architecture it is
    run on. However, in some cases (like with the current Perl interface),
    a Prolog program might include architecture-specific facts (like where
    is the Perl executable is on this particular architecture). In such a
    case, the <arch>/lib/ directory is the proper home for that XSB
    program.
    If mixing .P and .so files in one directory will turn out to be a
    problem in the future, we might separate the two. Right now there is
    only a handful of such external packages, anyway.

    Apart from these directories, the config/<architecture>/ directory
    contains the files created by Autoconf:

        emuMakefile - this is the makefile for emu/
		      It gets copied into emu/ when you type `make'
		      in the build directory.
	topMakefile - the top make file, which is originally created in the 
		      build directory.
       xsb_config.h - The file that contains the appropriate #define
		      statements for this architecture. It gets copied into
		      emu/configs/ when you type make in the build/ directory.
		      This file replaces the old config.h
        xsb_debug.h - The file containing some debug includes.
    	banner.msg  - Message displayed by XSB on startup.

	xsb_configuration.P -
	    	     configure takes this and produces a
		     configuration.P file.
		     this is a Prolog file that contains the definition
		     of the new predicate: xsb_configuration.
		     It stores a lot of information about how XSB was
		     built. This file gets loaded early on, and the info is
		     available to the running XSB programs. No longer you
		     need to use the stat_flag built in --- AND YOU MUST NOT!
		     (Many of the old flags don't even exist any more.)
        xsb_configuration_wind.P  -
	    	     template for configuration.P under Windows NT/95/98.


	Installation_summary
		   - the summary of the installation setup and the make
		     log. We should have a predicate send_bug_report/0,
		     which would take this summary and email to
		     xsb-internal.

	 site/	   - the directory for storing site-specific libraries used 
		     by XSB. For instance, some sites might have packages
		     that are of interest for that specific site, but these 
		     packages might not be in the common XSB execution.
		     This directory can contain the file

			  siteinitrc.P

		     which is loaded by XSB at startup. This allows one to
		     configure XSB for some particular site. For instance,
		     you can add site-specific directories to
		     library_directory.

	 site/lib/ - site-specific .P files that are not dependent on the
		     architecture. 
	 site/<arch>/lib/
		   - site-specific .so files and .P files that ARE
		     dependent on the architecture. 


What Autoconf does:

     It uses some of the above *.in files to create the configure
     script. The configure script is architecture-independent. In fact, it
     whole purpose is to probe the system and find out what the
     architecture is, which libraries/header files exist, etc., etc.

     When distributing XSB, only the *.in files and the generated configure 
     script needs to be included. Autoconf is not required for building XSB.

What the configure script does:

     It probes the system and creates the various make files and *.h files
     mentioned above. The contents of the files depends on the specifics of 
     the system at hand.

How to build:

    In the build/ directory, type:

	configure
	makexsb

    Configure has several options (type `configure --help' to see them all)
    that let you configure for debugging, with Oracle, etc. See ../INSTALL
    for details.  The outcome of running configure and makexsb is stored in
    Installation_summary. This file is sent to

	    xsb-installation@lists.sourceforge.net
    
    by the registration script and it is also saved in
    config/<configuration>/ directory, where <configuration> is the
    canonical name for the current configuration.

    A note about caching the configure tests: caching is disabled (the
    opposite of the standard Autoconf default). To enable it, type

       configure --cache

    This will make configure run much faster.
    However, if you change other options to configure, I recommend that
    --cache shouldn't be used, because configure may use a cached value
    that is different from the one that might be otherwise produced when
    those other options are in effect.

    The top makefile has several useful targets. When you type `makexsb'
    then the executable will be produced and XSB packages will be
    configured.  If you are debugging XSB, waiting for the packages
    is just a waste of time. So, type:

	 makexsb fast

    instead. When you type `makexsb fast' you will not be asked to
    register.

    However, when you just checked out a fresh copy from the XSB repository 
    or if you just ran `cvs update' then you should type 

        makexsb devel

    to rebuild the missing .O files in the XSB installation. (XSB CVS
    repository stores only the very necessary .O files, leaving the rest to 
    be rebuilt by the user.

    Sometimes even this is not enough. When people make changes to the
    compiler (however small they might be), it is necessary to recompile
    all .P files with the new compiler. The way to do this is to type

	makexsb superdevel

    Use this when all else fails. On a slow machine, this can obviously
    take time.

    Here are some other makexsb targets:

             vfast  - Like fast, but gpp is not compiled.
	     clean  - clean out the .o files in emu/ and in
		      config/<arch>/saved.o/ where <arch> is the current
		      architecture. 

	     configclean - wipe out everything in config/<arch>/

	     distclean - wipe out everything in 
			 config/*
			 bin/
			 emu/*.o

	     install - if you configured XSB with the --prefix=DIR option,
		       meaning that you want to install it somewhere else
		       (a copy of the executable will always be available
		       in the source tree as well), then this target will
		       copy the new executable and the .O files from the
		       XSB libraries into the corresponding directories in
		       DIR/<xsb-version>.
		       XSB version is appended so as to not wipe out the
		       earlier installed version (in case there is a
		       trouble with the newly installed version, or if it
		       is desirable to keep the old version for various
		       reasons).

    NOTE: you don't need to run `configure' every time you recompile
	  XSB!  Configure script needs to be run only if you need to build
	  XSB for a different architecture or to use different options
	  (e.g., build for Oracle, build with the debug option, etc.).
	  
	  If the building parameters haven't changed, you only need to
	  remake XSB in order to recompile it.


How to build C-callable XSB module xsbmodule.o:

    configure
    makexsb
    makexsb module

    This will create .../config/<architecture>/saved.o/xsbmodule.o
    You can link it with C programs that call XSB and pass queries to it.
    See a sample Makefile in .../examples/c_calling_XSB.


Development tricks:

    As mentioned before, the present set up allows one to build XSB for
    different architectures from a single source tree without the risk of
    wiping out the object files, etc. This can save a lot of time that
    would otherwise be wasted waiting for things to get compiled.

    The setup also saves all the architecture-specific make files and files 
    that must be included using the #include statement in the C source.
    All these files are automatically copied in the right place when you
    type `makexsb' in the build/ directory.

    One last feature:
	When debugging XSB, it is often necessary to compile it with different
	options. For instance, you might want to compile it with and without
	the Oracle support. The problem is that if you do this on the same
	computer, then (unless you booted to another OS) the object files and
	the executables from the previous compilation will be gone, since
	everything will be stored in the same config/<arch>/ directory.

	To address this, I added the --config-tag option to the configure
	script. If you build XSB using this tag, e.g., 

	   configure --config-tag=ora
	   makexsb --config-tag=ora

	then all configuration-specific files will go into the directory

	    config/<arch>-ora/

	and the results of the earlier build for the same architecture will
	be preserved.

	One problem with this is that the bin/xsb script will be looking for

	    config/<arch>/bin/xsb

	to run the XSB executable for your architecture. Since now it is in
	<arch>-ora instead of <arch>, a wrong executable will be run.

	However, things have been set up in such a way that if XSB was
	configured and compiled with a --config-tag option (e.g., `ora')
	then the smart xsb invocation script will be called xsb-ora. In
	other words, typing

	   bin/xsb-ora

	will run

	   config/<arch>-ora/bin/xsb

	instead of 

	   config/<arch>/bin/xsb


Please contribute any ideas you might have on how to make this setup more
flexible and/or simpler.

Michael Kifer
