INSTALL
*******

In the past I have built this tree on NetBSD (i386,sparc), FreeBSD,
SunOS, Solaris (sparc,x86).  I have also built much of it (*many* years
ago) on Linux, HP-UX, IRIX and Ultrix.

More recently it has been tested on NetBSD, FreeBSD, Darwin [#]_ and SunOS.

.. [#] with the exception of stn3270.

Feedback and patches are always welcome.

The sandbox (``$SB``)
=====================

The build instructions have been greatly simplified by using the
sandbox model.  A sandbox is just a tree which has a file
``.sandbox-env`` at the top, which serves to both mark the top of the
tree and provide a means of conditioning the environment.

mk
--

A simple wrapper script (``scripts/mk``) is provided, which finds
``.sandbox-env`` reads it and ``.sandboxrc`` if it exists, and then
invokes ``make``. Actually it invokes::

	exec ${REAL_MAKE:-${MAKE:-make}} "$@"

Note that this script starts with ``#!/bin/sh`` to allow for
exec(2).  On some systems ``/bin/sh`` isn't sufficient.  For these we
have exec-shell.sh_

exec-shell.sh
~~~~~~~~~~~~~

This script creates a wrapper to exec scripts via a chosen shell.

We provide ``sunos/mk`` and ``hp-ux/mk``.  If your ``/bin/sh`` chokes
on ``mk`` then use::

	exec-shell.sh shell=/bin/ksh mk

to create a suitable wrapper script.  Obviously specify a shell which
you have and that works.  For example ``sunos/mk``::

	#!/bin/sh
	script=`echo $0 | sed 's,sunos/,,'`
	exec /usr/xpg4/bin/sh $script "$@"

You could of course just edit ``mk`` to start with the correct ``#!``
path for your OS but that needs to be re-done each time you update,
and is only viable if you are not sharing the src tree on multiple
system types.

bmake
=====

Unless you are running a *recent* NetBSD_, you must build bmake_
which is a portable version of NetBSD's make and tracks it closely (I
am one of the maintainers of NetBSD make).

This tree is designed to be built with bmake and with support for
multiple architectures.  GNU autoconf is used to generate a config.h which
handles most system dependencies, but the Makefiles rely on bmake.
Fortunately bmake_  uses autoconf :-)

Building bmake
--------------

Building bmake is trivial::

	$ tar zxf ~/bmake.tar.gz
	$ tar zxf ~/mk.tar.gz
	$ ./bmake/boot-strap

is all I use, and it will print out the commands needed to install
bmake and the mk macros.

Note: I have the following in ``~/.bmake-boot-strap.rc``
which keeps the above simple::

	:
	echo "Building for $HOST_TARGET"
	case "$HOST_TARGET" in
	netbsd*) sys_share_mk=:/usr/share/mk;;
	sunos*) sys_share_mk=
		CC=`type gcc | sed 's,^[^/]*,,'`
	        export CC
		;;
	*)	sys_share_mk=;;
	esac
	objdir=./$HOST_TARGET
	case "$prefix" in
	*/$HOST_TARGET) 
        	CONFIGURE_ARGS="$CONFIGURE_ARGS --with-default-sys-path=$prefix/share/mk:`dirname $prefix`/share/mk$sys_share_mk"
        	;;
	esac


Makefiles
=========

The Makefiles want to know where the top level directory is.
The easy way to do this is with the mk_ wrapper mentioned above.

These Makefiles use my own macro files which were originally derived from the
NetBSD (1.0?) bsd.*.mk macros.  You can put them where ever you like
and set the location in ``$MAKESYSPATH`` in ``$SB/.sandbox-env``.
The default location is ``$SB/mk``

We default the macro ``NOMAN=no`` to suppress formatting of man pages.
You can override this if you have the BSD mandoc macros for [nt]roff.

Macro files
===========

A couple of my `macro files`_  differ from the bsd.* originals (apart from
being more portable), man.mk handles installing unformatted nroff, as
well as formatted pages with the normal extension rather than BSD's .0

Unless SUBDIR_MUST_EXIST is defined, subdir.mk will skip missing
subdirs (after telling you...) rather than die.  This is important,
since you very likely have a subset of the full src tree.


Building
========

In various directories, you may find symlinks named
``src`` pointing off to no where.  These should point to the
directories holding the appropriate distribution.  For instance::

	$ ls -l ssl/bin/rdist/src
	lrwxrwxr-x  1 sjg  wheel  17 Jun 20  1996 ssl/bin/rdist/src@ -> ../../../../rdist-6.1.3
	$ 

Obviously you will need these links correct before you can expect to
build things like SSLrdist.  See `other distributions`_ 
for details on where to get the other distributions you might need.

Now just::

	$ PATH=$PATH:$SB/scripts
	$ cd $SB
	$ mk
	# mk install

MAKECONF
--------

The distributed ``$SB/.sandbox-env`` sets ``MAKECONF=$SB/Makefile.inc``
so that will always be read by prog and lib makefiles.

Makefile.local.inc
~~~~~~~~~~~~~~~~~~

You can put customized settings in ``$SB/Makefile.local.inc``
which will be read by ``$SB/Makefile.inc``.  For example::

	# gcc, but an old version
	USE_AUTODEP_MK=no
	USE_DMALLOC?=no
	USE_DBUG?=no
	USE_DPADD_MK=yes
	WARNINGS_SET?=MIN


mkdep
-----

If you run ``mk depend``, the macros will use ${MKDEP}
(default is /usr/bin/mkdep or mkdeps.sh_)
If you don't have either skip the ``mk depend`` step.
Also see autodep.mk_

