Compiling

The next few sections outline the creation of a ``static library'' on GNU/Linux, and explain how to incorporate custom features at runtime. For more details, the source code, Makefile, and your system's documentation should provide a good start.

A small library is usually written as a header file, which contains function declarations (also called ``prototypes''), and a source file, which contains the actual code. Conventionally (under *nix), these files have extension .h and .cc respectively. Header and source files may ``include'' other header files, to incorporate additional functionality.

/* my_code.h */
#ifndef MY_CODE
#define MY_CODE
#include <cmath>   // standard library math header
#include "epix.h"  // ePiX header
using ePiX::P;

namespace Mine {   // to avoid name conflicts
  // functions for special relativity
  double lorentz_norm(P);
  bool   spacelike(P);
} // end of namespace
#endif // MY_CODE

This file exhibits two ``safety features''. The three MY_CODE lines prevent the file from being included multiple times. In a file of this size, inclusion protection is overkill, but as your code base grows and the number of header files increases, this protection is essential. Second, the header introduces a ``Mine'' namespace. Inside this namespace, two functions are declared as prototypes, giving the function's return type, name, and argument type(s). A header file should be commented fairly liberally, so that a year or two from now you'll be able to decipher the file's contents. For a longer file, version and contact information, an overall comment describing the file's features, and license information are appropriate.

Next, the corresponding source file; definitions are also placed into the namespace, and must match their prototypes from the header file exactly.

/* my_code.cc */
#include "my_code.h"
using namespace ePiX;

namespace Mine {
  double lorentz_norm(P arg)
  {
    double x=arg.x1(), y=arg.x2(), z=arg.x3(); // extract coords
    return -x*x + y*y + z*z;
  }
  bool spacelike(P arg)
  {
    return (lorentz_norm(arg) > 0); // true if inequality is
  }
} // end of namespace

Copies of these files are included with the source code so you can experiment with them. Next, the source file must be ``compiled'', ``archived'', and ``indexed''. In the commands below, the percent sign is the prompt.

% g++ -c my_code.cc
% ar -ru libcustom.a my_code.o
% ranlib libcustom.a

Please see your system documentation for details on command options and what each step does. For linking (below), the name of the library file must begin ``lib'' and have the extension .a. Once these steps are successfully completed, put the library libcustom.a and header file my_code.h in your project directory. You're ready to use the code in an ePiX figure.