%% /usr/local/src/hoc/hoc-7.0.2.beta/INSTALL, Sun Jan 27 10:31:00 2002 %% Edit by Nelson H. F. Beebe ============ Introduction ============ These are installation instructions for building, testing, and installing hoc version 7 (or later), a significant extension of the 1984 Kernighan and Pike high-order calculator. See the companion files for related details: COPYRIGHT Software copyright of the original hoc authors. The hoc 7 developer's contributions are considered to fall under the same liberal copyright conditions. [Roughly paraphrased: We're happy to have you use this software for free and for any purpose; just don't blame us if it doesn't work the way you expect.] ChangeLog Changes since hoc version 6. hoc.1 UNIX manual pages (raw nroff/troff) hoc.html UNIX manual pages (HTML) hoc.pdf UNIX manual pages (Portable Document Format) hoc.ps UNIX manual pages (PostScript) hoc.txt UNIX manual pages (plain text) PROBLEMS Problems met along the way. PROJECTS Ideas for future projects. README The original hoc announcement. README.NaN Notes about IEEE 754 NaN representation. README.UTAH Notes about changes made to version 6 to enhance portability (but nothing on the version 7 work). TO-DO Development list: when all items are commented out, the beta test development is complete, and after a suitable waiting period for remote user reports, an official non-beta release will be announced. ==================================== Unbundling the distribution archives ==================================== The hoc distribution is provided in at least four separate archive formats (each with identical contents), which may be unpacked like this: jar xf hoc-7.0.0.beta.jar tar xfz hoc-7.0.0.beta.tar.gz or, if you do not have GNU tar with its convenient z option, gunzip < hoc-7.0.0.beta.tar.gz | tar xf - unzip hoc-7.0.0.beta.zip zoo x hoc-7.0.0.beta.zoo Unfortunately, the jar format does not preserve execute permissions (what a foolish design error that is, given that the underlying zip format does!), so on a UNIX system, you then need to put them back like this: chmod a+x check-help.sh configure The other archive formats do not have this problem. =========================================== Default build, validation, and installation =========================================== To build, test, and install this software on any GNU, POSIX, or UNIX system with default settings, use the GNU standard build procedure: ./configure && make all check install You MUST have a C or C++ compiler conforming to 1989 ISO Standard C; the code CANNOT be compiled as-is with an old-style K&R C compiler. See the next section for instructions on the latter. If any of the validation tests fail, the install step will be skipped. After examining the output of the failing tests, you may decide that the differences reported are acceptable, and then you can do make install to complete the installation. By default, a 64-bit floating-point version of hoc will be built, but it may be possible to build others on your system, like this: ./configure --with-float && make all check install ./configure --with-double && make all check install ./configure --with-long-double && make all check install The installed executables will be called hoc32, hoc64 (same as hoc), and either hoc80 (Intel x86 and Motorola 68K) or hoc128 (most RISC architectures). The default is --with-double. Support for float and long double data types, and their corresponding run-time library, is sadly, and appallingly, deficient in many C/C++ implementations, so these alternate hoc precisions may not be buildable on your system. ======================================== Building in an old K&R-style environment ======================================== If you have a very old system that only has an old Kernighan & Ritchie C compiler (e.g., Hewlett-Packard HP-UX 10.01 at the maintainer's site), it is still possible to build hoc, but it takes one extra step: ./configure && make convert-to-knr all check install The convert-to-knr step creates a subdirectory, ./original, into which are moved the *.c source files needed to build hoc, then the ansi2knr filter (automatically built as a prerequisite to this step) is applied to create modified *.c files in the current directory that should compile under K&R C. The --with-float and --with-long-double build options are not expected to work in a K&R environment. The only system now available to the maintainer to test this under is HP-UX 10.01. However, in late 2001, it is now twelve years since the first ISO C Standard (1989), and two since the second one (1999), so most sites should have Standard C support by now. ======================================= How long does the validation suite run? ======================================= Typical wall-clock times for running the validation suite on local disks are: Pentium III (1.267GHz) 4 sec AMD Athlon (1.4GHz) 4 sec Compaq/DEC Sierra (667MHz Alpha 21264) 6 sec Intel Pentium III (600MHz) 8 sec Intel Pentium II (333MHz) (GNU/Linux) 7 sec Intel Pentium II (450MHz) (FreeBSD) 9 sec Compaq/DEC 4100-5/466 (466 MHz Alpha 21164) 16 sec Apple PowerMac G4 (533 MHz) 16 sec SGI Origin 200 (180 MHz MIPS R10000) 22 sec Sun Enterprise 5500 (400 MHz UltraSPARC II) 24 sec IBM RS6000 43P-166 (166 MHz PPC) 24 sec Apple PowerMac G3 (267 MHz PPC) 35 sec IBM SP/2 (166 MHz PPC) 40 sec Sun SPARC 10/51 (50 MHz SuperSPARC) 112 sec DEC Alphastation 200 4/100 (100MHz Alpha 21064) 144 sec HP NUE IA-64 emulator on Intel Pentium III/600MHz 1958 sec ===================================== What the validation output looks like ===================================== Here is a sample clean run of the validation suite (from the AMD Athlon system) (tests may be added from time to time, so your output may differ somewhat): ======================================================================== The only output should be the names of the tests: Caveats: (1) The Jn and Yn Bessel function tests expose serious inaccuracies on some platforms: IBM Power, PowerPC AIX: Jn: 16 bits, Yn: 11 bits SGI MIPS IRIX 6.5: Jn: 17 bits, Yn: 10 bits Sun SPARC Solaris 2.7, 2.8: Jn: 13 bits, Yn: 12 bits The Jn and Yn reporting tolerance is thus set high: 9 bits (2) The output form of NaN and Infinity is platform-dependent, so the many-symbols test may show differences there. (3) The many-symbols test will show differences for MINSUBNORMAL on systems that lack support for subnormals. (4) Recent GNU grep implementations may supply a final newline in the group D deep-calls test, while others may not, so there may be a bogus difference reported for that test. Check group A (original hoc 6 tests) ... ack double fac fac1 fac2 fib fib2 fibsum fibtest gamma Check group B (mostly numeric new hoc 7 tests) ... author ceil cos-sin eqne exp floor hypot hypot-alt infinity Jn macheps nan news relop scalb sqrt tan Yn Check group C (command-line option hoc 7 tests) ... opt-author opt-help opt-silent opt-version Check group D (internal array size limit hoc 7 tests) ... deep-calls long-name long-numtoken long-operand long-string many-symbols Check group E (string function hoc 7 tests) ... getenv index length strftime substr tolower toupper ======================================================================== ======================================== Rerunning subsets of the validation test ======================================== To run particular subsets of the validation suite: make check-a make check-b make check-c make check-d make check-e make check-f You can rerun a particular subtest of any of these by specifying the test file names, like this: make check-b CHECK_B="Jn.hoc Yn.hoc" If you want to see more than the default number of difference lines, do so like this example for the strftime() test: make check-e CHECK_E="strftime.hoc" DIFFLINES=9999 [The strftime test exposed the lack of proper internationalization on several systems: non-C locales are still treated like C (English). Other systems simply have (permitted) vendor-specific implementation choices for the output of certain calendar data formats.] ================================== What gets installed on your system ================================== With a default build and installation, this will report these files installed on your system (user and group identifiers will of course differ at your site): Installed files... -rw-rw-r-- 1 beebe wheel 2887 12-20 21:10 /usr/local/share/lib/hoc/hoc-7.0.0.beta/da/help.hoc -rw-rw-r-- 1 beebe wheel 2916 12-20 17:17 /usr/local/share/lib/hoc/hoc-7.0.0.beta/da/hoc.rc -rw-rw-r-- 1 beebe wheel 2813 12-20 21:09 /usr/local/share/lib/hoc/hoc-7.0.0.beta/de/help.hoc -rw-rw-r-- 1 beebe wheel 3469 12-17 15:44 /usr/local/share/lib/hoc/hoc-7.0.0.beta/de/hoc.rc -rw-rw-r-- 1 beebe wheel 5473 12-08 17:23 /usr/local/share/lib/hoc/hoc-7.0.0.beta/expm1.hoc -rw-rw-r-- 1 beebe wheel 3015 12-20 21:11 /usr/local/share/lib/hoc/hoc-7.0.0.beta/fr/help.hoc -rw-rw-r-- 1 beebe wheel 3548 12-17 15:42 /usr/local/share/lib/hoc/hoc-7.0.0.beta/fr/hoc.rc -rw-rw-r-- 1 beebe wheel 51140 12-20 21:05 /usr/local/share/lib/hoc/hoc-7.0.0.beta/help.hoc -rw-rw-r-- 1 beebe wheel 9061 12-18 15:12 /usr/local/share/lib/hoc/hoc-7.0.0.beta/hoc.rc -rw-rw-r-- 1 beebe wheel 4853 12-08 18:02 /usr/local/share/lib/hoc/hoc-7.0.0.beta/log1pa.hoc -rw-rw-r-- 1 beebe wheel 4780 12-08 17:24 /usr/local/share/lib/hoc/hoc-7.0.0.beta/log1pb.hoc -rw-rw-r-- 1 beebe wheel 5632 12-08 17:24 /usr/local/share/lib/hoc/hoc-7.0.0.beta/log1pc.hoc -rw-rw-r-- 1 beebe wheel 2977 12-20 21:13 /usr/local/share/lib/hoc/hoc-7.0.0.beta/pt/help.hoc -rw-rw-r-- 1 beebe wheel 3091 12-18 18:12 /usr/local/share/lib/hoc/hoc-7.0.0.beta/pt/hoc.rc -rw-rw-r-- 1 beebe wheel 3186 12-20 21:14 /usr/local/share/lib/hoc/hoc-7.0.0.beta/tr/help.hoc -rw-rw-r-- 1 beebe wheel 3244 12-17 15:45 /usr/local/share/lib/hoc/hoc-7.0.0.beta/tr/hoc.rc -rwxrwxr-x 1 beebe wheel 34520 2000-02-14 /usr/local/bin/hoc -rw-rw-r-- 1 beebe wheel 2851 08-24 19:24 /usr/local/man/man1/hoc.1 -rw-rw-r-- 1 beebe wheel 3682 12-10 06:08 /usr/local/share/emacs/site-lisp/hoc.el If any of these are missing after you do this at your site, then either the containing directories are missing, or you do not have permission to write into them. ======================= Undoing an installation ======================= You can remove the installation like this: make uninstall =================== Customizing a build =================== You can customize the installation directory tree with the --prefix option, like this: ./configure --prefix=$HOME/local The default prefix is the GNU standard /usr/local. You can choose any specific C or C++ compiler at configure time like this: env CC=compiler-name ./configure [The env command is available in all shells: it allows compact bash/ksh/sh-style setting of environment variables that exist just for the duration of the single command.] You can choose a nondefault implementation of yacc (usually, byacc or "bison -y"), like this: env YACC="bison -y" ./configure By default, GNU readline support will be used if it is found to be available, since that produces a hoc that is more convenient to use. You can, however, build without that support like this: ./configure --without-readline If you want configure to cache the results it found (this is handy during development, but unlikely to be needed at end-user sites), run it like either of these: ./configure -C ./configure --config-cache Here is an example of a highly customized build: env CC=/usr/local/test/bin/g++ YACC=byacc \ ./configure -C --prefix=/tmp/local --without-readline && \ make all check install ========================= Cleaning up after a build ========================= To clean up after a build, leaving the hoc executable in place: make clean To remove everything that make built at your site, reducing the directory contents to what was unpacked from the original software distribution: make distclean You MUST do this between successive builds for different architectures in the same build directory. Otherwise, the config.h values and Makefile variables that configure determined will very likely be wrong for the next build. ======================================================== Recovering from disasters, or bootstrapping the hard way ======================================================== Should you accidentally delete, or damage, the configure script, you would be in trouble unless you had the GNU autoconf package installed locally. To avoid that need, the subdirectory save/ contains read-only copies of these files: Makefile config.h configure hoc.c y.tab.h They can be used for recovery. They can also be used if you are on some absolutely bizarre system where configure doesn't work, giving you a Makefile, config.h, hoc.c, and y.tab.h that you can copy and edit as needed to bootstrap. Please tell me about any such system [see below for where]. The GNU autoconf developers have worked VERY hard to make sure that configure should run on ANY GNU, UNIX, or POSIX system without error. ================================= Building hoc on Microsoft Windows ================================= There are free and commercial UNIX-like environments for Microsoft Windows in which hoc should build fine (though I have not yet tested this myself). See http://www.math.utah.edu/~beebe/gnu-on-windows.html for details. ============== Test platforms ============== During development, this package has been tested with C and C++ compilers (vendor-provided native compilers, plus gcc-2.95.[23] and gcc-3.x from the most recent working weekly snapshot): AMD Athlon GNU/Linux version 2.4.2-2smp (Red Hat 7.1) Apple Power Mac 233MHz GNU/Linux 2.2.15pre9 Apple PowerPC G3 267MHz GNU/Linux 2.2.18-4hpmac (Red Hat Linux/PPC 2000 Q4) Apple PowerPC G4 267MHz Darwin 1.3.3 Apple PowerPC G4 267MHz Yellow Dog GNU/Linux 2.0 Compaq Alpha Sierra OSF/1 5.0 Compaq/DEC Alpha OSF/1 4.0F DEC Alpha GNU/Linux 2.2.19-6.2.1 (Red Hat 6.2) HP 9000/712 HP-UX 10.20 HP/Intel IA-64 GNU/Linux 2.2.17-14smp (Red Hat 6.2) [via HP NUE emulator on IA-32] IBM PowerPC AIX 4.2 IBM SP/2 AIX 4.3.2.0 Intel Pentium II FreeBSD 4.1.1 Intel Pentium III GNU/Linux 2.2.17-14smp (Red Hat 6.2) Intel Pentium III GNU/Linux 2.4.9-13smp (Red Hat 7.2) SGI Origin 200 IRIX 6.5 Sun SPARC GNU/Linux 2.2.19-6.2.1 (Red Hat 6.2) Sun SPARC Solaris 2.7 Sun SPARC Solaris 2.8 ======================= Bug and problem reports ======================= Send bug and problem reports, comments, and kudos to the hoc 7 developer (preferably via e-mail) at: Nelson H. F. Beebe Center for Scientific Computing University of Utah Department of Mathematics, 322 INSCC 155 S 1400 E RM 233 Salt Lake City, UT 84112-0090 USA Email: beebe@math.utah.edu, beebe@acm.org, beebe@computer.org, beebe@ieee.org (Internet) WWW URL: http://www.math.utah.edu/~beebe Telephone: +1 801 581 5254 FAX: +1 801 585 1640, +1 801 581 4148 Please do NOT bother the original hoc authors, Brian Kernighan and Rob Pike about hoc 7 issues. Their job finished with the publication of their excellent 1984 book! (run "hoc --author" for details).