# Installing BRL-CAD

*** PLEASE READ ***
THESE INSTALLATION INSTRUCTIONS ARE NO LONGER RELEVANT.
PLEASE SEE THE README OR INSTALL FILES IN THE SOURCE DISTRIBUTION.
They are included for historical reference only

This document exists to help you install the BRL-CAD Package. With approximately 435,000 lines of source code, and support for over a dozen hardware platforms, the configuration is important. It would be best if you read these directions first. However, it would be quite understandable if you were more eager to press ahead than to read this long paper. If you choose to start compiling now, the commands to run are presented here. Please, if anything seems wrong, pause to finish reading the directions.

            mkdir /usr/brlcad
            mkdir cad
            cd cad
            tar x              # 'tar xo'   on System V
            sh machinetype.sh -v
            sh setup.sh
            sh gen.sh all
            sh gen.sh install

If you need to install the software somewhere other than /usr/brlcad, (given as /a/b/c in this example,) follow this procedure:

            mkdir /a/b/c
            mkdir cad
            cd cad
            tar x               # 'tar xo'   on System V
            sh machinetype.sh -v
            sh newbindir.sh /a/b/c
            sh setup.sh
            sh gen.sh all
            sh gen.sh install

## DISTRIBUTION TERMS

This software is an unpublished work that is not generally available to the public, except through the terms of a limited distribution agreement. Please recall that to obtain this software, you agreed that before using the software at additional sites, or for permission to use this work as part of a commercial package, you would first obtain authorization from ARL.

## INTRODUCTION

The BRL-CAD Package software is distributed only in source code form. There are quite a number of advantages to this. The most important advantage is that only a single distribution tape has to be prepared; this distribution tape contains the complete software for all currently supported machines. All a BRL-CAD recipient needs to do is compile the source code, and install the resulting binaries. The second most important advantage of a source-code-only distribution is that it gives you complete control of your destiny. If you need to add a feature, change something, or fix a bug, you have everything required. Since ARL is unable to offer any kind of support of this software to non-Government recipients, distributing full source code ensures that you need not become "stuck".

This software is generally used in one of three ways:

- For production use,
- For the RT ray tracing benchmark, or
- For exploration, to get acquainted with the software.

Each of these different types of use will require slightly different configuration of the software. By default, the software is pre-configured for production use, to make installation most convenient for the primary user community. However, the modifications required for non-production use are slight, and are called out in great detail in the ensuing sections.

The BRL-CAD Package has been ported to a great many different machines throughout its lifetime. Every machine / software version combination will fall into one of these three categories:

a) For every configuration that we have available to test with at BRL, the software has been designed to install automatically, without need for any modifications to the configuration files. The hardware/software configurations which are known to have "automatic support" in this release are listed in this table, along with the default configuration specified in Cakefile.defs:

MTYPE | Hardware | Software | Framebuffer | MGED
--- | --- | --- | --- | ---
c1 | Convex C1 | UNIX 6.2.32.2 | net | -
xmp | Cray X-MP,Y-MP,C-90 | UNICOS 8 | net,X11 | X11
cr2 | Cray-2 | UNICOS 7 | net,X11 | X11
alpha | DEC Alpha | OSF/1 V3.0 | net,X11 | X11
vax | DEC VAX-11 | Berkeley 4.2 BSD, 4.3 BSD | net | -
bsdi | IBM PC | BSDI | net,X11 | X11
li | IBM PC | Linux | net,X11 | X11
nb86 | IBM PC | NetBSD/i386 1.0 | net,X11 | X11
5d | SGI 4D | Irix 4.0.5 | sgi,net,X11 | sgi,X11
6d | SGI 4D | Irix 5.2 | sgi,net,X11 | sgi,X11
7d | SGI 4D/TFP | Irix 6 | sgi,net,X11 | X11
sun3 | Sun-3/* | SunOS 4.1.X | net,X11 | X11
sun4 | Sun-4/* | SunOS 4.1.X | net,X11 | X11
sun5 | Sun-4/* | SunOS 5.3,5.4 | net,X11 | xgl,X11

For high-performance graphics, the SGI and Sun (GX) platforms work best.

b) With slight modifications to the configuration files, these additional hardware/software configurations can be easily supported. In many cases, these differences are due to slight variations in the hardware options installed, or the version of the software being used.

MTYPE | Hardware | Software
--- | --- | ---
3d | SGI 3030 | Version 3.5, 3.6
apollo | Apollo | SR10.1
ard | Stardent Titan | System V
aux | Apple Mac II | AUX 1.0
eta | ETA-10 | System V
fx | Alliant FX/8, /80 | Concentrix 3.0, 4.0
fy | Alliant FX/2800 | Concentrix 5
ibm | RS/6000 | AIX
ipsc | iPSC/860 Hypercube | NX/2
n16 | Encore Multi-Max | System V
next | NeXT | NeXT 2.0
np1 | Gould NP1 | UTX
pyr | Pyramid 9820 | OSx Version 4.1
sel | Gould PN6080, PN9080 | -
stad | Stardent VISTRA | System V
stl | Stellar | System V
vax | DEC VAX-11 | Berkeley 4.1 BSD

These systems are not considered ``supported'', but should work with little or no effort.

c) Porting this software to a machine which is not in one of the two tables above will require some additional configuration or programming effort. See the section on SUPPORTING A NEW MACHINE, below, for details.

There are some machine/display combinations which are supported that are not part of the default configuration. Optional framebuffer support is:

if_ab | Abekas A60 videodisk (ethernet)
if_adage | Adage RDS-3000 ("Ikonas")
if_ptty | AT&T 5620 w/special Moss layer
if_sun | SunView interface
if_ts | TekSource VME framebuffer
if_rat | Raster Technology One/80
if_remote | Network access to remote display
if_sgi | SGI Iris 3-D display
if_4d | SGI 4-D display
if_ug | Ultra Graphics
if_X | X Window System (X11R3, R4, R5)

At present, all versions of mged have support for these types of display devices by default:

dm-plot | any UNIX-plot filter
dm-tek | Tektronix 4014 and family
dm-tek4109 | Tektronix 4109
dm-ps | PostScript

These optional display devices are also supported, when specifically configured:

dm-ir | SGI 2400, 3030
dm-4d | SGI 4-D
dm-sun | SUN 3.2 Pixwin
dm-rat | Raster Tech One/180,380
dm-rat80 | Raster Tech One/80
dm-X | X Window System (X11R4, R5)
dm-xgl | SUN XGL interface

# DISK STORAGE REQUIREMENTS

The BRL-CAD Package is distributed in source code form only, so you will need enough space to simultaneously store the source material, documentation, binary files, and test images.

The TAR archive of the source materials requires about 48 MBytes. You will need about 350 MBytes of free space to compile in. On an SGI Irix 4.0.5 system, the installed /usr/brlcad tree requires 165 MBytes. On an SGI Irix 5.2 system, the installed /usr/brlcad tree requires only 21 MBytes. On a Sun-4 system, the installed /usr/brlcad tree requires only 20 MBytes. On a BSDI system, the installed /usr/brlcad tree requires 300 MBytes (not a typo). On a DEC Alpha system, the installed /usr/brlcad tree requires 26 MBytes. The difference is due to the availability of shared library support in the later operating systems. (More on shared libraries, below).

# LOADING THE SOFTWARE

1. Find a disk with at least 300 Mbytes of free space that you can use.
2. Mount the distribution tape on the tape drive. Make certain that the tape is write protected. For "round" (1/2 inch) tapes, be certain that the write-enable ring has been removed from around the rear of the center hole. For "square" IBM 3480-style tape cartridges, be certain that the thumbwheel is set so that the white dot is showing. For the DC-300 style tape cartridges, such as are used on Sun and SGI workstations, be certain that the arrow in the upper left corner of the cartridge is pointing to the "SAFE" position. For the Exabyte 8mm style tape cartridges, be certain that the write protect tab has been slid so that the red portion is visible. For the DAT 4mm style tape cartridges, be certain that the write enable tab has been slid so that the white portion is not visible.
3. Change directory to the place where you want the source code to go, and run these two commands:

       	mkdir cad
       	cd cad

   This will create a directory for containing the entire BRL-CAD Package tree, to keep this material separate from other projects that you may be working on.

4. Extract the contents of the tape. On a system which is based on Berkeley UNIX, run:

       	tar x

   On a system which is based on AT&T System V UNIX, run:

       	tar xo

   to forgo System V's default (bad) behavior of changing the ownership of the files as they are read from the tape.

   Note that if you have the tape mounted in a non-standard location, or are using a Sun workstation, it will be necessary to specify the tape drive to use. For example, on Berkeley UNIX, to use tape drive number one (mt1), run:

       	tar xf /dev/rmt1

   On a Sun workstation, you will need to use the command

       	tar xf /dev/rst8

   in order to have the Sun workstation read the tape using the industry standard QIC-24 format, rather than the default Sun behavior of reading the tape in QIC-11 format.
5. Apply all the relevant errata sheets. They are stored on the anonymous FTP server host ftp.brlcad.org, in the directory BRL-CAD, and are named "errata4.0-irix4" and the like.

# SOFTWARE ORGANIZATION

PROGRAMS | Description
--- | ---
rt | A ray-tracing lighting model, for rendering
lgt | Another lighting model, for rendering
mged | A solid-model editor
conv | ASCII/binary database converters
fbserv | Remote network frame-buffer server
util | Zillions of image-handling utilities and tools
fbed | Frame-buffer image editor
vdeck | Convert mged models to GIFT-format card decks.
tools | Utah Raster Toolkit tools
LIBRARIES | Description
librt | A solid-model ray-tracing library
libspl | A B-spline library
libsysv | Some System-V compatibility routines
libpkg | A "message-passing" interface to TCP network links
libfb | A generic frame-buffer library
libtermio | A library to handle terminal mode setting
libplot3 | A public-domain 2-D and 3-D UNIX-Plot library
libtig | Some plotting routines built on libplot3
librle | A Run-Length-Encoding library (originally from UofUtah)
libmalloc | The Princeton malloc(3) -- a better malloc
libwdb | A library for procedurally writing databases
libredblack | A library implementing red-black trees
MISC | Description
papers | Full-length papers
doc | Various smaller documents of lower quality
db | Several solid-model databases, in ASCII form
bench | Scripts to drive the RT benchmark
pix | Reference images for the RT benchmark
dmdfb | libfb support for layers in Teletype 5620 DMD terminal
whetstone | FORTRAN Whetstone benchmark
dhrystone | "C" Dhyrstone benchmark
CONTRIBUTED SOFTWARE (contributed/)
cake | A Fifth Generation version of MAKE
mgm | Mged On-Line Manual
off-3d | "OFF - A 3D Object File Format" document
pbm | Portable Bitmap Toolkit
spd | "Standard" Procedural Databases
toolkit-2.0 | Utah Raster Toolkit, Release 2.0

Please note that this distribution package does not include the various military-specific model analysis tools such as GIFT, SAR, SLAVE, VAST, etc., nor does it include any military databases. If you desire to have access to this material, please contact Keith Applin at (301)-278-6647.

# CONFIGURATION

If you are configuring the software for more than one type of computer, you will have to go through this configuration procedure separately for each kind of system. Configuration questions apply only to the hardware available on the particular system presently being configured.

## Normal (Single Machine) Configuration

As Cakefile.defs is distributed, the default is to place the compiled object modules and final products in the same directories as contain the source code. This is the style of operation that most UNIX software packages follow. It has the advantage of being convenient and familiar.

## NFS-based Multi-Machine Configuration

If you have several types of machines sharing a single filesystem using the Sun NFS (Network File System) or the AT&T RFS (Remote File System), and you wish to share a single copy of the BRL-CAD source tree with all the remote client machines, while maintaining separate binaries for each different type of client machine, then you probably want to take advantage of BRL-CAD's NFS-style multi-machine support. In this mode, a separate directory is made for each source directory for each type of client machine. This way, the binaries for each type of client machine can not co-mingle, yet everything is generated from a common set of source code. For example, the sources in cad/librt/ would have sun3 binaries in the directory cad/.librt.sun3/, and SGI 4-D binaries would be located in the directory cad/.librt.4d/. The leading dot on the binary directories keeps them ``invisible'' to ls(1).

This multi-machine configuration is the strategy used at BRL, where a single fileserver holds the master copy of the source code, and provides NFS service for Goulds, Alliants, Crays, Convexes, Sun-3s, Sun-4s, SGI-3Ds and SGI-4Ds. Having this capability makes it much easier to keep consistent binaries on a wide variety of machines, and minimizes "out of phase" errors between different members of the development group. Having the source code and binaries in separate directories requires slightly more care to be certain that you are in the right directory before running cake, but being able to share one set of sources across many different kinds of machines makes this well worthwhile. If you have only one kind of machine, don't bother.

To adopt this style of behavior, you will need to activate the "NFS" option in Cakefile.defs, by adding a #define NFS 1 line after the large NFS comment block, so that it reads:

    	#undef NFS

    	#define NFS 1

Then, further on, you will also be instructed to run cake mkdir to set up the binary directories for the machine you are installing.

You will also have to update the shell script gen.sh to change NFS=0 to NFS=1.

Some C-shell aliases that have proven helpful for dealing with this somewhat more complex environment are:

    # Determine machine type
    test -f /usr/brlcad/bin/machinetype.sh
    if ( $status == 0 )  then
    	set machine=`sh /usr/brlcad/bin/machinetype.sh`
    else
    	set machine=unknown
    endif
    # Build "mcd" to push source-code dir onto dir stack, then goto binary dir
    foreach i ( /n/spark/m/cad   ~/cad )
    	test -d $i
    	if ( $status == 0 )  then
    		alias mcd "cd $i/\!:1; pushd ../.\!:1."'$machine'
    		break
    	endif
    end

## CAKE: A Fifth Generation MAKE

The complexity of the NFS environment described above required a tool for maintaining binary files that was more powerful than the standard UNIX make(1) utility. After some evaluation of the options, the cake(1) utility was selected. cake uses PROLOG-style pattern matching and resolution, rather than the suffix-to-suffix translation of make, making it far more general. cake also uses the C-PreProcessor (/lib/cpp) to provide a general macro, conditional code, and file inclusion facility. However, for all these differences, the actual Cakefile files that you will find in the various source directories will look similar enough to Makefile files that all but the most extensive configuration changes can be attempted without having to learn much about cake.

# INSTALLATION DIRECTORIES

At this stage, it is necessary to decide what UNIX directory the BRL-CAD Package executable programs are going to be installed in, and to make certain that the binary (program) installation directory is in your Shell search path. This is necessary because certain programs (such as the cake program) and some Shell scripts (such as machinetype.sh) need to be placed in a location generally accessible to you, before the BRL-CAD sources can be compiled.

A full production installation done with cake install will require five directories for installing the compiled software in. These directories are known symbolicly as BINDIR, LIBDIR, ETCDIR, MANDIR, and INCDIR. BINDIR is where executable ("binary") programs and scripts are installed, LIBDIR is where all the libraries are installed, for you to use when writing additional software for this environment, and ETCDIR is where a few additional ("etc") programs, such as network server daemons, are installed. MANDIR is where the manual page subdirectories are installed. INCDIR is where all the include files are installed, so that programs which you write can reference them.

In all cases, it is necessary for the BINDIR string to be in your search path, before the BRL-CAD software can be set up.

## INSTALLATION DIRECTORIES \(em BENCHMARKING or EXPLORATION USE

For benchmark use, and for exploratory use, the binary directory should probably be set to some directory beneath your home directory. Note that the the traditional UNIX style is to name a personal directory for binary programs "bin", but you can substitute any name here, if you prefer. If you don't have some kind of "bin" directory yet, run:

    	cd		# Go to your HOME directory
    	mkdir bin
    	cd bin
    	pwd
    	cd

For this example, assume that the path to your "bin" directory (as printed by pwd above) was "/a/d/mike/bin". Use this path string as BINDIR.

Using the full path name of your "bin" directory, update the definitions for BINDIR, LIBDIR, MANDIR, INCDIR, and ETCDIR in the files "Cakefile.defs", "setup.sh", "cray.sh", "cake/Makefile", "cakeaux/Makefile", "brlman/awf", and "brlman/brlman". The shell script "newbindir.sh" can be used to simplify this process for you, if BINDIR, LIBDIR, MANDIR, INCDIR, and ETCDIR are all subdirectories with the same parent directory. Just run it with the first argument being the full path name of the new parent directory.

## INSTALLATION DIRECTORIES \(em PRODUCTION USE

For production use, the software comes configured to install everything in the directories "/usr/brlcad/bin", "/usr/brlcad/lib", and "/usr/brlcad/etc". If this choice is acceptable to you, then first you need to make these directories, or have a superuser make them for you:

    	mkdir /usr/brlcad

    	cd /usr/brlcad

    	mkdir bin lib etc include man vfont

    	mkdir man/man1 man/man3 man/man5

    	chmod 775 * */*

    	chown YOURNAME * */*

where you replace "YOURNAME" with your user name, and then you need to add "/usr/brlcad/bin" to your search path. See the previous section for instructions on how to do this.

If you wish to install the software somewhere else, create your "bin", "lib", and "etc" directories, and update the definitions for BINDIR, LIBDIR, and ETCDIR in the files "Cakefile.defs", "setup.sh", "cray.sh", "cake/Makefile", and "cakeaux/Makefile". Then, add your choice for BINDIR to your search path. Note that the script "newbindir.sh", as described above, will update the required files for you, if the BINDIR, LIBDIR, MANDIR, INCDIR, and ETCDIR all have the same parent directory.

Running setup.sh will cause all the necessary directories to be created.

## Updating Your Search Path

Bourne Shell (/bin/sh)
  If you are a Bourne Shell user (/bin/sh, generally the default shell on most systems), you will need to edit your ".profile" file, and modify the PATH variable to include the full path name of your "bin" directory (BINDIR). In the editor, look for a line that looks something like:

      	PATH=/usr/ucb:/bin:/usr/bin:/usr/local/bin::

  and add the path name of your "bin" directory after the equals ("=") sign. In this example, the new form would look like one of the two lines below; the first line is the example non-production form, and the second line is the production form.

      	PATH=/a/d/mike/bin:/usr/ucb:/bin:/usr/bin:/usr/local/bin::

      	PATH=/usr/brlcad/bin:/usr/ucb:/bin:/usr/bin:/usr/local/bin::

  where the full path name for the "bin" directory has been added to the front of your PATH specification. Then, you must run:

      	.   .profile

  (dot space dot-profile) to have the Shell set up your new PATH specification.
C-Shell (/bin/csh)
  If you are a C-Shell user (/bin/csh), you will need to edit your ".cshrc" file, and modify the "set path" directive to include the full path name of your "bin" directory. In the editor, look for a line that looks something like:

      	set path=(/usr/ucb /bin /usr/bin /usr/local/bin .)

  and add the path name of your "bin" directory after the open paren ("("), followed by a space. In this example, the new form would look like one of the two lines below; the first line is the example non-production form, and the second line is the production form.

      	set path=(/a/d/mike/bin /usr/ucb /bin /usr/bin /usr/local/bin  .)

      	set path=(/usr/brlcad/bin /usr/ucb /bin /usr/bin /usr/local/bin  .)

  where the full path name for the "bin" directory has been added to the front of your search path. Then, you must run:

      	source   .cshrc

  to have this change take effect.

# ONE-TIME SETUP

At this point, it is important to check the automatic determination of your machine type and system parameters, by running:

    	sh machinetype.sh -v

Be certain that the values which are printed are reasonable. First, make sure that the MACHINE variable is appropriate for your machine; see the table of supported machine types, above. If the MACHINE variable is set properly, the UNIXTYPE variable should also be set properly: "BSD" for systems based on the Berkeley version of UNIX, "SYSV" for systems based on AT&T SystemV. Finally, the HAS_TCP variable should be one ("1") if your machine supports the TCP/IP network protocols, and zero ("0") otherwise. If any of these parameters are not correct, see the section on SUPPORTING A NEW MACHINE, below.

Now that the installation directories have been made, and the binary directory has been added to your search path, the next step is to run the "setup.sh" shell script from within the "cad" directory:

    	sh setup.sh

This script first checks to make sure that your choice for BINDIR has been correctly installed into your search path and exported. Next, it installs several shell scripts (including machinetype.sh) into BINDIR. Finally, it compiles cake and cakeaux.

Once this is complete, if you use csh for your login shell, (or a derivative of csh, such as tcsh), run:

    	rehash

to get these additional programs into your shell's hash table. Bourne shell (sh) and Korn shell (ksh) users should skip this step.

Only if you elected the NFS-style multi-machine support above and edited Cakefile.defs, you need to run

    	cake mkdir

at this point, to make the binary directories for this machine. This step will need to be repeated while logged into each different kind of machine that you will be supporting via NFS.

# COMPILING AND RUNNING THE BENCHMARK

To compile just enough of the BRL-CAD software to run the benchmark, and then to conduct the actual benchmark test, run:

    	cake benchmark

    	cd bench

    	sh run.sh

The cake benchmark will process just the directories that are needed to run the benchmark: libsysv, libmalloc, conv, db, libpkg (if HAS_TCP==1), libfb, libplot3, libspl, librt, rt. If any fatal errors occur during this process, consult the section on SUPPORTING A NEW MACHINE.

Running the benchmark takes several hours on a DEC VAX-11/780 machine, so scale your expectations accordingly. For details on the background of the benchmark, the BRL-CAD Benchmark Test Methodology, the Ray-Tracing Figure of Merit (RTFM) used to judge the computational performance of different computer systems, and for data on the measured performance of various machines, please consult the document in "doc/benchmark.doc".

## Obtaining Correct Results

The benchmark timings are not considered valid unless the correct results are given. Make sure that the answers match the reference files to within plus-or-minus one in each color (see pixdiff(1)). You may wish to compare the execution times and log file remarks from your tests (in the "bench/xxx.log" files) with the VAX-11/780 (with hardware FPA) times which are given in the "pix/xxx.log" files. The reference images are also located in the "pix/" directory.

For example, if you are running the benchmark on a Cray X-MP, as I'm sure all of you are, moss.pix will have 152554 pixels off by 1, world.pix will have two pixels off by 1, and m35.pix will have 75 pixels off by 1. This is not to be considered an error, as it is a consequence of differences arising from Cray's different hardware floating point format, division algorithm, and rounding rules.

# GENERAL STRUCTURE OF THE SOFTWARE

In the top level directory (cad), a dummy Makefile and Cakefile exist, both of which simply invoke the Shell script gen.sh with their argument. gen.sh is used to control the processing of all commonly used operations, to see that operations are performed on the proper set of directories.

The operations supported by gen.sh are:

Keyword | Description
--- | ---
benchmark | Special: Make only benchmark
all | Makes all software
clean | rm *.o, leave products
noprod | rm products, leave *.o
clobber | rm products and *.o
lint | run lint
install | install all products
uninstall | remove all products
print | print all sources to stdout
typeset | troff all manual pages
nroff | nroff all manual pages
mkdir | NFS: create binary dirs
relink | NFS: relink Cakefile
rmdir | NFS: remove binary dirs

Within each directory is a Cakefile that includes ../Cakefile.defs, either ../Cakefile.lib (if the directory makes a library) or ../Cakefile.prog (if the directory makes programs), and finally ../Cakefile.rules. This structure allows all configuration of this package to be concentrated in the single file Cakefile.defs, with per-product structural information in the individual Cakefiles located in each sub-directory. Cakefile.rules contains all the rules which are used to implement the ancillary operations (such as "typeset", "install", etc), and these rules then apply uniformly in all product directories. While this complex structure may seem overwhelming at first, once established, it makes the task of configuration very simple.

# COMPILING THE FULL PACKAGE

To compile the full BRL-CAD Package on a supported configuration, sit in the top ("cad") directory, and run:

    	cake all

    	cake install

Note that if the products from a previous installation remain in INSTDIR (eg, "/usr/brlcad/bin", etc), then the install operation very carefully renames each existing product as product.bak before installing the new product. For example, an existing version of mged would be renamed /usr/brlcad/bin/mged.bak before the new version is installed as /usr/brlcad/bin/mged. If this behavior is not desired, perhaps because of limited disk space, the rule "cake install-nobak" can be used instead.

## Installing Network Framebuffer Service

If your system reported HAS_TCP=1, then you have TCP/IP networking, and you have the option of offering in-bound remote framebuffer service via fbserv, the framebuffer server and remote-framebuffer daemon. (Note that in previous releases, this function was provided by rfbd. This release continues to provide an rfbd program, but you should switch to fbserv). If you wish to do this, you should be sure that the IF_REMOTE capability has been selected for libfb. (In the supported configurations, it is).

To define the service, add this line to /etc/services:

    remotefb     5558/tcp       # BRL Remote Frame Buffer

If your system does not support inetd(8), fbserv should be started in /etc/rc.local. If your system uses the Sun style of inetd(8), fbserv must be started with this /etc/servers entry:

    remotefb tcp    /usr/brlcad/bin/fbserv

If your system supports the Berkeley 4.3 BSD style of inetd(8), fbserv must be started with this /etc/inetd.conf entry:

    remotefb stream tcp     nowait  nobody  /usr/brlcad/bin/fbserv       fbserv

This entry depends on having a ``nobody'' user, so be certain that your /etc/passwd file contains a line like this. (The choice of UID and GID of -2 is intentional):

    nobody:*:-2:-2:NFS Unprivileged user:/nonexistent:/dev/null

## Special Kernel/Shared Memory Considerations on all SGI systems

When using the framebuffer library on an SGI system, it is necessary to modify certain kernel limits in the binary image of your kernel to be able to use a large block of shared memory.

For an SGI 3D, follow the directions in libfb/if_sgi.c, and then reboot your workstation to allow the changes to take effect. There are claims that on some SGI 3-D machines with only 4 Mbytes of memory, this may cause unreliable operation, so be certain to keep a backup kernel.

For an SGI 4D, software release 3.0 and up, add these entries to your kernel configuration:

    	#define SHMMAX (MAXUMEM*NBPP)
    	#define SHMMIN 1
    	#define SHMMNI 100
    	#define SHMSEG 6
    	#define SHMALL 4000

then install the new kernel, and reboot.

# SUPPORTING A NEW MACHINE

This rather lengthy section attempts to document how to add support for a new type of machine. It may also prove useful to study this material if you experience difficulties with one of the existing configurations.

## machinetype.sh

The first step is enhancing machinetype.sh and Cakefile.defs to recognize the type of machine that you are using. Both of these files use the same technique: they directly run the C Preprocessor (/lib/cpp) and test for the existence of a vendor-specific pre-defined symbol that identifies the machine type, using C #ifdef constructions. For example, on a DEC VAX, the test #ifdef vax is true, while on an Alliant, the test #ifdef alliant is true. The documentation for the C Compiler cc(1) will often mention the vendor-specific symbol to test for. If not, a little playful experimentation with the vendor's name and the machine model name/number will usually suffice. Sometimes two symbols need to be checked to tell certain incompatible models apart. For example, on the SGI machines, both "sgi" and "mips" need to be checked. If defined(sgi) and !defined(mips), then it is a 3030, if defined(sgi) and defined(mips), then it is a 4D. Sometimes it is worse than that.

Update machinetype.sh first; it is easier to experiment with than the full Cakefile.defs file. The code that will need to be added will be of the form:

    	#ifdef eta10
    	/*	ETA-10 running UNIX System V. */
    	#	undef	eta
    		MACHINE=eta;
    		UNIXTYPE=SYSV;
    		HAS_TCP=0;
    	#endif