autodep.mk
----------

If you have a *recent* gcc, you can set ``USE_AUTODEP_MK=yes``
and autodep.mk will automagically update dependencies as and when
files are compiled.

object dirs
-----------

Note that I *always* use object dirs to keep the build tree neat
and facilitate build/editing within emacs while sharing the src via
NFS.

The ``.sandbox-env`` file included in the distribution turns this on
automatically::

	SB_SRC=$SB
	SB_NAME=`basename $SB`
	SRCTOP=$SB
	OBJTOP=${MAKEOBJDIRPREFIX:-/var/obj/$SB_NAME}
	MAKEOBJDIR='${.CURDIR:S,${SRCTOP},${OBJTOP},}'
	MKOBJDIRS=auto
	MAKECONF=$SB/Makefile.inc
	MAKESYSPATH=$SB/mk
	if [ -s /netbsd ]; then
		BMAKE=${BMAKE:-make}
	else
		BMAKE=${BMAKE:-$HOME/$HOST_TARGET/bin/bmake}
	fi
	REAL_MAKE=${BMAKE:-bmake}
	# we only need these if using the full mk version.
	SB_PROJECT=sjg
	SB_PATH=${PATH:-/usr/bin:/bin:/usr/sbin:/sbin:/usr/pkg/bin:/usr/local/bin}
	# on many "modern" systems /bin/sh is not posix compliant
	# so we avoid export VAR=value
	unset  MAKEOBJDIRPREFIX
	export SB_SRC SB_NAME 
	export SRCTOP OBJTOP
	export MAKESYSPATH MAKECONF MAKEOBJDIR
	export MKOBJDIRS
	export REAL_MAKE

The above allows you to override OBJTOP by simply setting ``MAKEOBJDIRPREFIX``.
You will need that if you do not have permissions to creat dirs in ``/var``

.. warning:: If you disable auto objdirs and skip making of obj dirs,
   don't be surprised when the build fails in subtle ways.

shared libraries
----------------

The lib.mk macros know how to build shared libraries on NetBSD,
FreeBSD, Darwin, SunOS, Solaris, HP-UX and OSF/1.

For other systems lib.mk will use the GNU libtool if you have it 
and set ``USE_LIBTOOL=yes`` though this is a bit more limited.
(Actually I haven't tested use of libtool in a long time ;-)

If you do not want shared libraries built, either set NOPIC
in Makefile.local.inc or on the command line, or create .nopic in the src
or obj directories  concerned.

Alternatively if NOARCHIVE is set you can skip building the archive
libraries and use just the shared libs. This can save considerable
time on non-development systems.

symlinks
~~~~~~~~

Note that on ELF systems (eg. Solaris, Linux, and recent BSD's)
you need to make a symlink like::

	# ln -s /usr/local/lib/libsslfd.so.0.3 /usr/local/lib/libsslfd.so.0

Before the libraries are really usable.  ELF systems do not really
handle shared lib versioning the way that BSD and SunOS used to do, so
we give it just the major version number to look for.  Also, in order
to link against a shared lib on an ELF you need to create a link
like::

	# ln -s libsslfd.so.0.3 libsslfd.so

On HP-UX you need to ensure that shared libs are executable! 

SSL
===

The ssl tree here now expects OpenSSL to be already installed, it will
try to guess where but you may need to set INCLUDES_libcrypto in
local.libnames.mk 

.. sidebar:: Building OpenSSL

   The OpenSSL distribution is still pretty crude when it comes to
   building - which is why I originally provided an alternative means
   of building it (later incorporated into NetBSD).

   If you were desperate, you could grab the Makefiles from NetBSD and
   they should work with minor tweaking.


Example
=======

An example usually helps. The following assumes that OpenSSL has been
built and installed.

First unpack all the packages in a single tree such as
``~/work/sjg`` (this will be ``$SB``)::

	$ mkdir -p ~/work/sjg
	$ cd ~/work/sjg
	$ gzcat /tmp/bmake.tar.gz | tar xvf -
	$ gzcat /tmp/mk.tar.gz | tar xvf -
	$ gzcat /tmp/SSLrsh.tar.gz | tar xvf -
	..
	..

Note: if you have already installed bmake_ you do not need to unpack
it in ``$SB``.

Also note that if you want to support sharing read-only src via NFS
ensure that ``.sandbox-env`` sets ``OBJTOP=/var/obj/$SB_NAME`` or similar.

You will likely need to be root to install anything as the install
macros use chown which is usually restricted to root::

	# mk install

If you want to force installing without chown etc::

	$ mk install BINOWN= LIBOWN=

breakage
========

It is highly likely that your source tree is a small subset of ours.
We have taken steps to try and ensure that the build will work for you
despite this, but we may have missed something.

It is also possible (likely) that newer OS versions can introduce new
hiccups - especially since much of the code in telnet for example is
pretty old.

In general it is safest to start with a clean tree.  If you have
unpacked previous versions of SSLrsh.tar you may have Makefiles
or headers present that are not in the current release and will cause
you problems.  

------

.. _`macro files`: mk-files.htm
.. _bmake: bmake.htm
.. _NetBSD: http://www.netbsd.org/
.. _`other distributions`: other.html
.. _mkdeps.sh: http://www.crufty.net/ftp/pub/sjg/mkdeps.sh

:Author: sjg@crufty.net
:Revision: $Id: install.txt,v 1.15 2010/01/05 17:02:00 sjg Exp $
:Copyright: Crufty.NET
