OpenSS7 STREAMS Utilities -- read me CVS file.  2007-06-24
$Id$
Copyright (c) 2001-2007  OpenSS7 Corporation. <http://www.openss7.com/>
Copyright (c) 1997-2000  Brian Bidulock <bidulock@openss7.org>
See the end for copying conditions (for this file).

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 (see `Downloading the Tar Ball', in
the manual), 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
....................

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

     % wget http://www.openss7.org/strutil-0.9.2.6.tar.bz2
     % tar -xjvf strutil-0.9.2.6.tar.bz2
     % pushd strutil-0.9.2.6
     % ./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(1)' 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/strutil-0.9.2.6.tar.bz2
     % tar -xjvf strutil-0.9.2.6.tar.bz2
     % pushd strutil-0.9.2.6
     % ./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 (see `Downloading the Tar Ball', in the
     manual) and configure (see `Configuring the Tar Ball', in the
     manual) 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 (see `Configuring the
     Tar Ball', in the manual) 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 (see `Installing the Tar Ball', in the manual),
     however, for embedded targets the `install-strip' `automake(1)'
     target should be used instead of the `install' `automake(1)'
     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/strutil-0.9.2.6.tar.bz2
     % tar -xjvf strutil-0.9.2.6.tar.bz2
     % pushd strutil-0.9.2.6
     % ./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/strutil', 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'.

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(8)'
the necessary `strutil' modules at boot time.

`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 `strutil'.  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/strutil', 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 LiS build
     #       (cd usr/src/LiS; ./configure.nexusware; $(MAKE) install-strip)
     #       uncomment for LfS build
             (cd usr/src/streams; ./configure.nexusware; $(MAKE) install-strip)
     #       uncomment for strutil build
     #       (cd usr/src/strutil; ./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/strutil-0.9.2.6.tar.bz2
     % pushd /u5/NexusWare24
     % source SETUP.sh
     % pushd usr/src
     % tar -xjvf ${DIRSTACK[2]}/strutil-0.9.2.6.tar.bz2
     % ln -sf strutil-0.9.2.6 strutil
     % 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(1)' 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-2007  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/

=========================================================================
vim: ft=README tw=72 nocindent nosmartindent formatoptions+=tcqlorn
