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:

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.

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:

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

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

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

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 ARL.

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

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 symbolically 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 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

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 * */*

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

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

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

	rehash

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

	cake mkdir

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

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:

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

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. 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

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

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

	sh machinetype.sh -v

If machinetype.sh reports that HAS_TCP=0, i.e., 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 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:

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

	#	define	CC_OPTS	-f68881

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 support 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

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

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

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

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

	cd libfb
	cake clobber
	cake

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

h/machine.h

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

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.

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 disastrous. 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 automatically. E.g. your_source_dir/rt/rt will automatically 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

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, . 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 configuration.

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.

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;

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'

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

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.

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 library "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 weird 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 messages 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.

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 ignored.

CONVEX Warnings

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

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-Length 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.

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 automatically 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 releasing 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. 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 coming months.