coder.cinclude

Include header file in generated code

Syntax

coder.cinclude(headerfile)

coder.cinclude(headerfile,'InAllSourceFiles',allfiles)

Description

coder.cinclude(headerfile) includes a header file in generated C/C++ source code.

MATLAB^® Coder™ generates the include statement in the C/C++ source files that are generated from the MATLAB code that contains the coder.cinclude call.

For a Simulink model, when a MATLAB Function block includes a call to coder.cinclude, the code generator places the include statement in the C/C++ source file, where the code for corresponding MATLAB Function block is generated.

Note

In most cases, use coder.ceval (MATLAB Coder) with the "-headerfile" option instead of coder.cinclude. Use coder.cinclude only if you use coder.ceval to call multiple C/C++ functions defined in the same header file. You must call coder.cinclude before the corresponding coder.ceval call, and you must call coder.cinclude and coder.ceval in the same MATLAB function.

coder.cinclude(headerfile,'InAllSourceFiles',allfiles) uses the allfiles option to determine whether to include the header file in all generated C/C++ source files.

If allfiles is true, for MATLAB code and Simulink models that include the MATLAB Function block, the code generator places the include statement in all C/C++ source files, except some utility files. This behavior is the coder.cinclude behavior from R2016a and earlier releases. The presence of the include statement in these additional files can increase compile time and make the generated code less readable. If allfiles is false, the behavior is the same as the behavior of coder.cinclude(headerfile).

Examples

Include Header File in C/C++ Code Generated by Using the MATLAB Coder codegen Command

Generate code from a MATLAB function that calls an external C function. Use coder.cinclude to include the required header file in the generated C code.

In a writable folder, create a subfolder mycfiles.

Write a C function myMult2.c that doubles its input. Save it in mycfiles.

#include "myMult2.h"
double myMult2(double u)
{
    return 2 * u;
}

Write the header file myMult2.h. Save it in mycfiles.

#if !defined(MYMULT2)
#define MYMULT2
extern double myMult2(double);
#endif

Write a MATLAB function, myfunc, that includes myMult2.h and calls myMult2 for code generation only.

function y = myfunc
%#codegen
y = 21;
if ~coder.target('MATLAB')
    % Running in generated code
    coder.cinclude('myMult2.h');
    y = coder.ceval('myMult2', y);
else
    % Running in MATLAB
    y = y * 2;
end
end

Create a code configuration object for a static library. Specify the locations of myMult2.h and myMult2.c

cfg = coder.config('lib');
cfg.CustomInclude = fullfile(pwd,'mycfiles');
cfg.CustomSource = fullfile(pwd,'mycfiles','myMult2.c');

Generate the code.

codegen -config cfg myfunc -report

The file myfunc.c contains this statement:

#include "myMult2.h"

The include statement does not appear in any other file.

Include Header File in C/C++ Code Generated from a MATLAB Function Block in a Simulink Model

Generate code from a MATLAB Function block that calls an external C function. Use coder.cinclude to include the required header file in the generated C code.

In a writable folder, create a subfolder mycfiles.

Write a C function myMult2.c that doubles its input. Save it in mycfiles.

#include "myMult2.h"
double myMult2(double u)
{
    return 2 * u;
}

Write the header file myMult2.h. Save it in mycfiles.

#if !defined(MYMULT2)
#define MYMULT2
extern double myMult2(double);
#endif

Create a Simulink^® model that contains a MATLAB Function block connected to an Outport block.

In the MATLAB Function block, add the function myfunc that includes myMult2.h and calls myMult2.

function y = myfunc
%#codegen
y = 21;
coder.cinclude('myMult2.h');
y = coder.ceval('myMult2', y);
% Specify the locations of myMult2.h and myMult2.c
coder.extrinsic('pwd', 'fullfile');
customDir = coder.const(fullfile(pwd, 'mycfiles'));
coder.updateBuildInfo('addIncludePaths', customDir);
coder.updateBuildInfo('addSourcePaths', customDir);
coder.updateBuildInfo('addSourceFiles', 'myMult2.c');
end

Open the Configuration Parameters dialog box.

On the Solver pane, select a fixed-step solver.

Save the model as mymodel.

Build the model.

The file mymodel.c contains this statement:

#include "myMult2.h"

To read more about integrating custom code in a MATLAB Function block, see Integrate C Code by Using the MATLAB Function Block.

Input Arguments

headerfile — Name of header file

character vector | string scalar

Name of a header file specified as a character vector or string scalar. headerfile must be a compile-time constant.

Enclose a system header file name in angle brackets < >. The generated #include statement for a system header file has the format #include <sysheader>. A system header file must be in a standard location or on the include path. Specify the include path by using code generation custom code parameters.

Example: coder.cinclude('<sysheader.h>')

For a header file that is not a system header file, omit the angle brackets. The generated #include statement for a header file that is not a system header file has the format #include "myHeader". The header file must be in the current folder or on the include path. Specify the include path by using code generation custom code parameters.

Example: coder.cinclude('myheader.h')

Data Types: char

allfiles — All source files option

true | false

Option to include header file in all generated C/C++ source files. If allfiles is true, for MATLAB code and Simulink models that include the MATLAB Function block, the code generator places the include statement in all the C/C++ source files, except for some utility files. If allfiles is false, the behavior is the same as the behavior of coder.cinclude(headerfile).

In a MATLAB Function block, the code generator ignores the all source files option.

Data Types: logical

Limitations

• Do not call coder.cinclude inside runtime conditional constructs such as if statements, switch statements, while-loops, and for-loops. You can call coder.cinclude inside compile-time conditional statements, such as coder.target. For example:

  ...
   if ~coder.target('MATLAB')
     coder.cinclude('foo.h');
     coder.ceval('foo');
  end
  ...

Tips

• Before a coder.ceval call, call coder.cinclude to include the header file required by the external function that coder.ceval calls.

• Extraneous include statements in generated C/C++ code can increase compile time and reduce code readability. To avoid extraneous include statements in code generated by MATLAB Coder, follow these best practices:

  • Place a coder.cinclude call as close as possible to the coder.ceval call that requires the header file.

  • Do not set allfiles to true.

  For the MATLAB Function block, the code generator generates the include statement in the model source file (for example, model.c).

• In R2016a and earlier releases, for any coder.cinclude call, MATLAB Coder included the header file in almost all generated C/C++ source files, except for some utility files. If you have code that depends on this legacy behavior, you can preserve the legacy behavior by using this syntax:

  coder.cinclude(headerfile,'InAllSourceFiles',true)

Extended Capabilities

C/C++ Code Generation
Generate C and C++ code using MATLAB® Coder™.

GPU Code Generation
Generate CUDA® code for NVIDIA® GPUs using GPU Coder™.

HDL Code Generation

Generate VHDL, Verilog and SystemVerilog code for FPGA and ASIC designs using HDL Coder™.

The coder.cinclude function supports only MATLAB to High-Level Synthesis (HLS) workflow in HDL Coder™.

Version History

Introduced in R2013a