Preprocess Complex Source Code for Bug Submissions

Introduction

You have discovered a problem when building your C/C++ code. You need to somehow send this code to TI so they can reproduce the problem. This may appear to be a difficult process. The code may include multiple levels of non-trivial header files. It may be part of a large Code Composer Studio (CCS) project. For convenience, or to protect your intellectual property (IP), you want to send as little as possible, yet still enough to reproduce the problem.

The answer is to use preprocessing.

Preprocessing Explained

The statements in C/C++ code that begin with # are all directives to the preprocessor phase of compilation. Preprocessing code means to process the # statements and nothing more. So, #include files get included, #define’s get evaluated and replaced, #if’s are processed, and so on. What you are left with is one self contained completely legal C/C++ file that has no preprocessing statements. In particular, you don’t have to worry with the header files any more. Usually, a preprocessed file isn’t much to look at, but rarely does that keep TI from working the problem.

How to Create a Preprocessed File

The details for creating a preprocessed file depend heavily on how you build your code. This section covers the process for two common build methods. You may have to change these methods a bit to account for how you do your build.

In general though, you build the problem file with all the same options as before, plus the options --preproc_with_comment --preproc_with_compile. This creates a preprocessed file that preserves comments. If you are especially concerned about protecting IP, use --preproc_only instead of --preproc_with_comment. The preprocessor options, by default, have the compiler stop when preprocessing is over. The option --preproc_with_compile makes the compiler continue on with normal compilation. The preprocessed file has the same base name as the source file, with the extension changed to .pp. This is the only source file you need to send to TI.

CCSv5.1 Method

This section presumes the problem source file is part of a project you build within CCS version 5.1.

• From the Project Explorer view, right-click the file name and select Build Options...
• Navigate the directory like path on the left to something like Build/C6000 Compiler. There might be an Advanced Options level to expand.
• Highlight Parser Preprocessing Options
• Change the Mode drop-down box from automatic (default) to manual
• Check the box for Preprocess only; maintain comments. If you are especially concerned about protecting your IP, then choose Preprocess only instead.
• Check the box for Continue compilation after using -pp<X> options
• Click OK

Now you are ready to build the preprocessed file.

• Right-click the file name and select Build Selected File(s)

A preprocessed file is created with the same base name as the source file, and the extension changed to .pp. For example, my_source.pp. This file is found in the same directory as the original source file. This is the file to send to TI. It is an ordinary text file. Don't be alarmed if it starts with many blank lines. That is not unusual. Note you can use the usual Windows operations to copy and paste this file from CCS.

Feel free to leave the above build option changes in place, or undo them.

Makefile Method

This section presumes you build with a makefile, and you have identified a single source file as the problem.

Start with this simple makefile. Presume iup.c is the problem file.

<syntaxhighlight lang='make'>

1. -----------------------------------------------------------------------------
2. Name the object files
3. -----------------------------------------------------------------------------

OBJS := icdct.obj isbt.obj iup.obj iwinm.obj mhead.obj towave.obj wavep.obj

1. -----------------------------------------------------------------------------
2. Develop C_OPTS: The compiler build options
3. -----------------------------------------------------------------------------
4. Optimization level 2

C_OPTS := $(C_OPTS) -o=2

1. Build for C6400+ processors

C_OPTS := $(C_OPTS) -mv6400+

1. Extra SW pipeline info

C_OPTS := $(C_OPTS) -mw

1. See C source like comments in assembly output

C_OPTS := $(C_OPTS) -s

1. -----------------------------------------------------------------------------
2. Link build rule
3. -----------------------------------------------------------------------------

mp3.out : $(OBJS) cl6x -z $(OBJS) -o=$@ lnk.cmd

1. -----------------------------------------------------------------------------
2. Compile build rule
3. -----------------------------------------------------------------------------

%.obj : %.c cl6x $(C_OPTS) $< </syntaxhighlight>

The first step is to add two options for preprocessing. Add the following lines to the C_OPTS part of the makefile.

<syntaxhighlight lang='make'>

1. Preprocessing which preserves comments

C_OPTS := $(C_OPTS) --preproc_with_comment

1. Compilation continues normally after preprocessing

C_OPTS := $(C_OPTS) --preproc_with_compile </syntaxhighlight>

If you are especially concerned about protecting IP, use --preproc_only instead of --preproc_with_comment.

Next, rebuild only iup.c. Here is one way to do that.

% rm iup.obj
% gmake iup.obj
cl6x  -o=2 -mv6400+ -mw -s --preproc_with_comment --preproc_with_compile iup.c

The file iup.pp appears in the current directory. It is an ordinary text file. Don't be alarmed if your .pp file starts with many blank lines. That is not unusual. Note iup.pp is the only file you need to send to TI.

Recent versions of the compiler include an option --pp_directory to control where .pp files are placed.

CCS 3.3

In CCS 3.3, you can right-click on the project, go into Build Options, Compiler tab, Category: Preprocessor, select the option from the Preprocessing drop-down list.

Change Extension When Attaching to Forum Post

This section presumes you need to attach the resulting .pp file to a post on the E2E forum. The forum only allows attachment of a few different kinds of files. Files with the extension .pp are rejected. Please rename the file to add the extension .txt, similar to my_source.pp.txt. Then you can attach it.

Confusion due to --preproc_dependency in CCS projects

The option --preproc_dependency (alias -ppd) also generates a file named with the .pp suffix, but its contents are entirely different from the preprocessed source code needed to diagnose problems. CCS uses this option to create dependence files for the Makefile to use to build projects. If you are trying to submit preprocessed source code, you must disable this option and enable one of the source-code-generating options above.