IN THE KNOW

Like LCAVision itself, its support libraries also continue to evolve. Responsibility for knowledge and support of these libraries is largely shared and in some cases even changing hands. For instance sharing John Shalf's knowledge about FlexIO is Thomas Radke out of Albert Einstein Institute in Potsdam Germany, and for TCPXX Werner Benger from that institute is also an excellent resource. Nevertheless, the breakdown noted above indicates who started the bulk of each code base and therefore who stands to know the most about it (or to know who knows the most about it, which is still better than nothing ;-)). For help with libraries written by "Others" refer to the originators of those libraries, most of whom should be reachable in one way or another from the information provided on the LCAVision website. Seeking others' help or ours is no substitute for the plethora of detailed documentation out there about LCAVision and all of the libraries it uses. Developers especially should be sought out only when all else fails. System administrators and in-house experts knowledgeable of your system should be your best friends during large-scale build processes such as it takes to build LCAVision from out of its many disparate yet powerful code bases. Keep telling yourself if it's this hard to build, imagine how hard it was to write all that code!

GENERAL PROCEDURES FOR REBUILDING

Typically the LCAVision distribution changes the most radically the most often. New features and bug fixes for the application are made all the time. Get them by doing a cvs update in the top-level LCAVisionX.x directory. Note: lately to update I have had to login to the pserver as when first checking out, then cvs -d update :pserver:anon@cvs.cactuscode.org:/packages update Then rebuild everything in the LCAVision distribution. For rebuilding, LCAVision's generic build script will _not_ solve all your problems. You will need to adapt to your system's quirks the makefile(s) produced by LCAVision's generic build script. The makefiles should not be affected by subsequent updates lest you build again. Because maintaining unique build scripts everywhere is its own messy business, we usually only build once and then work from there with the individual makefiles, changing a path or compiler flag here and there based on suggestions by those who know the particular system best. Once we get something to work, we _always_ keep a backup file of the original makefile or build script before changing it for a record to refer back to. We also carefully abstain from re-using the full-blown (and over-zealous) build script after that as much as possible to avoid all our crucial tweaks being mistakenly over-written. This is practical advice for building any large libraries, including the ones LCAVision depends on.

In the event newer distributions of LCAVision go to requiring a newer version of a library, you will need to update that library and all codes that depend on it before the LCAVision application can be considered updated and rebuilt in full. See the diagram above for a complete outline of dependencies.

CORE GRAPHICS LIBRARIES

Our inability to auto-determine whether your system wants OpenGL or Mesa is sometimes an issue, as is as our blindness to the location of these core graphics libraries on your system. You must make sure that vtk, fltk, & Vision compile using the same one of these libraries and all builds that need one of these graphics libraries find the correct one. This is sometimes tricky. You must know your system or someone who does and keep paths in makefiles and build scripts straight without spaces at the end of lines and/or mispellings.

NOT OUR PROBLEM BUT SUDDENLY OUR PROBLEM

From time to time the libraries from the group tagged "Others" in the diagram above are buggy or leave something to be desired in the way of ease-of-building. This has been the case with just about every one of them at one time or another. fltk, in which you must ensure the client (here Vision's) makefile specifies -I/usr/include _before_ the FLTK include of fltk's header files (one of which is math.h 8^P). vtk, in which the order of -lVTK<name> libraries is also crucial on LCAVision's link-line for similar reasons, the correct order being: -lVTKPatented -lVTKGraphics -lVTKImaging -lVTKCommon and more recently hdf5, which is still beta, so we forgive them somewhat for crashing us with a bug here or stopping our fun before it ever gets started with a compiler-incompatibility there. But we need these libraries and so do you to experience LCAVision in all its glory. The originators of the various libraries have active mailing lists and are generally friendly and full of good advice.

COMPATIBILITY: STATIC VERSUS SHARED LIBRARIES,
ARCHITECTURE DIFFERENCES

We most commonly link against static libraries if at all possible to ensure post-build compatibility with other systems and transferability of the executable across systems. Also, while the majority of workstations continue to transition from 32 to 64 bit architectures, we recommend building everything for the former. Again, in the name of usability independent of running under particular operating conditions. 64 bit machines should run 32 bit binaries fine but not vice-versa. And shared objects are great so long as they exist regularly in the same place everywhere you take the program to.

LOCATION OF LIBRARIES

You sometimes need to install files after they are processed by a build or make operation to a certain location. I still consider it best when building LCAVision to make sure all vtk header and library files are in an include and lib directory respectively off the VTKHOME directory. Same goes for FlexIO and fltk regarding their respective home directories. Even though for all these libraries LCAVision should be more lenient at this point about requiring of you this additional file management, I still make the subdirectories and copy changes there. I do it mainly because it's not hard and I never make assumptions about where a build script or makefile is looking to first or at all. Especially considering I know some of the build and make operations can take a _long_ time. I mentioned this, but it warrants repeating. When updating, also be sure that you overwrite all older files in the locations to which dependent codes are looking. If installation include or lib directories entirely miss a refresh, so will all code(s) further down the line. As a general rule, an include directory needs to get updated whenever you know the code may have changed, like when you re-download a library for instance. A lib directory, on the other hand, needs the freshest library files every time you rebuild. Most libraries like hdf for example make the install process a little nicer and more integrated with a make install feature, but I have found it's sometimes cryptic and a hassle and I don't always have the permissions to just accept where they want to install by default. Even providing your own path, you also have to be absolutely sure when rebuilding that your old install directories get cleaned out to be sure said directories definitely see the _newest_ updates as intended. Point here being, pay careful attention to where the result of builds and makes output to so those libraries can (continue to) be properly referenced by dependent codes.

We will do our best to try to incorporate other pertinent suggestions and observations into this document to help guide you in installing the program. Thanks for being patient. We hope and believe this is worth all the trouble.