12. Compiling, linking, Makefile, header files

A common convention in C programs is to write a header file (with .h suffix) for each source file (.c suffix) that you link to your main source code. The logic is that the .c source file contains all of the code and the header file contains the function prototypes, that is, just a declaration of which functions can be found in the source file.

This is done for libraries that are provided by others, sometimes only as compiled binary "blobs" (i.e. you can't look at the source code). Pairing them with plain-text header files allows you see what functions are defined, and what arguments they take (and return).

Here is a program that computes the preferred direction of a neuron recorded in primary motor cortex of rhesus macaques, during a whole-arm reaching task (e.g. from Gribble & Scott, 2002). The monkey moved his hand from a central start target to one of 8 peripheral targets around the circumference of a circle. Movements to each of the 8 targets were repeated 5 times for a total of 40 movements. The order of target directions was randomized.

The data for each neuron are represented by two sets of values: first, an array of 40 values that indicate for each movement, the direction of the movement (specifically, the direction, in radians of the velocity vector at peak hand velocity), and second, another array of 40 values that indicate for each movement, the mean number of spikes per second averaged over a window starting 150ms before movement onset and ending at peak hand velocity.

For each neuron, the goal is to compute a preferred direction. That is, the direction of movement for which the neuron fires most enthusiastically (most spikes per second). The details of how these computations are done are not so important to consider here, but imagine for the moment that we have already written (or someone has provided us with) a C function called compute_PD() that performs this calculation, and that the code is stored in a file called neuron.c, with a header file neuron.h.

Here is our main program which is called go.c:

// gcc -std=c99 -o go go.c neuron.c -lm

#include <stdio.h>
#include <stdlib.h>
#include <string.h>
#include "neuron.h"

int main(int argc, char *argv[]) {

  int ncells = 100;                     // # cells to process
  char fnum[4], fname[128];              // filename strings
  double celldirs[40], cellspks[40];    // data for each cell
  double PD[ncells], plate_out[9];      // store cell PDs

  // loop to process each cell
  int i;
  for (i=1; i<=ncells; i++) {

    // construct the numeric part of the filename
    if (i<10) sprintf(fnum, "00%d", i);
    else if (i<100) sprintf(fnum, "0%d", i);
    else sprintf(fnum, "%d", i);

    // read in a dirs data file
    sprintf(fname, "data/cell_dirs_%s.txt", fnum);
    readcell(fname, celldirs, 40, 0);

    // read in a spks data file
    sprintf(fname, "data/cell_spks_%s.txt", fnum);
    readcell(fname, cellspks, 40, 0);

    // compute PD
    PD[i-1] = compute_PD(celldirs, cellspks, 40);
  }

  // print vector of PDs to screen and write to a file
  show_double_vec(PD, ncells);
  write_double_vec(PD, ncells, "PDs.txt");

  return 0;
}

What we can see is that on line 6, we use an #include statement to include the neuron.h header file (shown below). This is a way of essentially telling the compiler, that these functions (in neurons.h) will be described fully later … and for now, "trust" that they are defined, and in this particular way (inputs and outputs).

On line 1 (commented out) I show the gcc command to compile this program, and you can see that we simple add neuron.c to the list of files to send to the compiler. This is where the compiler actually integrates the code in neuron.c into our program. We also need the -lm flag, to instruct the compiler to load the standard C math library (since the #include <math.h> directive appears in neuron.h).

Here is the header file neuron.h:

#include <stdlib.h>
#include <stdio.h>
#include <math.h>

#ifndef M_PI
#define M_PI 3.1415926535897932384626433832795
#endif

void show_int_vec(int vec[], int n);

void show_double_vec(double vec[], int n);

void write_double_vec(double vec[], int n, char fname[]);

void showmat(double mat[], int nrows, int ncols);

void readcell(char fname[], double data[], int n, int msg);

void oneplate(double r1, double r2, double a1, double a2, double output[6]);

void platemethod(double a[], double r[], int n, double output[9]);

int mycomp(const void *a, const void *b);

double getangle(double x, double y);

int mycomp_struct(const void *a, const void *b);

double compute_PDr(double celldirs[], double cellspks[], int ntrials, int ndirs);

double compute_PD(double celldirs[], double cellspks[], int ntrials);

What you can see is that this is simply a listing of the functions that are defined in neuron.c, and we simply list the function prototypes, not the "meat" of the functions themselves. When we write the #include "neuron.h" statement at the top of go.c (line 6), these function prototypes are loaded in, so that the code in the main program "knows about" these functions. Note that there are some functions in here that we do not use in the go.c code above.

An important point to remember is that as long as we can look at the header file, we have all the information about what functions are defined in the source file, and how they are used (what their input arguments are and what output arguments, if any, they return). If we want to look "inside" those functions, we can look at the source file. The header file then can be thought of as an interface between the source code and the programmer.

To summarize then, in order to include external code in your C program (code that is located in a separate file), you need to make sure two things happen:

1. The external C source code is passed to the compiler at compile time
2. Your own C program has access to the function prototypes associated with the external code

Another small example: let's say you want to write a program that takes at the command-line one integer input, and determines whether that integer is a prime number or not. Now let's say that you don't want to write your own code for determining primality, so you ask your friend, who you know has written such a function already. She sends you a pair of files (primes.h and primes.c). Her header file (primes.h) looks like this:

int isPrime(int n); // returns 0 if n is not prime, 1 if n is prime

So we know a couple of things from this header file. It declares a function prototype for isPrime(). We can see this function takes a single integer as an input argument, and returns an integer value: 1 if the input value is a prime number, and 0 if it is not. Now we know all we need to know in order to use this function (without even looking at the function's source code, which resides in primes.c).

Here is what the primes.c file look like:

int isPrime(int n) {

  // returns 0 if not prime, 1 if prime

  if (n<2) return 0;         // first prime number is 2
  if (n==2) return 1;        // ensure 2 is identified as a prime
  if ((n % 2)==0) return 0;  // all even numbers above 2 are not prime

  int i;
  for (i=3; i*i < n; i++) {  // test divisibility up to sqrt(n)
    if ((n % i) == 0) {
      return 0;
    }
  }
  return 1;
}

Here is what our program go.c looks like:

/* go.c
   Takes one input argument from the command line, an integer,
   and returns 1 if the number is prime, and 0 if it is not.

   Compile with: gcc -o go go.c primes.c 
*/

#include <stdio.h>
#include <stdlib.h>
#include "primes.h"

int main(int argc, char *argv[]) {
  if (argc < 2) {
    printf("error: must provide a single integer value to test\n");
    return 1;
  }
  else {
    int n = atoi(argv[1]);
    int prime = isPrime(n);
    printf("isPrime(%d) = %d\n", n, prime);
    return 0;
  }
}

Here is the result of running the program on a small selection of input values:

plg@wildebeest:~/Desktop$ gcc -o go go.c primes.c
plg@wildebeest:~/Desktop$ ./go 1
isPrime(1) = 0
plg@wildebeest:~/Desktop$ ./go 2
isPrime(2) = 1
plg@wildebeest:~/Desktop$ ./go 3
isPrime(3) = 1
plg@wildebeest:~/Desktop$ ./go 63
isPrime(63) = 0
plg@wildebeest:~/Desktop$ ./go 67
isPrime(67) = 1
plg@wildebeest:~/Desktop$ ./go 12347
isPrime(12347) = 1

The compiler will look in several places for header files that you include with the #include directive, depending on how you use it. If you use include with the angled brackets (e.g. #include <stdio.h>) then the compiler will look in a series of "default" system-wide locations (see Search Path for details). If you use double-quotes (e.g. #include "neuron.h") then the compiler will look in the directory containing the current file. It's possible to add other directories to the search path by using the -Idir compiler option, where dir is the other directory. You might have to do this if you link your code to an external C library that is not part of the standard C library, and does not reside in the usual "system" default locations.

Just as we can include external code in our C programs, we can make a declaration in our C program that a variable exists and has been declared elsewhere (e.g. in some other source file). This is done using the extern keyword. See here for more details.

There are a number of features of a Makefile we can utilize to make the whole idea more useful. We can introduce "macros" (like a variable) to generalize the name of the C compiler to use, the flags to pass the compiler, the location of any library files, etc etc. Here is what a more generalized Makefile might look like for our primes example from above:

CC = gcc
CFLAGS = -Wall
DEPS = primes.h
OBJ = go.o primes.o

%.o: %.c $(DEPS)
        $(CC) $(CFLAGS) -c -o $@ $<

go: $(OBJ)
        gcc $(CFLAGS) -o $@ $^

You can see we have moved all the specific details (filenames, compiler flags, etc) into the macros on the top, and what remains below in the rules themselves, is expressed only in terms of those macros. There's nothing wrong with using a Makefile that is simple (as in Makefile1.txt, it is a choice for you about how fancy to get. The one limitation of Makefile1.txt is that the header file primes.h doesn't appear anywhere … this means if that file changes, then make will not think it has to recompile anything (because nothing in the rule "go" depends on primes.h). In Makefile2.txt, we introduce a dependency of .o files (on line 6) on $(DEPS), which is defined above on line 3, and includes the header file primes.h.

Note that we have term in the CFLAGS macro that looks like this: -Wall. This is a flag to the compiler to turn on all Warnings. There are many warnings that the compiler will tell you about, like variables that are never used, uninitialized variables, etc. Consult the documentation for full details.

Here is what it looks like when we run make using Makefile2.txt:

plg@wildebeest:~/Desktop/CBootCamp/code/primes$ cp Makefile2.txt Makefile
plg@wildebeest:~/Desktop/CBootCamp/code/primes$ make
gcc -c -o go.o go.c
gcc -c -o primes.o primes.c
gcc -o go go.o primes.o

You can see that in this case, three commands end up being run (lines 3-5).

Now the neat thing is, if we type make again (without changing anything) we get this:

plg@wildebeest:~/Desktop/CBootCamp/code/primes$ make
make: `go' is up to date.

We are told that the "go" rule is "up to date". The make program checks to see which files have changed since the last make, and only executes the step in the rule(s) (if any) that need to be done (it figures this out based on the dependencies that you set up in the rules).

In the long run, using Makefiles is a good idea, because:

• it's faster to recompile things (less typing, and it only recompiles based on what's changed and leaves the rest)
• it organizes all the "steps" in a (potentially complex) compilation into one place (the Makefile), which makes it easier for other people to compile your code

See the links below for more details and more examples of how GNU make can be used to your advantage.