# OpenSS7 Linux Fast STREAMS -- NexusWare procedures.  2006-01-03
# README-nexusware,v 0.9.2.2 2006/01/03 16:21:41 brian Exp
# Copyright (c) 2001-2006  OpenSS7 Corporation. <http://www.openss7.com/>
# Copyright (c) 1997-2000  Brian Bidulock <bidulock@openss7.org>
# See the end for copying conditions.

The following is an extract from the manual to assist NexusWare developers:

6.3.3 Building from the Tar Ball
--------------------------------

If you have downloaded the tar ball (*note Downloading the Tar Ball::), then the
following instructions will rebuild the package on your system.  (Note that the
build process does not required `root' privilege.)

6.3.3.1 Native Build
....................

Folowing is an example of a native build against the running kernel:

     % wget http://www.openss7.org/streams-0.7a.4.tar.bz2
     % tar -xjvf streams-0.7a.4.tar.bz2
     % pushd streams-0.7a.4
     % ./configure
     % make
     % popd

6.3.3.2 Cross-Build
...................

Following is an example for a cross-build.  The kernel release version must
always be specified for a cross-build.(1)  If you are cross-building, specify
the root for the build with environment variable DESTDIR.  The cross-compile
host must also be specified if different from the build host.  Either the
compiler and other tools must be in the usual places where GNU `autoconf' can
find them, or they must be specified with declarations such as
`CC=/u5/NexusWare24/ppc-linux/gcc' on the `configure' command line.  Look in
the file `configure.nexusware' in the release package for an example.

     % wget http://www.openss7.org/streams-0.7a.4.tar.bz2
     % tar -xjvf streams-0.7a.4.tar.bz2
     % pushd streams-0.7a.4
     % ./configure DESTDIR="/some/other/root" \
     	--with-k-release=2.4.18 --host sparc-linux
     % make
     % popd

6.3.3.3 NexusWare Build
.......................

Additional support is provided for cross-building for the `Performance
Technologies Inc.' `NexusWare' embedded target for the CPC-384, CPC-388 and
CPC-396 cards.  A configuration script wrapper (`configure.nexusware') is
provided to simplify the cross-build operation for these targets.  The following
steps describe the process:

  1. Follow the normal `NexusWare' instructions for rebuilding a `generic'
     kernel and flash image as follows:  (Note that I keep my `NexusWare' build
     in `/u5/NexusWare24'.)

          % pushd /u5/NexusWare24
          % source SETUP.sh
          % make
          % popd

     For more recent `NexusWare' releases, the method for rebuilding a kernel
     is a little different as follows:

          % pushd /u5/NexusWare80
          % ./nexus 2.4
          % ./nexus 8260
          % ./nexus quick
          % . SETUP.sh
          % popd

  2. Next download, unpack (*note Downloading the Tar Ball::) and configure
     (*note Configuring the Tar Ball::) using the provided
     `configure.nexusware' wrapper for `configure'.  This wrapper simply tells
     the `configure' script where to find the `NexusWare' sources and which
     `NexusWare' cross-building tools to use for a cross-compile.(2)

     Any of the normal `configure' script options (*note Configuring the Tar
     Ball::) can be used on the same line as `./configure.nexusware'.  One of
     particular interest to embedded targets is `--with-k-optimize=size' to
     attempt to reduce the size of the kernel modules.

     You must specify the kernel version of the kernel for which you are
     configuring.  Add the -with-k-release=2.4.18 option for older `NexusWare'
     releases, -with-k-release=2.4.25 or -with-k-release=2.6.12 for more current
     `NexusWare' releases.

  3. Install as normal (*note Installing the Tar Ball::), however, for embedded
     targets the `install-strip' target should be used instead of the `install'
     target.  The `install-strip' target will strip unnecessary symbols from
     kernel modules and further reduce the size in the root file system flash
     image.


Following is what I use for configuration and installation: (My `NexusWare'
tree is rooted at `/u5/NexusWare'.)

     % pushd /u5/NexusWare80
     % ./nexus 2.4
     % ./nexus 8260
     % ./nexus quick
     % . SETUP.sh
     % popd
     % wget http://www.openss7.org/streams-0.7a.4.tar.bz2
     % tar -xjvf streams-0.7a.4.tar.bz2
     % pushd streams-0.7a.4
     % ./configure.nexusware --with-k-release=2.4.25 --with-k-optimize=size
     % make
     % make DESTDIR="$NEXUSWARE_PREFIX" install-strip
     % popd

Once built and installed in the `NexusWare' directory, you will have to
(currently) hand edit a `.spec' file to include the components you want in the
`NexusWare' root file system.  If you are cross-building for `NexusWare' you
should already know what that means.  Objects that you might be interested in
copying to the root file system are kernel modules that were installed in
`$NEXUSWARE_PREFIX/lib/modules/2.4.18/streams', libraries installed in
`$NEXUSWARE_PREFIX/usr/lib' and utility functions installed in
`$NEXUSWARE_PREFIX/usr/bin' and `$NEXUSWARE_PREFIX/usr/sbin' and test programs
in `$NEXUSWARE_PREFIX/usr/libexec'.  If you would prefer that these programs be
installed in `$NEXUSWARE_PREFIX/lib', `$NEXUSWARE_PREFIX/bin',
`$NEXUSWARE_PREFIX/sbin' and `$NEXUSWARE_PREFIX/libexec', (say because you want
to remote mount the `/usr' directory after boot), then specify the
`--exec-prefix=/' option to `./configure.nexusware'.

In addition, because `NexusWare' does not include an `/etc/modules.conf' file
by default, it will be necessary to add one or edit your `rc.4' file to
`insmod' the necessary `streams' modules at boot time.  Also, `NexusWare' does
not configure its kernels for CONFIG_KMOD, so any kernel modules must be loaded
by the `rc.4' init script at boot.  On more recent `NexusWare' releases, the
init scripts will be installed in `$NEXUSWARE_PREFIX/etc/rc.d/init.d/' but you
must manually edit your `rc.4' script to invoke these scripts.

Once you have completed the necessary `.spec' and `rc.4' file entries, you need
to rebuild the `generic' kernel flash image once more for these objects to be
included in the flash file system.  It is important that this second build of
the kernel image be the same as the first.

When modifying and rebuilding a `NexusWare' kernel, it will be necessary to
rebuild and install `streams'.  Simply perform the last `make install-strip'
stage or start again with `./configure.nexusware'.  You can place the unpacked
tarball in `$NEXUSWARE_PREFIX/usr/src/streams', and add the following to the
top-level `NexusWare' `Makefile' to make the build process a single step
process instead of dual pass:

     all:
     ...
             (cd kernels/generic; $(MAKE) depend)
             (cd usr/src/pcmcia-cs-3.2.1; $(MAKE) config)
             (cd kernels/generic; $(MAKE))
             (cd usr/src/pcmcia-cs-3.2.1; $(MAKE) pti)
             (cd usr/src/pti; $(MAKE))
             (cd drivers; $(MAKE))
             (cd utility; $(MAKE))
     #       uncomment for streams build
     #       (cd usr/src/streams; ./configure.nexusware; $(MAKE) install-strip)
             (cd build/generic; $(MAKE))
     ...

Another, perhaps simpler approach, is to make the necessary edits to the
`NexusWare' top-level `Makefile' and `.spec' and `rc.4' files, download and
unpack the tar ball into the `NexusWare' directory, and build the `NexusWare'
flash image as normal:

     % wget http://www.openss7.org/streams-0.7a.4.tar.bz2
     % pushd /u5/NexusWare24
     % source SETUP.sh
     % pushd usr/src
     % tar -xjvf ${DIRSTACK[2]}/streams-0.7a.4.tar.bz2
     % ln -sf streams-0.7a.4 streams
     % popd
     % make
     % popd

The situation is a little more complex for recent `NexusWare' releases.

---------- Footnotes ----------

(1) Because it _is_ a cross-build, the kernel version on the build machine is
unlikely to be the kernel version of the target machine, except by coincidence.

(2) Although I have not tried it, because we use GNU `autoconf' for
configuration, these instructions should work equally well for the Solaris
`NexusWare' cross-building environment as it does for the Linux `NexusWare'
cross-building environment.



=========================================================================

Copyright (c) 2001-2006  OpenSS7 Corporation. <http://www.openss7.com/>
Copyright (c) 1997-2000  Brian Bidulock <bidulock@openss7.org>

All Rights Reserved.

 Permission is granted to make and distribute verbatim copies of this
 manual provided the copyright notice and this permission notice are
 preserved on all copies.

 Permission is granted to copy and distribute modified versions of this
 manual under the conditions for verbatim copying, provided that the
 entire resulting derived work is distributed under the terms of a
 permission notice identical to this one

 Since the Linux kernel and libraries are constantly changing, this
 manual page may be incorrect or out-of-date.  The author(s) assume no
 responsibility for errors or omissions, or for damages resulting from
 the use of the information contained herein.  The author(s) may not
 have taken the same level of care in the production of this manual,
 which is licensed free of charge, as they might when working
 professionally.

 Formatted or processed versions of this manual, if unaccompanied by
 the source, must acknowledge the copyright and authors of this work.

-------------------------------------------------------------------------

 U.S. GOVERNMENT RESTRICTED RIGHTS.  If you are licensing this Software
 on behalf of the U.S. Government ("Government"), the following
 provisions apply to you.  If the Software is supplied by the Department
 of Defense ("DoD"), it is classified as "Commercial Computer Software"
 under paragraph 252.227-7014 of the DoD Supplement to the Federal
 Acquisition Regulations ("DFARS") (or any successor regulations) and the
 Government is acquiring only the license rights granted herein (the
 license rights customarily provided to non-Government users).  If the
 Software is supplied to any unit or agency of the Government other than
 DoD, it is classified as "Restricted Computer Software" and the
 Government's rights in the Software are defined in paragraph 52.227-19
 of the Federal Acquisition Regulations ("FAR") (or any successor
 regulations) or, in the cases of NASA, in paragraph 18.52.227-86 of the
 NASA Supplement to the FAR (or any successor regulations).

=========================================================================

 Commercial licensing and support of this software is available from
 OpenSS7 Corporation at a fee.  See http://www.openss7.com/

=========================================================================
