[an error occurred while processing this directive] FTOOLS Home

General Guidelines

Before getting to specifics, there are a few general guidelines to keep in mind when writing FTOOLS. First of all, an FTOOLS package must be portable. What is a portable package? One that will compile and run on various platforms without user modification to the source code. If a user must edit a file that ends in c, f, h, or inc, the package isn't portable. This sounds obvious, but it's an easy goal to loose sight of. Portability is achieved through careful design of the source code itself and careful design of the build process.

Considering the source code itself, the programmer must remember that their code isn't meant for them - it's meant for a wide audience of people on various platforms at various places at various points in the future. If for some reason you don't want anyone else reading (understanding) your code, stop here. You want to distribute binaries and not source code. Everything about portable code doesn't apply because it will be your headache, not mine. With that in mind, your code needs to be straight forward and riddled with comments. Give a random page of what you've written to another programmer at your level. If they can't get a rough idea of what's happening with that chunk in 15 minutes, you've got a problem. Two years from now when you're trying to figure out why a section is segment faulting on a machine that doesn't exist today, you'll appreciate readable code.

Here are a few other points to keep in mind:

• Use macros when they make code clearer not because they're ``cool''. Nothing is more frustrating than having 50 macros defined, 90% of which perform tasks like adding two numbers. Seeing ``y = x + 4'' is much more clear than ``FOURADDXTOY(x,y);''.
• Write functions that do something. Wrappers are sometimes a necessary evil, but writing a one line function to ``personalize'' an existing library routine adds a layer of needless abstraction.
• Use only ANSI C and FORTRAN 77. Sure, there are a lot of great extensions out there and a lot of great languages. Unfortunately, they don't come bundled with every machine. Always stick to the lowest common denominator. (More specifics on this below.)
• Don't do bit manipulations on data-types you haven't created/defined. If you're worried about how many bits are in a long, or whether it's big-endian or not, you're going to have problems down the road.
• Use library routines that already exist. The added benefit to this is that part of the porting work for a new platform rests on someone else's back.

With the build procedure, the same general ideas presented for the source guidelines also apply. The goal is a process that's efficient, straight forward, and easy to translate to other architectures. In the build process you'll want to make all the necessary adjustments for the target platform/environment. This can of course be complicated at times, but it doesn't need to be oblique.

Points to consider when designing how your package compiles:

• Use a new GNU autoconfigure script and pass down flags if you need to customize for a platform.
• Shell scripts should use Bourne shell only. Korn, BASH, tcsh have nice features, but we want the common ground, not the high ground.
• Keep in mind that not every platform will have the same commands you do. Try to use macros ( ${MAKE}, ${CC}, ${RANLIB} ) instead of hard-coding commands in.
• Try to leave "pristine" copies of files that are configured. It's nice to be able to start from scratch without dumping the tarfile again.

Before going on to more specific points, let me leave you with the Golden Rules for FTOOLS Programming:

• Don't be clever; be clear.
• Use plain ANSI C and FORTRAN 77; don't use extensions (make sure you know what's an extension and what isn't - you may be surprised).
• Use FITSIO and CFITSIO. Don't roll your own.
• Test on as many platforms as possible. This means SunOS, Solaris, Linux, IRIX, OSF, Ultrix, VMS, and one IRAF flavor at a minimum.
• Don't be clever - CLEVER BAD. SIMPLE GOOD.

FTOOLS Home

[an error occurred while processing this directive]