All systems have a small block of code that will look much like the example above. Your first task is to select a "nickname" for the machine that is four characters long, or shorter, in the MACHINE= line. In the example case of the ETA-10, the string "eta10" was shortened to "eta". Note the #undef eta to ensure that the "nickname" is not also a C Preprocessor builtin symbol. In the UNIXTYPE= line, only two choices are currently valid, "SYSV" for variants of AT&T System V, and "BSD" for Berkeley UNIX 4.2 BSD and 4.3 BSD. Finally, if the machine supports the TCP network protocols using the Berkeley socket interface, then define HAS_TCP=1, otherwise define HAS_TCP=0. Extending the network support for non-TCP environments, or TCP implementations that use some other interface, will probably only require changes to libfb(3) and fbserv(1), and will not be elaborated on here. Check how you did by running:

    	sh machinetype.sh -v

and making any necessary corrections.

If machinetype.sh reports that HAS_TCP=0, ie, this is a machine without TCP network capability, the gen.sh script will automatically delete fbserv and libpkg from the PRODUCTS list, as they serve no purpose in a non-networked environment.

## Cakefile.defs

The file Cakefile.defs is included in every local Cakefile, and contains the common definitions and configuration information for the BRL-CAD Package. There are a great many symbols which may be defined to specify the details of the desired configuration.

