################################################################################
#
# Version: Onyx 5.1.1
#
# Building and installation instructions for the Canonware Onyx distribution.
#
################################################################################

Required: This software depends on the excellent 'cook' program for building.
	  'cook' is freely available (GPLed), and runs on many platforms.  For
	  more information, see:

		http://www.canb.auug.org.au/~millerp/cook/cook.html
		http://www.canonware.com/download/cook/

Optional: Regular expression support in Onyx depends on the pcre library.  pcre
	  is distributed separately, and needs to be installed before building
	  this software:

		ftp://ftp.csx.cam.ac.uk/pub/software/programming/pcre/
		http://www.canonware.com/download/pcre/

Optional: Interactive command line editing is implemented in modprompt, which
	  relies on libedit.  libedit is distributed separately, and needs to be
	  installed before building this software:

		ftp://ftp.astron.com:/pub/libedit/
		http://www.canonware.com/download/libedit/

Optional: When running on Apple OS X, module support depends on OpenDarwin's
	  dlcompat shim library, which implements dlopen() and friends.
	  dlcompat is distributed separately, and needs to be installed before
	  building this software:

		http://www.opendarwin.org/projects/dlcompat/
		http://www.canonware.com/download/dlcompat/

Optional: Running the regression tests requires perl.

Optional: Rebuilding the documentation requires LaTeX (teTeX distribution),
	  transfig, latex2html, and perl.  However, the source distribution
	  should come with the documentation already built, so you should not
	  need to do so unless making documentation modifications.

Optional: Regenerating the configure script requires GNU autoconf.

Building this distribution in many cases is as simple as typing the following
while in the root directory of the source tree:

	./configure
	cook

To install, do the above, then type:

	cook install

Additional build targets of finer granularity include:

	bins
	o<binname>
	<binname>
	libs
	libs_[as]
	<libname>
	mods
	<modname>
	tests
	examples

Additional install targets of finer granularity include:

	{bins,libs,mods,docs}_install
	<binname>_bins_install
	libs_install_[ias]
	<libname>_libs_install
	<libname>_libs_install_[ias]
	<modname>_mods_install
	docs_install_{pdf,html}

Uninstall targets include:

	uninstall
	{bins,libs,mods,docs}_uninstall
	<binname>_uninstall
	<libname>_uninstall
	<modname>_uninstall

Cleanup targets include:

	clean
	distclean
	relclean

Targets that depend on optional supporting software include:

	docs
	docs_{pdf,html}
	release
	check
	check_update

Onyx can be configured in a myriad of ways.  The following diagram depicts the
dependencies among optional features.  The configuration system automatically
enforces these dependencies, so if, say, regex is disabled, modules will also be
disabled automatically.

/-----\  /--------\  /-------\  /------------\  /------\  /---------\
| oop |  | handle |  | regex |  | posix_file |  | real |  | inlines |
\-----/  \--------/  \-------/  \------------/  \------/  |  or     |
   ^          ^          ^            ^                   | debug   |
   |          |          |            |                   \---------/
   |          |          |        /-------\
   |          |          |        | posix |               /---------\
   |          |          |        \-------/               | threads |
   |          |          |            ^ ^                 |  or     |
   |          |          |            | |                 | pth     |
   |           \        /             |  \                \---------/
    \           \      /             /    \
     \         /---------\          /   /--------\
      \--------| modules |---------/    | socket |
               \---------/              \--------/
                 ^     ^
                 |     |
       /-----------\  /----------\
       | modprompt |  | modclopt |
       \-----------/  \----------/

The build system is capable of building in a different directory than the
source, so that no files are written to the source tree.  In order to use this
feature, run 'configure' and 'cook' while in the directory that you want to
build the software in.

Optionally, pass any of the following (not a definitive list) arguments to
'configure':

--prefix=<install-root-dir>
	Set the base directory in which to install.  For example:

		./configure --prefix=/usr/local

	will cause files to be installed into /usr/local/bin, /usr/local/man,
	/usr/local/include, /usr/local/lib, and /usr/local/share.

--disable-threads
	Do not support threads.  Specifying this option disables significant
	functionality.  The documentation does not mention the effects of this
	option -- UTSL.

--enable-pth
	Use the GNU pth cooperative threading library rather than POSIX
	threads.  This has some minor impacts on the available functionality.
	For example, periodic garbage collection is not available, and garbage
	collection is synchronous rather than asynchronous.  The documentation
	does not mention the effects of this option -- UTSL.

	To build pth such that it works correctly for libonyx, use something
	like the following to build it:

		./configure --enable-syscall-hard
		make
		make install

--disable-oop
	Do not include support for object-oriented programming.  This excludes
	the "class" and "instance" Onyx types and associated operators.  The
	documentation does not mention the effects of this option -- UTSL.

--disable-handle
	Do not include the "handle" Onyx type, which is used by extensions
	implemented as loadable modules.  The documentation does not mention the
	effects of this option -- UTSL.

--disable-real
	Do not include the "real" Onyx type, which supports double precision
	floating point operations.  The documentation does not mention the
	effects of this option -- UTSL.

--disable-regex
	Do not use include support for regular expressions.  This excludes the
	"regex" and "regsub" Onyx types and associated operators.  The
	documentation does not mention the effects of this option -- UTSL.

	Regular expression support is provided by the PCRE library package,
	which is open source software, written by Philip Hazel, and copyright
	by the University of Cambridge, England.

