
===================================================
README on GNU for HP-UX 9.00 v1.0 Package (02/2014)
===================================================


I. Introduction
===============

Unfortunately, the vanilla HP-UX 9.00 installation lacks HP's complete SoftBench
development environment. Only those tools which are required to re-build the
kernel (e.g. for installing new drivers or configuring kernel properties) are on
board, such as the HP-UX link editor or the assembler, and even the baseline
debugger adb.

Also, HP has spent a crippled so-called 'bundled' Kerninghan & Richie C
compiler, which lacks support for many important development features such as
ANSI C, c89, generating debug information or performing code optimization.
Advanced programming tools such as a symbolic debugger, a profiler or an
integrated development environment with program editor are totally missing. As a
consequence, there are just a view source code packages which really can be
built with this highly restricted configuration.

Moreover, there is only a stripped-down run-time X Windows system with Motif
provided, which lacks many client programs and fonts, and also most header files
for developing your own X Windows applications are missing. X Windows libraries
including the Motif 1.2 toolkit are present only as shared libraries.

However, from the well-known GNU project and other sources there are perfect
replacements available, with the GNU compiler collection (gcc) as core
component. Actually, today most Unix-like systems utilize gcc together with a
large number of supporting tools instead of developing own compilers. GNU tools
in general not just substitute native tools, but also provide additional
functionality, which again can boost productivity. Also, HP-UX is missing a
couple of standard run-time environments such as perl or tcl/tk.