### Machine Type Information

Edit the file Cakefile.defs and start by making the same general kind of additions as were done for machinetype.sh. When porting the BRL-CAD software to a new machine, it is wise to start with a configuration that does not attempt to use the network, and which does not try to access any display hardware. Once all the basic software compiles, and the benchmark produces correct results, then a cake clobber can be done, the configuration edited to add more complexity, and a full cake all can be run.

As an example which tracks the example in the previous section, the additions to support the ETA-10 are simply:

    	#ifdef eta10
    	#	undef	eta
    	#	define	MTYPE	eta
    	#	define	UNIXTYPE	SYSV
    	#	define	HAS_TCP        0
    	#	define	LIBRT_TIMER    timerunix
    	#endif

The values for MTYPE, UNIXTYPE, and HAS_TCP should match those values placed in machinetype.sh. This definition for the ETA-10 will build a package with minimal graphics display support, and no network support.

The timer configuration LIBRT_TIMER must be specified, based on the version of UNIX you are using. This timer module is for providing CPU and elapsed time indications. If your system has a vendor-specific clock with more resolution than the normal UNIX library provides, you should eventually create your own system-specific timerXXX.c module, although timerunix.c is a fine starting point for any UNIX system. The full range of choices for LIBRT_TIMER are:

timerunix | Generic UNIX
timer42 | 4.2 BSD, 4.3 BSD (Berkeley UNIX)
timercos | Cray X-MP running COS
timer52brl | For BRL's System 5-under-4.n BSD
timerhep | Denelcor HEP