--disable-posix
	As much as reasonably possible, avoid using any external library
	functions (disjoint from --disable-threads option).  This option is
	useful when embedding onyx in an application where libc isn't available.
	Specifying this option disables significant functionality.  The
	documentation does not mention the effects of this option -- UTSL.

--disable-posix-file
	As much as possible, avoid using POSIX file operations (open(), close(),
	read(), write()).  This option is useful when embedding Onyx in an
	application that does not have complete I/O capabilities.  With the
	exception of calls to printf() and fprintf(stderr, ...) in debug
	versions of libonyx, no POSIX file operations are used.  The
	documentation does not mention the effects of this option -- UTSL.

--disable-socket
	Do not include networking socket support.  The documentation does not
	mention the effects of this option -- UTSL.

--disable-modules
	Do not include support for dynamically loadable modules.  This leaves
	out modload, require, and mrequire.  The documentation does not mention
	the effects of this option -- UTSL.

--disable-modprompt
	Do not build the prompt module, which provides command line editing
	functionality for interactive invocations of onyx.  There is little
	benefit to disabling modprompt under normal circumstances, since there
	is virtually no overhead involved for non-interactive invocations of
	onyx (less than 50 bytes).  The documentation does not mention the
	effects of this option.

--disable-modclopt
	Do not build the clopt module, which provides command line option
	parsing.  The documentation does not mention the effects of this option.

--enable-debug
	Build debugging code and turn assertions on (controlled by the CW_ASSERT
	cpp macro).  The resulting libraries and modules will not be binary
	compatible with ones that were compiled without this option, so
	specifying this option and installing the results for general use is not
	recommended.

--disable-inlines
	Do not use inline functions.  This reduces the size of binaries at the
	expense of performance.

--enable-autogen
	Include dependency rules in the build system to automatically regenerate
	files created by configure when their sources are newer.  This is
	only of interest when making modifications to the source code.

--with-docs
	Enable build system rules to build the documentation.  Unless this
	option is specified, the build system assumes that pre-built
	documentation resides in the source directory (which is the case for all
	Onyx distributions).  Note that the documentation lands in the objdir,
	so in order to completely empty the objdir, the relclean target must be
	used.  This option is only useful when modifications have been made to
	the documentation source.

--with-host-cc=<cc>
	If specified, use <cc> as the host compiler.  This needs to be specified
	if cross compiling, since bootstrapping the onyx interpreter must be
	done on the host.

--with-target-cc=<cc>
	If specified, use <cc> as the target compiler, which generates the final
	binaries.

--with-pcre-prefix=<prefix>
	If specified, libonyx will be built using the copy of pcre in <prefix>.
	Specifically, <prefix>/bin/pcre-config will be used to determine the
	appropriate compiler and linker flags.

	This option should only be necessary when <prefix>/bin is not in the
	shell's PATH.  This option does not provide a mechanism to choose
	between multiple installations of pcre.

--with-libedit-prefix=<prefix>
	If specified, modprompt will be built using the copy of libedit in
	<prefix>.  Specifically, the following will be used when compiling and
	linking modprompt:

		* Compiling: -I<prefix>/include
		* Linking: -L<prefix>/lib

	In addition, if building on a system that requires that the library
	search path be encoded in modprompt, the link line will also include
	something like:

		-Wl,-rpath,<prefix>/lib

	This option should only be necessary when there are multiple versions of
	libedit installed on the system, and the desired version does not come
	first in the default library search path, or if the library is not in
	the default library search path.

Optionally, define environment variables when invoking configure, including (not
exclusively):

CFLAGS="?"
	Pass these flags to the compiler.  You probably shouldn't define this
	unless you know what you are doing.

EXTRA_CFLAGS="?"
	Append these flags to CFLAGS.  This makes it possible to add flags such
	as -Werror, while allowing the configure script to determine what other
	flags are appropriate for the specified configuration.

	The configure script specifically checks whether an optimization (-O*)
	flag is specified in EXTRA_CFLAGS, and refrains from specifying an
	optimization level if it finds that one has already been specified in
	EXTRA_CFLAGS.

CPPFLAGS="?"
	Pass these flags to the C preprocessor.  Note that CFLAGS is not passed
	to 'cpp' when 'configure' is looking for include files, so you must use
	CPPFLAGS instead if you need to help 'configure' find header files.

LD_LIBRARY_PATH="?"
	'ld' uses this colon-separated list to find libraries.

LDFLAGS="?"
	Pass these flags when linking.

PATH="?"
	'configure' uses this to find programs.

Optionally, define cook variables when invoking cook, including (not
exclusively):

PREFIX="?"
	Use this as the installation prefix.

BINDIR="?"
	Use this as the installation prefix for programs.

DATADIR="?"
	Use this as the installation prefix for modules and documentation.

LIBDIR="?"
	Use this as the installation prefix for libraries.

INCLUDEDIR="?"
	Use this as the installation prefix for header files.

MANDIR="?"
	Use this as the installation prefix for man pages.

HCC="?"
	Use this to invoke the host C compiler (used for building a bootstrap
	Onyx interpreter).

TCC="?"
	Use this to invoke the target C compiler.

CFLAGS="?"
	Pass these flags to the compiler.

CPPFLAGS="?"
	Pass these flags to the C preprocessor.

LDFLAGS="?"
	Pass these flags when linking.

PATH="?"
	Use this to search for programs used during configuration and building.