HP provides current HP-UX 11.x ports of GNU packages from its Porting &
Archiving Centre (see http://hpux.connect.org.uk/hppd/hpux/Gnu/ for downloads).
However, those packages are of course of no use for HP-UX 9.0x.

So starting with a plain vanilla HP-UX 9.00 installation, I tried to make those
GNU software toolsets available for HP-UX 9.00 on HP 9000 Series 300 (or shortly
HP300) with Motorola MC68k architecture as a productivity add-on for software
development and for compiling ready-to-use source code packages on your own.

I used the bundled C compiler which is included in the vanilla HP-UX 9.00
installation for bootstrapping the gcc compiler collection, which again is used
for compiling all the other tools. Also I have re-built the full X11R5/Motif1.2
package for HP-UX 9.00 and provided many of the components which are missing in
the standard run-time HP-UX 9.00 installation.

Please note that the program versions of the diverse GNU tools in this GNU for
HP-UX 9.00 package in general are not the most recent ones as available from the
GNU FTP server. Reason behind is that system resources of hosts running HP-UX
9.00 with a Motorola MC68k are quite limited, so we have to find the right
trade-off between implementing the latest in features & technology, and being
alright with the amount of memory and the processing power of those systems
which became obsolete about 15 or more years ago. So the versions go back to the
time anywhere between 1999 and 2014.

I tried to find a sound compilation of stable releases covering the most
important features but still using as few system resources as possible. But I am
by far not sure that I have really identified the best versions. So you are
welcome to try compiling other GNU packages and find even better solutions.


II. Special Notes on Release 1.0
--------------------------------

This is the very first release, so don't expect everything to be perfect. For
example, there is still room for making the GNU packages a more compact by
compiling with shared libraries, using compressed MAN pages, or dropping some of
the contribution files which might not be essential (such as NLS support).

If there had been tests provided with the packages, I have run them to make sure
the newly built tools are in general working in the HP-UX 9.00 environment. A
few tests for autoconf and automake still fail (10 of 600 or so), mostly because
of wrong exit codes when intentially feeding the tools with invalid data.


Package Contents
----------------

gnu-hpux9.00-v1.0.tar.Z:

   autoconf 2.59        (2003)  package for generating configuration scripts
   automake 1.9.5       (2005)  package for generating Makefile.in files
   bash 3.2.0           (2005)  replacement shell with many combined features
   binutils 2.16.1a*/** (2005)  GNU utilities for binaries (gas, ld, ar etc.)
   bison 1.29           (2001)  replacement for yacc compiler compiler
   bzip2 1.0.6          (2010)  decent compression tool
   diffutils 2.8        (2002)  utilities related for finding file differences
   dejagnu 1.4.4        (2004)  test framework
   flex 2.5.4a          (1997)  replacement for Lex lexcival analyzer generator
   gawk 3.1.0           (2001)  replacement for Awk text processing & reporting
   gcc 2.95.3***        (2001)  GNU compiler collection
   gdb 5.2.1*           (2001)  GNU project debugger
   gettext 0.10.40      (2001)  internationalization & localization system
   gperf 3.0.1          (2003)  perfect hash function generator
   gzip 1.3.9           (2006)  common compression tool
   help2man 1.25        (2001)  resemble a standard man page from help output
   indent 2.2.9         (2002)  converts different C programming styles
   less 382             (2002)  feature rich replacement for the 'more' pager
   libjpeg 9a           (2014)  library for operations on JPEG images
   libpng 1.0.60        (2012)  library for operations on PNG images
   libTIFF 3.8.2        (2006)  library for operations on TIFF images
   libungif 4.1.4       (2005)  library for operations on GIF images
   libXpm 3.5.4.2       (2005)  library for operations on X pixmap images
   m4 1.4.6             (2006)  implementation of the M4 macro processor
   make 3.78.1          (1999)  replacement for the standard build tool
   patch 2.5.9          (2003)  utility for applying patch files
   pkgconfig 0.20       (2005)  script for generating build flags
   sed 4.0.7            (2003)  replacement for sed text filter utility
   tar 1.14             (2004)  replacement for tar tape archive utility
   tcl 8.4.4            (2003)  implementation of the TCL tool command language
   termcap 1.3.1        (2002)  GNU termcap library
   texinfo 4.9          (2007)  generate different doc formats from one source
   tk 8.4.4             (2003)  widget framework for creating GUIs
   wget 1.11.4          (2008)  retrieve files using HTTP, HTTPS and FTP
   zlib 1.2.8           (2013)  general purpose data compression library
  
   *)   last version officially supporting hp300
   **)  including bfd, ar, ranlib, gas, ld, gprof, nm, strip etc.
   ***) C & C++ only (no objective-C, f77, Ada)
  
  
emacs-hpux9.00-v1.0.tar.Z:
 
   emacs 21.4.1         (2002)  rich & extensible text editing environment

   All emacs binaries have been compiled with gcc.


perl-hpux9.00-v1.0.tar.Z:
 
   perl 5.5.4           (2004)  implementation of the Perl programming language

   All perl binaries have been compiled with gcc.


x11r5-hpux9.00-v1.0.tar.Z:
 
   X11R5                (1991)  additional client programs
   X11R5                (1991)  header files
   X11R5                (1991)  static libraries
   X11R5                (1991)  additional lib files
   Xaw3d 1.5E           (2001)  3D version of Athena toolkit

   All binaries have been compiled with native-gcc (so being compatible to
   HP-UX native cc/ld/ar etc.) and all executables are dynamically linked
   to already existing HP-UX shared libraries.


motif1.2-hpux9.00-v1.0.tar.Z:

   Motif 1.2            (1991)  header files
   Motif 1.2            (2001)  static libraries (LessTif)
  
   Static libraries are built from LessTif 0.93.14 due to license restrictions.

   All Motif binaries have been compiled with native-gcc (so being compatible
   to HP-UX native cc/ld/ar etc.).  


All packages have been built on this reference system:

   System:    HP 9000/385
   CPU:       MC68040 (33MHz)
   RAM:       48 MB
   Graphics:  98545A (1024x768, 16 Colors)
   HDD:       SCSI (1GB)
   Network:   10 MBit Ethernet (AUI)
  
That configuration represents some kind of "high end" within HP 9000 Series 300
and is perfectly suited for building the packages since it speeds up develop &
build processes significantly. Of course you don't need that processing power
for just using the package.

Unfortunately I have no HP 9000 Series 300 with MC68020 or MC68030 available, so
I rely on the experience of others for testing on those more restricted
platforms.


III. Prerequisites & Preparations
=================================

System Requirements
-------------------

The current GNU package for HP-UX 9.00 is intended for any HP300 system with
Motorola MC68k family processor except 68000 and 68010, but including the
MC68020, MC68030 and MC68040 with or without MC68881 or MC68882 floating point
coprocessor. Actually, neither MC68000 nor MC68010 processors are supported by
HP-UX 9.00 anyway, so there also is no support within the GNU package for HP-UX
9.00.

You will need at least 200 MB of free hard disc space for the GNU utilities, 120
MB for emacs, 24 MB for perl and 30 MB for the X11R5 & Motif 1.2 add-ons. Or 374
MB for all the packages.

SCSI or fast HP-IB is recommended, but standard HP-IB also works. Superuser
(root) privileges are required for installing the X11R5 & Motif 1.2 add-ons.


Preparations
------------

It can happen that the default HP-UX kernel memory configuration prevents
running some of the programs. In that case, increase the kernel parameter
'maxdsiz' for the data segment with HP-UX' SAM utility (must be superuser) and
rebuild the kernel afterwards. Some large packages may need a value of up to
0x08000000 (=128 MB). Please note that shell memory errors require different
handling (see section "Compiling Your Own Packages" below).

You will need a way to transfer the package to your HP-UX system. Easiest way is
to use FTP or to mount a remote share via NFS. Both will require a LAN interface
installed in the HP-UX system. Another common way would be to attach a removable
mass storage medium with the installation package on it and install it from
there. Of course also the HPDrive mass storage emulator can be used for that
purpose (see http://www.hp9845.net/hp9845/projects/hpdrive). A prepared hpi
image is available for being mounted under HP-UX, so that the installation can
be done from there.


Mounting with HPDrive
---------------------

If you are already using HPDrive for the HP-UX system disk (e.g. emulating a
C2203 CS/80 hard disk drive), simply add the hpi image as a second unit, such as

  hpdrive -d -C2203 -n 2 <your-system-disk-image> gnu-bin-dist-1.0.hpi
 
Then check whether /dev/dsk/c7d0l1s0 already exists. If not, create it as root
user with

  mknod /dev/dsk/c7d0l1s0 b 0 0x070010

Finally mount the second disk unit with

  mkdir /gnu-bin-dist
  mount /dev/dsk/c7d0l1s0 /gnu-bin-dist
  cd /gnu-bin-dist

For mounting the hpi image when using another drive for the system disk (such as
SCSI or HP-IB real hardware) first start HPDrive on the PC side with

  hpdrive -d -C2203 gnu-bin-dist-1.0.hpi

Then check whether /dev/dsk/c7d0s0 already exists. If not, create it as root
user with

  mknod /dev/dsk/c7d0s0 b 0 0x070000

Finally mount the drive with
 
  mkdir /gnu-bin-dist
  mount /dev/dsk/c7d0s0 /gnu-bin-dist
  cd /gnu-bin-dist


IV. Installation
================

Installation is pretty straight-forward. Simply copy install.sh and the
compressed installation archives (files with suffix .Z) into the same directory
and run

   sh install.sh

from that directory and all packages will be installed into /usr/local/ and to
the proper X11 & Motif directories. Please note that any already existing file
with the same name will be overwritten. Installing in X11 directories needs root
privileges, which is not necessarily the case for installing just the GNU tools.

You also can install individual packages separately with

   sh install.sh gnu
   sh install.sh emacs
   sh install.sh perl
   sh install.sh x11
   sh install.sh motif

Note: Normally, after a fresh install of HP-UX 9.00, the /usr/local directory
      will be empty. But if you already have installed files in this location,
      better save them somewhere else before installing the package. Otherwise
      they may get overwritten during the installation.

After all files have been installed, you have to include /usr/local/bin into
your PATH shell variable before /bin. You can do so with

   PATH=/usr/local/bin:$PATH
   export PATH

Also include /usr/local/emacs/bin and /usr/local/perl5/bin in the search path if
you have chosen to install GNU emacs and Perl 5.

I recommend making this persistant in your .profile user startup script, rather
than in /etc/profile. Reason behind is that normally there is no need to be root
for using the GNU tools (actually being root is deprecated for software
development), and the default root environment should not mix up standard
execution paths and GNU tools execution paths.

Note: Some GNU tools replace existing tools with the same program name.
      Examples are the GNU linker ld, the GNU archiver ar or the GNU make
      utility. By using /usr/local/bin as the first search location, you
      ensure that always the GNU tools are executed, and not the standard
      tools which are normally stored under /bin. GNU tools should in case of
      doubt better work together with other GNU tools for maximum
      interoperability, not with the native tools built into the operating
      system, even if the latter are more stable or provide the better
      performance. If you for whatever reason need to go back to HP-UX'
      native tools, simply remove /usr/local/bin from the PATH variable.

Once the PATH variable has been updated, you can test it e.g. with

   gcc --version
  
I would also recommend to set the PAGER and the TERMINFO variables in your
.profile startup script as follows:

   TERMINFO=/usr/local/lib/terminfo
   PAGER=/usr/local/bin/less
   export TERMINFO PAGER

If you like, you also can set EDITOR to emacs instead of vi.


V. Usage
========

Plase refer to the man or info documentation, e.g. with

   man gcc
  
 or

   info gcc
  
to request information on the installed program versions. You also are
encouraged to visit www.gnu.org for digging even more, but be warned that the
version included in the GNU for HP-UX 9.00 package do intentionally not
represent the latest versions.

If you need a complete IDE, and you are a friend of efficient keyboard commands,
just use emacs as the build control center. It can easily be configured to not
just edit source code, but also to execute build commands, parse compiler
output, follow references to build errors and integrate the GNU debugger and
version control.


VI. Compiling Your Own Packages
===============================

There are many more programs available from GNU and non-GNU projects beyond the
current GNU for HP-UX 9.00 package. The development environment included in the
package however can be used to create more tools on your own.

The normal steps for building a program are:

   1. Download the source code package from whereever appropriate (such as
      ftp.gnu.org) onto your system. I would recommend to create a subdirectory
      under your home directory for this, e.g. /users/yourname/packagename.

   2. If the package is in compressed format, use either bzip2 (for .bz2) or
      gunzip (for .gz) to uncompress the package.

   3. Use 'tar xvf <tarfile>' to unpack the whole distribution. If you have
      already bzip2 or gzip installed, you can directly unpack & install from
      the package archive, such as
     
         bunzip2 -c <tarfile>.bz2 | tar xvf -
         gunzip -c <tarfile>.gz | tar xvf -
     
   4. Locate the installation instructions of the package (normally one of the
      files INSTALL or README) and follow the procedure described there.
      In general this includes the four steps from the top of the source
      directory tree:

         sh configure --prefix=/usr/local --disable-shared
         make
         make check (or make tests) [optional]
         make install

For some packages is is advantageous to separate the source directory from the
build directory. For building gcc this is mandatory. Separate source and build
directories are not well supported by HP's own make utility, the gcc make
utility is recommended anyway.

Also some packages provide test suites. It is strongly recommended to run those
test suites before installing the package, so you can be sure you are installing
a working program. Normally this is done with 'make check' or 'make tests'.

Only few packages run through the whole build process without modifications. You
have to keep in mind that those packages are source for building on a large
number of platfoms, and unless someone else did a port for exactly your personal
system configuration, you can assume that some adjustments will be required. And
yes, it can be time consuming to do a port. Of course there is no general rule
how to cope with those problems. Here are just a few tips:

   - GNU software packages in general include pre-build targets for
     configuration scripts, makefile templates, dependencies and
     documentation. For re-building those targets, tools like autoconf,
     automake, autoheader, aclocal, makeinfo and several others are
     required. Since rebuilding the targets can be a time consuming
     process and in general is only required if you have changed one
     of the target's dependencies in the source tree, you can save time
     and worries by using the pre-built versions. The make tools will
     automatically use the pre-built targets if their modification time
     stamp is newer than that of any of its dependencies.
    
     If you just unpack the distribution archives with tar xf, the original
     time stamps will be preserved, and normally no pre-built target will
     be re-built.

   - If there is an existing HP-UX port, check whether it is for HP300 (m68k)
     or HP700 (HPPA). If the port is for HP700, only HP-UX specific parts
     of the port can be re-used, no machine dependencies.
    
     Also check whether the port is for using HP-UX cc or GNU gcc.
     If the port is for HP-UX cc, it will normally be for the standard
     ANSI C compiler, not for the bundled K&R compiler. If the port
     is for gcc, there can be of different flavors: gcc using native
     HP-UX binary tools (ld, as, ar etc.), gcc using GNU binutils,
     or gcc as cross compilers. A good indicator can be which kind
     of ar and ranlib are configured. If it is /bin/ar or /usr/bin/ar
     with 'ar ts' as standard ranlib command, it is probably configured
     for a gcc using native HP-UX binary tools. If it is /usr/local/bin/ar
     with 'ranlib' as ranlib command, it is probably configured for
     a gcc using GNU binutils. Cross compilers are not useful for building
     on a HP300 anyway (also there is no known working cross compiler
     for HP300 running on another system such as a MS Windows PC).
    
     You will need different gcc build configurations for HP-UX native binary
     tools and GNU binutils. With the GNU for HP-UX package you can control
     them by simply setting the proper search path. See "Native Tools &
     Shared Libraries" below.
    
     Note that the available port for GNU binutils won't support creating
     of or linking to shared libraries. You should use the --disable-shared
     or --enable-shared=no options when running a configure script.
    
   - If the build process stops because a certain program for a target is
     missing, first check whether the target already exists but is outdated
     and just needs a 'touch'. Sometimes make has removed the target, and you
     just have to re-extract it from the tar archive. If there /really/ is a
     program missing to build the target, you need to download, build &
     install that one before you can go on.

   - If the build  process is running out of memory increase the kernel
     parameter 'maxdsiz' for the data segment with HP-UX' SAM utility (must
     be superuser) and rebuild the kernel afterwards. Some large packages may
     need a value of up to 0x08000000 (=128 MB).
    
   - If the shell gives a memory error during the run of configure, try
     running "sh configure" instead of "./configure". Same applies to running
     the install-sh into shell memory errors, change the call of
     "install-sh" into "sh install-sh".
    
   - If, when using the native bundled C compiler, the preprocessor (cpp)
     stops because there is not enough space for defines etc., grant
     additional space with the -Wp,-H256000 option. This should by enough
     for at least bootstrapping the basic tools for compilation. There
     is no such issue when using gcc.

   - If a certain system value within a system header file is not declared
     although the header file has been properly included, define _KERNEL
     before including them.

   - If the linker can't resolve one or more references, 'grep' in the existing
     source or object files where that function or variable is implemented and
     check in the Makefile why the object file or library is not being included
     within the link step.

   - GNU ld and HP-UX ld are not fully compatible, nor are GNU ar and HP-UX ar
     (the latter differ in their symbol tables). The HP-UX assembler and the
     GNU asssembler require totally different input fomats and generate both
     a.out object format but with different symbol information.
    
     By default, gcc is using /usr/local/bin/ld and /usr/local/bin/as.
     HP's cc and native-gcc are both using /bin/ld and /bin/as. Make sure that
     for gcc /usr/local/bin/ar is placed before /bin/ar in the search path,
     and for HP's cc and native-gcc vice versa. For gcc use as ranlib command
     /usr/local/bin/ranlib, for HP's cc and native-gcc '/bin/ar ts'.

   - There is no yacc available without HP's own development environment. Use
     bison -y instead. Most auto configuration tools will detect bison
     automatically. Same applies to lex, which is replaced by flex. When
     using the native bundled C compiler, you can create a workaround by
     creating a symbolic link from /bin/lex to /usr/local/bin/flex, plus
     writing a small shell script named /bin/yacc which calls bison with
     "/usr/local/bin/bison -y $*".

   - Check in the change logs whether support for HP-UX 9.x has been added or
     discontinued with a certain version. Try to figure out the most recent one
     with support for HP-UX 9.x. GNU packages normally include config
     directory trees which build a database for configurations such as
     'm68k-based architecture with hpux operating system'.

   - Sometimes HP-UX ports for a certain version are incomplete or buggy,
     check for one of the more recent releases whether there is a fix.

   - Sometimes HP-UX ports are obsolete or restricted to a newer HP-UX version
     (such as 10.x or 11.x). In this case check for an older release where the
     port for HP-UX 9.00 is still available.

   - If the assembler complains about the wrong input, either the HP-UX
     assembler is used with gcc or the GNU assembler is used with the HP-UX
     standard compiler. Both programs have the name 'as', so check the
     search path.

   - Check in google groups if you are looking for other user's experiences
     on GNU and HP-UX 9.00. Google web search won't help much on problems
     which happened 15-20 years in the past.
    
   - Don't waste time for looking for pre-compiled program binaries for
     HP-UX 9.00. Probability is pretty low that you will find them. This
     is the main reason for this package.
    

VII. Limitations & Odds
=======================

64-bit Support
--------------

The included gcc compiler assumes long long integers 64-bit wide and performs
all CPU calculations on 64-bit quad words correctly, but where it uses HP-UX
libraries, the result is unpredictable, since HP-UX does not support 64-bit long
long integers (neither signed nor unsigned).

This is most obvious when doing a formatted output with printf(). printf() in
gcc 2.95.3 uses the printf() system call provided by HP-UX C library, which
handles a long long as long in a way it uses the most significant 4 bytes of a
long long integer as long integer, so that just the upper 32 bits are output.
You can solve this by performing a two-step printf, such as:

   unsigned long long value = 0x0123456789abcdef;
   printf("%08lx%08lx", value, value << 32);

As a consequence, you you should use 64-bit values with care. The included
tcl/tk tools are compiled without 64-bit support or support for large files with
size of >2 GByte. Same applies to perl.

An HP-UX port of the Gnu C library would be helpful in this point, however as
far as I know there is no port available yet.


C99 Support
-----------

The included gcc 2.95.3 version does not officially support the C99 C language
standard. So a couple of types & directives such as 'restrict' defined in later
GNU packages may fail. IEEE754 however should be fully supported.


Native Tools & Shared Libraries
-------------------------------

gcc can be built for using GNU assembler & linker, or for using HP-UX native
assembler & linker. gcc with GNU assembler & linker takes advantage of a high
number of additional features and full support of GNU debug information (as
needed for GNU debugger gdb), and is therefore recommended as standard for
building public source packages. All utilities within this distribution package
have been built with this version of gcc for maximum GNU compatibility.

However, the GNU assembler/linker uses a slightly different symbol table format,
which is incompatible to HP-UX native tools. Also, the HP300 port of GNU
binutils (including assembler & linker) does not support building or linking
HP-UX shared libraries (libraries with filename extension .sl).

So, if there is need for creating static libraries with gcc using HP-UX native
symbol table format, or shared libraries shall be linked, simply use the
native-gcc compiler located in the /usr/local/native-gcc/bin directory instead
of the gcc which is located in /usr/local/bin.

If both shared and static libraries are available, the native-gcc links to
shared libraries by default (leading to smaller executables). For linking to
static libraries, use 'gcc -Wl,-a -Wl,archive'. It is highly recommended to
position /bin, /usr/bin and /usr/local/native-gcc/bin ahead of /usr/local/bin in
your search path when working with native-gcc.

See the "HP-UX 9.0 Programming on HP-UX" manual for instructions how to use
shared libraries in general.

Object code for creating shared libraries (and only for shared libraries) must
be compiled with position independent code (PIC). Currently, the gcc is not
capable of generating working PIC for HP-UX. Shared libraries created with the
-fpic or -fPIC options will crash when local data is referenced within a text
segment.


Year2k
------

HP-UX 9.00 is not year 2k proof. There are not even patches available. So, to be
sure, operate the system with a system time between 1993 and 1999 and do not
cross the year 2000 boundry.

However, I did a couple of quick tests with the most common date/time/filetime
routines, and did not find anything unusual. And when skewing time back,
consider getting into problems with software archives containing modification
times which - from the systems perspective - lie in the future. Also proper
modification time again is essential to re-use pre-built targets.
    
    
VIII. Disclaimer
================

EVERYTHING YOU DO WITH THE GNU FOR HP-UX 9.00 PACKAGE IS ON YOUR OWN RISK. I AM
NOT AND WILL NEVER BE UNDER ANY CIRCUMSTANCES LIABLE FOR ANYTHING WHAT HAPPENS
WITH USING THE SOFTWARE. SO, IF YOU NEED SUPPORT OR GUARANTEES OR WARRENTY OR
WHATEVER, BUY COMMERCIAL PRODUCTS OR GET THE SOURCE PACKAGES AND DO IT ON YOUR
OWN. BUT PLEASE *NOT* WITH ANY OF THE PROGRAMS WITHIN THIS GNU OR X11 FOR HP-UX
9.00 PACKAGES.

Please also observe the license rules which are bound to the software, which in
most cases is the GNU Public License (GPL). See
http://www.gnu.org/licenses/gpl-3.0.en.html for details.

On the other side, if you like to report bugs, or just give feedback or
suggestions, your are highly welcome to send me some note. Please us the contact
feature on http://hp9845.net/9845/home/contact.php.

Also don't hesitate to visit http://www.hp9845.net and have a look on my other
projects.

