We're hiring!

We're actively seeking developers and designers for our Ann Arbor & Detroit locations.

Avoid Putting Preprocessor Directives in .c Files

The C Language has a heavy reliance on the C Preprocessor (CPP)–a preprocessor is a program that runs over a set of text files replacing specific patterns as it goes. The more I use C, the more I’ve become convinced that the CPP should be used only very rarely in .c files (though limited use in a header file doesn’t bother me). A major exception to this is the use of the ‘#include’ statement to pull header files into .c files.

I have a couple main reasons to avoid the preprocessor in .c files:

  • It’s easy to add preprocessor statements, but hard to take them out. They are the ultimate quick fix, but the longer you use them, the more of them you’ll need to fix the next problem. Eventually they will take your code hostage, and the project descends into Preprocessor Hell — a place where it’s hard to determine what code is active and, if it is, what it does.
  • I don’t normally have a compelling reason to put macro definitions inside .c files. Adding them there clutters up the more important aspects of my project. I end up putting these in one of my various header files.

I want to point out one good way to avoid using preprocessor statements in .c files when dealing with multiple platforms. First, here’s a program that uses the preprocessor to differentiate between platform implementations:

#include "interface.h"

void initialize(void)
{
  puts("Common Initialize\n");

#if   defined(PLATFORM_A)
  puts("Initialize A\n");
#elif defined(PLATFORM_B)
  puts("Initialize B\n");
#else
  #error "Invalid platform."
#endif
}

void do_stuff(void)
{
  puts("Common Do Stuff\n");

#if   defined(PLATFORM_A)
  puts("Do Stuff A\n");
#elif defined(PLATFORM_B)
  puts("Do Stuff B\n");
#else
  #error "Invalid platform."
#endif
}

void cleanup(void)
{
  puts("Common Cleanup\n");

#if   defined(PLATFORM_A)
  puts("Cleanup A\n");
#elif defined(PLATFORM_B)
  puts("Cleanup B\n");
#else
  #error "Invalid platform."
#endif
}

In this example we can see that there’s common code in each of the three functions, but there are also sections specific to each of PLATFORM_A and PLATFORM_B. It’s not too hard to see how this becomes unmanageable with more than 2 platforms or more than a few functions.

Instead of using conditionals in .c files, I propose using a single header file that defines all of the interfaces each platform must implement. It might look something like this:

#ifndef __INTERFACE__
#define __INTERFACE__

void initialize(void);
void do_stuff(void);
void cleanup(void);

#endif /* __INTERFACE__ */

Once we have this interface defined, we just need to implement it once for each different platform. Here’s the first implementation:

#include <stdio.h>
#include "common.h"
#include "interface.h"

void initialize(void)
{
  common_initialize();
  puts("Initialize A\n");
}

void do_stuff(void)
{
  common_do_stuff();
  puts("Do Stuff A\n");
}

void cleanup(void)
{
  common_cleanup();
  puts("Cleanup A\n");
}

… and here’s the second:

#include <stdio.h>
#include "common.h"
#include "interface.h"

void initialize(void)
{
  common_initialize();
  puts("Initialize B\n");
}

void do_stuff(void)
{
  common_do_stuff();
  puts("Do Stuff B\n");
}

void cleanup(void)
{
  common_cleanup();
  puts("Cleanup B\n");
}

Notice that the compiler will prevent us from compiling both implementations at once since the symbol names would clash. The preprocessor prevents this with a #error statement in the #else branch, but what if this piece was forgotten? I think it’s safer and cleaner to push this logic into the build system in order to simplify the code. This isn’t hard to do especially if each of the platforms have a directory for platform specific code.

Using a common interface with multiple platform implementations has several advantages:

  • The compiler will help us catch missing portions or duplicate portions of the interface. A preprocessor-only implementation will not reliably help us catch these bugs.
  • The C files don’t need special analysis to figure out what code is active and what code isn’t active. This makes the code more maintainable in the future.
  • We completely avoid #ifdef hell.
  • The common interface header file serves as a template for adding new platforms.
  • Using different files for the platform-dependent code gives certain guarantees about independence. We can be confident we haven’t accidentally modified the code for the wrong platform.


I’ve put together a complete example of this anti-CPP-pattern in this GitHub gist. It consists of the following files:

  • main.c – the entry point which calls all three of the functions
  • common.h – some code that’s common to both platforms
  • common.c – implementation of common.h
  • interface.h – the interface file that defines the functions required by each platform
  • platform_a.c – the implementation of the interface for Platform A
  • platform_b.c – the implementation of the interface for Platform B
  • bad_way.c – both platforms implemented in a single file using the preprocessor to select which code to include


If you have GCC installed and in your path…

You can build the code for Platform A by running:

gcc main.c common.c platform_a.c -o platform_a


Platform B can be built with:

gcc main.c common.c platform_b.c -o platform_b


I’ve found build system and architectural changes preferable to the use of preprocessor statements in .c files.

What other ways are there to avoid overusing the preprocessor?

John Van Enk (31 Posts)

This entry was posted in Embedded Systems and tagged . Bookmark the permalink. Both comments and trackbacks are currently closed.

2 Comments

  1. Posted February 15, 2012 at 2:56 pm

    The C preprocessor is something one should avoid, it’ far too dumb to be of proper use but if find the solution you provide a bit complicated as it increases code replication and supporting several arch a bit more tedious, not everything can be moved to a safe common call not even when inlined. What I try is to confine the arch dependend code in as few modules as possible and there the preprocesor is permitted.

    Right now I’m getting tired of using the dumb c preprocesor, and I’m setting a better system for code configuration(let’s admit it, this is why we all use the c preprocesor) that enables better automation of testing and does validation of parameters before compilation. Right now this looks pretty much like a web framework.

    Regards

    • John Van Enk
      Posted February 15, 2012 at 3:09 pm

      I don’t mind this approach either. One tricky part about my suggestion is trying figure out at what granularity to make the common interface. I intentionally broke mine out at a high level. If left at this level, then you’re correct, there may be a lot of code duplication.

      As long as the CPP is made as marginal of a tool as possible in a project, I don’t mind it being there. Your suggestion to confine the preprocessor seems perfectly reasonable.