### C Compiler Configuration

The symbols CC, CC_DEFS, and CC_OPTS can be set to define various features used with the C compiler. CC is the full path to the C compiler, CC_OPTS is used to select the most appropriate kind of optimization for this configuration, and CC_DEFS is used to pass definitions to the compiler. For example, if the C compiler can not support "void" functions, this can be bypassed with:

    	#	define	CC_DEFS	-Dvoid=int

If the compiler needs a special optimization switch, this can be done with something like this:

    	#	define	CC_OPTS	-f68881

For most systems, the default values should be fine. Changing the definition of CC can be useful when testing a new release of the C compiler. The BRL-CAD Package is used by several hardware vendors as part of their standard compiler regression test suite.

### FORTRAN Compiler Configuration

The full path to the FORTRAN compiler is specified in the symbol FC. The default value is /usr/bin/f77. Note that there is no longer a single line of FORTRAN code in the BRL-CAD Package, but the Cakefiles still suport it, as a little user-developed code is still in FORTRAN.

### Host Name

The program to run to obtain the name of the current host is specified by the symbol GETHOST. If this symbol is not defined, the appropriate default is chosen based on BSD or SYSV with this code:

    #if	!defined(GETHOST)
    #	if	UNIXTYPE == BSD
    #		define	GETHOST	hostname
    #	else
    #		define	GETHOST	uname -n
    #	endif
    #endif

### Library post-processing (ranlib)

The program to run to properly post-process an archive which is intended to be a subroutine library is specified by the symbol RANLIB. The default values are chosen with the code below. Note that on older System V release, no post-processing is possible, so the command echo is substituted.

    #if	!defined(RANLIB)
    #	if	UNIXTYPE == BSD
    #		define	RANLIB	ranlib
    #	else
    #		define	RANLIB	ranlib5.sh
    #	endif
    #endif

### libfb configuration

The configuration for the framebuffer library is specified by the two symbols LIBFB_CONFIG, LIBFB_OBJS. If these two symbols are not defined in the configuration that you provide, then they will be defaulted using this code:

    #if !defined(LIBFB_OBJS) || !defined(LIBFB_CONFIG)
    #	if HAS_TCP == 0
    #		define	LIBFB_OBJS	if_ptty
    #		define	LIBFB_CONFIG	-DIF_PTTY
    #	else
    #		define	LIBFB_OBJS	if_remote pkg if_ptty
    #		define	LIBFB_CONFIG	-DIF_REMOTE -DIF_PTTY
    #	endif
    #endif

If this is a TCP-capable system, the defaults provide for including the "remote" network framebuffer capability, in addition to the terminal-line AT&T 5620 "ptty" interface. The LIBFB_OBJS symbol is given the base name of all the object modules to be included, and the LIBFB_CONFIG symbol is given all the C compiler definitions necessary to incorporate the extern linkages to the desired object modules, via the array in libfb/fb_generic.c.

Even if your configuration has no display hardware specified, this library is necessary, as the debug and disk-file interfaces are always useful. Lacking any displays at all, you may be able to utilize the bw-impress(1) program to produce pictures on an Imagen laser-printer, or bw-px(1) to produce a PostScript image.

The philosophy of libfb is that it is a fully self-contained library. An applications program that desires to have framebuffer support need only link with libfb, and all subroutines that may be needed on that machine will be provided. Frequently, this means that libfb will have to include object modules drawn from one or more vendor-specific libraries, as well as the object modules from the BRL-CAD source files. If the symbol LIBFB_SETUP is defined, then libfb/Cakefile will run that string as a Shell command before creating the libfb archive. This is used to add object modules from vendor-specific libraries. For an example of how this is used, see the SGI or Cray configurations.

For example, to configure a system to support the Raster Technology display attached to a parallel port, these lines would be added to the system-specific configuration:

    #	define	LIBFB_CONFIG	-DIF_RAT
    #	define	LIBFB_OBJS	if_rat

No vendor-specific library is required for the Raster Technology support.

As another example, for a SUN system of release 3.2 or higher, configuring both the display and also the network framebuffer capability (since all SUN systems support TCP/IP networking), these definitions would be used. This is taken directly from Cakefile.defs:

    #	define	LIBFB_OBJS	if_remote if_ab if_sun
    #	define	LIBFB_CONFIG	-DIF_REMOTE -DIF_AB -DIF_SUN
    #	define	LIBFB_LIBES	LIBPKG -lsuntool -lsunwindow -lpixrect

The first important thing to note is that when adding support for the network "remote" framebuffer capability, "if_remote" is listed as an object file, and "LIBPKG" is added to the library list for the network interface routines. Also note that the definition of LIBFB_LIBES mentions three SUN-specific libraries that will also be used when building applications that use LIBFB.

As a final example, configuring a machine to use the X Window System (X11) as a framebuffer might use these definitions:

    #	define  LIBFB_OBJS      if_remote if_X
    #	define  LIBFB_CONFIG    -DIF_REMOTE -DIF_X -I/usr/local/include/X11
    #	define	LIBFB_LIBES	LIBPKG -L/usr/local/lib/X11 -lX11

Note how the X11 include directory may need to be added to LIBFB_CONFIG, and the location of the X11 library may need to be indicated with a "-L" flag in LIBFB_LIBES.

If you change the configuration of libfb partway through building the system, be certain to run

    	cd libfb
    	cake clobber
    	cake

before recompiling other programs, because the external symbols compiled into the binaries change based on the configuration options in Cakefile.defs.

## mged Configuration

All versions of mged have support for the four display devices listed at the beginning of this document. If the symbols MGED_CONFIG, MGED_OBJS, and MGED_LIBES are not defined, then a version of mged will be built that contains only the standard display handlers. In addition, a variety of optional display devices are also supported; the list also appears at the beginning of this document.

