Sample Code Base#

This tutorial uses a sample code base designed to showcase the features of CBI.

Attention

To follow along with the tutorial, we first need a copy of the sample code base.

It can be downloaded from here or copied from the docs/source/sample-code-base directory on GitHub.

Directory Structure#

The sample code base consists of just a few source files, arranged as shown below:

src/
├── CMakeLists.txt
├── cpu
│   └── foo.cpp
├── gpu
│   └── foo.cpp
├── main.cpp
└── third-party
    ├── library.cpp
    └── library.h

Although simple, this structure is representative of many applications that target multiple platforms. The code base contains:

  • A directory (src) containing all of the source files required to build the application.

  • Two subdirectories (cpu and gpu) containing source files that are only used when building the application to target specific platforms.

  • Some shared source files (main.cpp) that are always used when building the application to target any platform.

  • Some third-party source files (third-party/library.h and third-party/library.cpp).

Tip

Generally speaking, “third party source files” just means “source files maintained by somebody else”. Even if we’re working with a code base without any external dependencies, treating code written by other developers or other teams as “third party source files” will allow us to limit our analysis to source files that we care about.

File Structure#

Let’s take a look at one of the files in the code base, main.cpp:

 1 // Copyright (c) 2024 Intel Corporation
 2 // SPDX-License-Identifier: 0BSD
 3 #include <cstdio>
 4 #include "third-party/library.h"
 5 void foo();
 6
 7 int main(int argc, char* argv[])
 8 {
 9 #if !defined(GPU_OFFLOAD)
10     printf("Running on the CPU.\n");
11 #else
12     printf("Running on the GPU.\n");
13 #endif
14     foo();
15     bar();
16 }

The preprocessor directives on Lines 9, 11 and 12 (#if, #else and #endif) define a specialization point, allowing Lines 10 and 12 to be specialized based on the value of a preprocessor macro (GPU_OFFLOAD). This approach is common in many C, C++ and Fortran applications.

Lines 3, 4 and 5 also define potential specialization points, because the compilation commands targeting different platforms may search different include paths and/or link against different libraries.

Note

Although this file contains 16 lines of text, CBI will count only 13 lines of code. Comments and whitespace do not count.