For example, to configure an SGI Iris 3-D ("ir") running version 3.5 of the software, with XNS networking, specify:

    #	define	MGED_CONFIG	-DDM_IR  -DNOBLOCK
    #	define	MGED_OBJS	dm-ir
    #	define	MGED_LIBES	-lbsd -lgl2

Note the necessary vendor-supplied libraries must be listed on the MGED_LIBES line.

## h/machine.h

The file "h/machine.h" has a number of configuration options, including the setting of:

fastf_t | fastest "C" floating point type (float or double)
LOCAL | static or auto, for fastest local data type.
FAST | LOCAL or register, for FAST fastf_t variables.
PARALLEL | Defined for parallel processors.

VAX, GOULD, Cray, Alliant and HEP examples are provided. The defaults should be correct for reasonable 32-bit serial computers. Note that K&R ``C'' specifies that all floating point calculations must be done as double, so it is usually fastest to set fastf_t to double. Also note that when fastf_t is float in 32-bit IEEE or IBM style floating point, not enough accuracy is carried to correctly process large models. See the "Silicon Graphics Warnings" section for more information.

## h/rle.h

The file h/rle.h has #if statements that will need modification if your machine is a "Little-Endian" machine and your machine is not a VAX. "Big-Endian" machines will work without modification. A Big-Endian machine has byte [0] on the left of the word, like IBM, while a Little-Endian machine has byte [0] on the right side of the word, like DEC. Some of the liborle code needs to know.

## libplot3/htond.c

This routine converts between the native machine floating point format, and IEEE double precision floating point. This is especially important for generating binary portable plot metafiles. If the machine that you are porting to implements one of the already supported native types, all you need to do is adjust the #if directives for the symbol NATURAL_IEEE to include your machine type. (Please notify ARL when you do this, so that we can update the master copy).

If it seems that your machine uses a novel internal floating point format, you may have to write some code to perform the conversion. Before undertaking such an effort, please read the file "papers/dist-graphics", Workstations, Networking, Distributed Graphics, and Parallel Processing, where this whole issue is discussed in great detail. You may also wish to contact ARL via E-mail to see whether support for your machine has already been accomplished by others.

## Adding Support For New Displays

If you desire to add support for a new display, there are only two modules that you will have to create. The first will be for the framebuffer library (see libfb(3) for more details). A template for creating interfaces to new devices is provided as libfb/if_TEMPLATE.c. The second module needed is an mged display manager, like mged/dm-XX.c. Here, the task is somewhat harder, as two major modes of behavior are supported: displaylist and refresh. You should examine display managers for devices similar to yours, and proceed from there. ARL would be most interested in obtaining any additional display modules that you might develop, should you wish to share them.

## Potential Optimizations

After initial testing, you may wish to go back and enable the special assembler version of sqrt(), by uncommenting and editing the FAST_SQRT line in "librt/Makefile.loc". 4.2BSD VAX and Gould UTX 1.2 versions are provided. Note that the 4.3BSD VAX library sqrt() is even faster than this one by more than 40%.

The file "h/vmath.h" has macros for numerous common vector operations; if your system has hardware support for vector operations, after getting the program working you would profit greatly from changing these macros to machine-specific code. If you do this, please submit the "rays/sec" figures for the original as well as the optimized runs.

ARL is currently working with compilers that detect implicit vectorization. The full results of this work will be included in a subsequent release.

# DIFFICULTIES

If you are experiencing difficulty with one of the provided configurations, Cakefile.defs is the most important file to scrutinize. See SUPPORTING A NEW MACHINE.

## Extreme difficulty with libfb

In the case of extreme difficulty, a no-op stub version of libfb is provided in rt/libfb-dummy.c. This can be substituted for "libfb.a" in order to run the rt benchmark.

## Changing Configurations of libfb, mged, librt

For libfb, mged, and librt, it is also necessary to run "cake clean" in those directories after making related changes to Cakefile or ../Cakefile.defs, because the compiled binaries of some modules depend on configuration options selected in the Cakefiles. Failure to do this is the single most common cause of difficulty when experimenting with the configuration of this software. To be ultra conservative, after each major change of a configuration file, it would be wise to run cake clobber in the top directory, and then recompile.

# LIVING WITH SHARED LIBRARIES

Many modern versions of UNIX offer shared libraries, and this BRL-CAD release takes advantage of them on the Sun and SGI platforms. For BRL-CAD modelers, shared libraries save a lot of disk space and represent only a minute performance loss. For BRL-CAD developers who are making changes to the libraries, shared libraries offer an additional detail to keep track of. In particular, when a new shared library is installed, all the programs will start using it the next time they are run, even without being explicitly recompiled. If data structures in raytrace.h were changed, this could be disasterous. There are several different ways developers can cope with this:

1. Disable shared library support in Cakefile.defs, and run

       	cake clobber

       	cake install

   to build non-shared libraries and programs.
2. In /usr/brlcad/lib, make symlinks from your_source_dir/librt/librt.so to /usr/brlcad/lib, e.g.:

       	cd /usr/brlcad/lib

       	ln -s your_source_dir/librt/librt.so .

   for each of the libraries that you plan to be working on. Note that this makes the system "installed" version of the library your development copy. This is only a reasonable policy if the developer(s) are the only users of this particular machine.
3. On SunOS 4 machines only, the development tree executables are able to find the development tree libraries automaticly. E.g. your_source_dir/rt/rt will automaticly attempt to use ../librt/librt.so before resorting to the installed version in /usr/irlcad/lib/librt.so. Sadly, this feature does not work on SunOS 5 and SGI platforms.
4. You can attempt to play games with your environment variable LD_LIBRARY_PATH, to control which library versions you are using.

# KNOWN PROBLEMS

## CAKE Warning Message

Occasionally, CAKE will print the message

    NOTE:  Null action skipped

This warning message is not harmful, and may safely be ignored.

## System V Documenters Workbench Unbundled

In recent releases of System V, DWB has been unbundled. This means that for these systems, the man command no longer runs nroff to typeset the manual pages as they are needed. As a result, a new strategy is employed for installing manual pages. They now go in INSTDIR/man/man1, man3, and man5, rather than into the system's manual directories. At a minimum, this means that your users will have to add /usr/brlcad/man to their MANPATH environment variable.

If your man command does not honor the MANPATH variable, or your system does not have DWB installed, then you can always fall back to using the brlman command. A replacement for nroff known as awf is provided, and is used as the basis for the brlman command (which is just a shell script). awf is the Amazingly Workable Formatter, kindly provided by Henry Spencer at U of Toronto Zoology, <henry@zoo.toronto.edu>. In this way, all systems can have nicely formatted manual pages online, while leaving the sources for the manual pages in nroff format.

## DEC VAX, 4.1 BSD and DEC Ultrix

The C compiler on 4.1 BSD UNIX systems, and on DEC Ultrix systems is unable to handle pointers to functions which return void. In the section of Cakefile.defs for the VAX, it is necessary to uncomment this definition, which maps all void objects to int objects, a harmless workaround:

    	#	define	CC_DEFS	-Dvoid=int

## SILICON GRAPHICS 3-D WARNINGS

The SGI IRIS workstations in the 2400, 2400 Turbo, or 3000 series have been affectionately nicknamed the "3D" machines, since they came before the newer "4D" machines.

If you are attempting to run the benchmarks, beware of the long float -vs- double controversy. The SGI C compiler converts both float and double to 32-bit single-precision numbers. While the current release of librt is believed to generally operate correctly in spite of this, beware of the rt program failing to find roots, or being unable to perform a "box push". Unfortunately, the "star.pix" rt benchmark will fail due to lack of floating point precision, and generate lots of diagnostics, filling your disk.

SGI 3-D software release version 3.3.1, 3.4, and 3.5 have a defective library version of hypot(); be aware of the (slower) substitute in "rt/machine.c".

Operations of the form "*fp += incr;" are known to compile incorrectly on SGI 3-D release 3.5 when "fp" is declared as "register double *fp" (or register float). The one known instance of this in util/bwmod.c has been "fixed" with a #ifdef sgi.

When running MGED on a 3.5 Iris with XNS networking, there is no select() capability, so non-blocking I/O has to be used instead. This has two undesirable side effects. First, it puts MGED into a hard loop polling the workstation keyboard. Second, it seems to have an interaction with control-S/control-Q flow control -- if you suspend output, most of it will be discarded. However, MGED is still somewhat usable in this configuraition.

On an SGI 3-D, warning messages from the compiler of the form:

    "../h/rle.h", line 88: warning: field 'opcode' - bitfields are inherently unsigned.
    "../h/rle.h", line 88: warning: field 'datum' - bitfields are inherently unsigned.

may safely be ignored.

Under SGI Release 3.5, the invocation of the sort command that is used to build the font table for the program tools/rleClock is not handled properly, resulting in a bad input file and compiler errors. You can safely do without this program.

As a helpful hint, it is very useful to add a "gclear" account to each SGI 3-D system, so that after using the screen in 24-bit mode when not logged into the console, you can regain control of the screen by typing "gclear". By having a "gclear" account, typing "gclear" will always succeed whether or not you are logged in. Add this line to /etc/passwd:

    gclear::4:5::/tmp:/usr/bin/gclear

Currently there are no good solutions to these problems. Voice your opinions to the vendor.

## SILICON GRAPHICS 4-D WARNINGS

There is utterly no support for SGI 4-D machines running SGI software releases earlier than 4.0 \(em they don't work well. Similarly, IRIX 6.0 had not been released at the time BRL-CAD Release 4.4 was being finalized, so it is unclear how well this combination will work. Contact ARL for an errata sheet when IRIX 6.0 is available.

### SGI IRIX 4.0.5

When compiling on IRIX 4.0.5, the module librt/machine.c trips over an SGI C compiler bug, producing the following warning:

    /usr/bin/cc -G 9 -ansiposix -DIRIX=4 -O2 -I''../h -DSYSV -c ../librt/machine.c

    accom: Warning 182: ../librt/machine.c, line 297: void * and function pointers are not convertible to each other

            void    (*func)() = (void (*)())arg;

This warning can safely be ignored.

When linking (loading) programs on IRIX 4.0.5 which use LIBRT and thus use the SGI multi-processing library -lmpc, the following spurious warning messages are produced:

    /usr/bin/ld:^M
    Warning: _oserror: multiply defined
            previous (used) definition from '/usr/lib/libmpc.a';
            new (ignored) definition from '/usr/lib/libc_s.a'
    Warning: _setoserror: multiply defined
            previous (used) definition from '/usr/lib/libmpc.a';
            new (ignored) definition from '/usr/lib/libc_s.a'

These warnings can safely be ignored; we could find no way to suppress them.

Most importantly, the "moss" and "world" benchmarks no longer produce images that match the reference images. This results in the "run.sh" script printing these messages:

    +++++ moss
    pixcmp bytes:  786425 matching,       5 off by 1,       2 off by many
    moss.pix: WRONG WRONG WRONG WRONG WRONG WRONG
    +++++ world
    pixcmp bytes:  786417 matching,      12 off by 1,       3 off by many
    world.pix: WRONG WRONG WRONG WRONG WRONG WRONG

The difference seems to occur at three locations where the eye ray just grazes the edge of the yellow torus. Since these differences do not occur on other architectures or on more recent SGI software releases, our current assumption is that this is probably due to a compiler or OS-release specific interaction with the IEEE rounding modes of the processor hardware. As we are about to phase out Irix 4.0.5 in favor of Irix 5.3 for all ARL SGI machines, this puzzle does not seem worth pursuing.

### SGI IRIX 5.2

When compiling on IRIX 5.2 using shared libraries, many times the SGI loader will produce the following warning(s):

    ld:
    The shared object /usr/lib/libm.so did not resolve any symbols.
            You may want to remove it from your link line.
    The shared object ../libsysv/libsysv.so did not resolve any symbols.
            You may want to remove it from your link line.

This warning can safely be ignored. The documentation states that the -S option given to the loader will suppress loader warnings like this, but when specified, causes the loader to issue an additional warning stating that the -S option is unimplemented.

### SGI IRIX 6.0

The hardware semaphore support needed for running RT and LGT in multi-processor mode is broken in Irix 6.0. SGI claims that this is fixed in Irix 6.0.1; you will need to modify librt/machine.c to eliminate the software workaround currently employed.

When building 64-bit executables under Irix 6.0, the SGI graphics libarary "GL" is not supported. SGI tells us that they only intend to support Open-GL on 64-bit platforms. We have OpenGL modules for LIBFB and MGED underway, but they are not ready yet. In the meantime, Irix 6.0 platforms are limited to using the remote framebuffer and X11 interfaces.

XMGED can not yet be successfully compiled on Irix 6.0, either. Bummer.

## ALLIANT WARNINGS

Under Concentrix 5.0, the module librt/machine.c causes the optimizer to dump core. If you compile it without optimization before compiling everything else, this will avoid the trouble:

    cd librt

    cc -ce -I../h -DBSD=42 -c ../librt/machine.c

    cake

## CRAY WARNINGS

When performing multi-tasking on either the XMP or the Cray-2, the librt/timerunix.c routine has great difficulty in collecting correct timing. On the average, one run in four will have correct timing data. This is due to a wierd interaction between the Cray multi-tasking library and the UNIX times() system call. In particular, the multi-tasking library provides an arbitrary mapping between ``virtual cpu'' and tfork()-ed UNIX process, so that the ``main'' thread of control can land in any process in the multi-tasking group \(em but only one of those processes is the parent process, where timing data is being collected. Presently, there is no known fix, except to re-run the benchmarks many times, and only use timing data from runs where the ``rt_parallel: PID changed ...'' warning does not occur.

Ignore warning messags of this form:

     *** *** SC1130 [caution ] < File = ../librt/vert.c, line = 337 > :

             Code was not generated for the block beginning at or corresponding to this statement (or part of it), because there is no path to it or it is not necessary.

In remrt, ignore the error messages:

     *** *** SC065 [caution ] < ../remrt/remrt.c, Line = 29, File = /usr/include/netdb.h line = 34 > :

             Invalid characters appear before a new-line in the '#else' directive.

     *** *** SC065 [caution ] < ../remrt/remrt.c, Line = 29, File = /usr/include/netdb.h line = 37 > :

             Invalid characters appear before a new-line in the '#endif' directive.

and the like; they are due to non-ANSI-C constructs in system include files provided by Cray.

It is safe to ignore the self-laudatory messages of the form:

    * Loop Vectorized at 181 in foo$c

Various remarks from CFT77 regarding the Whetstone tests can also be ingored.

## CONVEX Warnings

When compiling on the Convex it is safe to ignore messages of the forms:

    cc: Warning on line 849 of machine.c: saw asm statement in 'RES_ACQUIRE',
    optimization level reduced to -O0.

    cc: Warning on line X of fbstretch.c: expression statement has no effect

## SUN PROBLEMS

A problem with keyboard command input to mged being ignored has been seen when running mged on a color Sun workstation running SunOS 3.4. This problem does not affect C-Shell (csh) users, only Bourne Shell (/bin/sh) users, and has something to do with SunView changing the process group of mged when the local graphics window is opened. If you are a Bourne Shell user and you experience this problem, try running csh before starting mged.

## DEC ALPHA PROBLEMS

The DEC Alpha system running DEC OSF/1 V3.0 has a bug in /bin/sh which causes the Shell to segmentation fault when executing this line:

                  eval `grep '^RELEASE=' ../gen.sh`

in the files newvers.sh and sharedlibvers.sh, which is of course a perfectly good shell command. The error message is a bit cryptic and will look like this:

     ../newvers.sh libsysv_version "BRL-CAD System V Compatibility Library"
     ../newvers.sh: no space

There are workarounds included in both shell scripts, simply comment out the defective line and uncomment the workaround, and all will be well. A bug report has been filed with the vendor.

When the DEC loader builds a shared library, it insists on printout out a list of all the external symbols referenced by that library, even though the -S flag has been given. These messages are unsightly but not harmful.

# ENHANCEMENTS

If you develop additional software for the BRL-CAD environment that you would be willing to share, please send it to us for inclusion in the next release. The first such inclusion was the Utah Raster Toolkit, included "as is" in the directory contributed and integrated into the system in the directories tools and librle. Note that ARL considers the RLE format a long-term image storage format, with pix(5) format used for image manipulation, while Utah uses RLE format for all manipulation stages as well.

# UPGRADING FROM RELEASE 1.20 to 2.0

Release 2.0 contains only minor external changes from Release 1.20, but for complete safety, you should save the old binary to "conv/g2asc" someplace safe, so that if you find the binary format of the database incompatible you can convert your old databases from binary to ASCII form. Having to do this is system dependent (only Sun, SGI, and Alliant users are likely to be affected), but it is difficult to recover from without having saved the old converter (or your old distribution tape).

# UPGRADING FROM RELEASE 2.0 to 2.3

Primarily, Release 2.3 is a maintenance release, with lots of little nits resolved, along with a few new features being added. The major weak area is still Sun display support. In particular, using RT from within MGED fails miserably.

This release contains different and better support for multiple lights in RT, along with a standardized shader interface, and stackable shaders. Support for polygonal objects is now correct, but slow. The spline code has been significantly improved. Some contributed code for the Raster Technologies One/80 has been included, but is untested. The library for procedurally generating databases ``libwdb'' is now included, along with some example uses in the directory ``proc-db''. The program ``rtwalk'' generates a viewpoint animation control script that takes the eye between given start and end points, without walking through any geometry. This is especially interesting when used on complex scenes like those made by proc-db/clutter.c.

# UPGRADING FROM RELEASE 2.3 to 3.0

Release 3.0 introduces a great many new features; too many to itemize here. In general there should be no difficulty upgrading from Release 2.3 to Release 3.0, with one exception.

All earlier editions of the BRL-CAD package used Version 2 of the Utah ``RLE'' (Run-Lenght Encoded) image format. The Utah Raster Toolkit uses Version 3, which is incompatible. In BRL-CAD Release 3.0, this latest Utah RLE format is adopted, to permit complete interoperability with all the Utah Toolkit software. For sites that may have stored images in the old RLE format, the old library now exists as liborle, and all the programs have had an "o" added to their name, e.g., the version of rle-fb which uses the old library is now orle-fb.

# UPGRADING FROM RELEASE 3.0 to 3.7

Release 3.7 is a maintenance release. Significant effort went into providing good support for the full line of SGI 4-D workstations. This included making the SGI 4-D framebuffer support work efficiently. Both color and monochrome Sun workstations are now supported, both in mged and in libfb. There is now support for X-windows in both mged and in libfb.

Some new features have been added, such as sliders for mged. This release also includes a network distributed version of the ray tracer, remrt. Support for each kind of primitive geometry has now been largely concentrated in the relevant librt module. Common database-handling code has been moved entirely into librt. See the file doc/rel3.1.doc for more details.

There have been no file format changes.

# UPGRADING FROM RELEASE 3.7 to 4.0

Release 4.0 is a major features release. Binary geometry databases (``.g'' files) are upwards compatible from Release 3.7 to Release 4.0, but not backwards compatible. In order to move a geometry database from a 4.0 system back to a 3.7 system, it is necessary to convert it to ASCII form with g2asc. The ASCII format is unchanged.

Release 4.0 contains an implementation of Kevin Weiler's n-Manifold Geometry capability, which can be used to convert CSG models into faceted boundary-representation approximations of the original shapes. Note that this software is still experimental in this release, and can only operate on very simple cases.

There are lots of new image processing and signal processing tools.

# UPGRADING FROM RELEASE 4.0 to 4.4

Release 4.4 is a maintenance release. Binary geometry databases (``.g'' files) are upwards compatible from Release 4.0 to Release 4.4, but not backwards compatible. Many new tools are provided as well.

The NMG database support, converters, import/export routines, MGED visualization, and MGED editing support are all operational and stable. LIBRT is able to ray-trace NMG solid from the database (either imported via a converter or created using MGED's facetize command). This code is very young, so if you encounter difficulty please submit a bug report. The NMG boolean code used by MGED's ev command still fails on a non-trivial number of cases. Only about 2/3 of the M-2 Bradley can be automaticly converted. It is anticipated that there will be substantial improvements in the robustness of this code as the support of the new LIBRT NMG ray-tracer is exploited.

This release contains data structure, import/export, and MGED visualization support for trimmed NURBS NMGs ("t-NURBS NMGs"). However there is no support for ray-tracing such objects yet. We plan on releaseing BRL-CAD Release 5.0 as soon as (1) t-NURBS NMGs can be ray-traced by LIBRT, and (2) everything has been converted to the new ".g" database file format.

Finally, Release 4.4 includes a very polished X-windows version of MGED dubbed XMGED, and an experimental TCL version of MGED dubbed TMGED. TCL provides MGED with a powerful interpreted command language that has variables and formulas, as well as access to X11 widgets via the Tk package and user extensibility. When XMGED and TMGED are merged in a future release, expect a quantum improvement in the power of MGED!

# COMMUNICATION

You are invited to participate in the InterNet electronic mailing lists on the BRL-CAD software, which are listed at on the Sourceforge project site Bug reports and discussions of new features are the main topics; volume of messages has been light (so far). Direct your bug reports to devs@brlcad.org if you simply wish to make a report without subscribing. If you find bugs, please report your experiences by E-mail, preferably by running the "cadbug.sh" script included in this distribution. While ARL makes no offer of support, we are most interested in hearing about your experiences. All bugs and issues reported using the "cadbug.sh" script will automaticly be entered into our bug-tracking database, which is available for public inspection on the World-Wide-Web. The URL to access this (and other online BRL-CAD) release information is:

http://brlcad.org/
General information and published reports on BRL-CAD is also available on the main website.

It is our intention to make substantial additional use of the World-Wide-Web in the comming months.