Real-Time Workshop®

Customizing the Build Process

Controlling the Compiling and Linking Phases of the Build Process

After generating code for a model, the Real-Time Workshop build process determines whether or not to compile and link an executable program. This decision is governed by the following:

• Generate code only option

  When you select this option, the Real-Time Workshop software generates code for the model, including a makefile.

• Generate makefile option

  When you clear this option, the Real-Time Workshop software does not generate a makefile for the model. You must specify any post code generation processing, including compilation and linking, as a user-defined command, as explained in Customizing Post Code Generation Build Processing.

• Makefile-only target

  The Microsoft Visual C++ Project Makefile versions of the grt, grt_malloc, and Real-Time Workshop Embedded Coder target configurations generate a Visual C++ project makefile (model.mak). To build an executable, you must open model.mak in the Visual C++ IDE and compile and link the model code.

• HOST template makefile variable

  The template makefile variable HOST identifies the type of system upon which your executable is intended to run. The variable can be set to one of three possible values: PC, UNIX, or ANY.

  By default, HOST is set to UNIX in template makefiles designed for use with The Open Group UNIX platforms (such as grt_unix.tmf), and to PC in the template makefiles designed for use with development systems for the PC (such as grt_vc.tmf).

  If the Simulink software is running on the same type of system as that specified by the HOST variable, then the executable is built. Otherwise,

  • If HOST = ANY, an executable is still built. This option is useful when you want to cross-compile a program for a system other than the one the Simulink software is running on.

  • Otherwise, processing stops after generating the model code and the makefile; the following message is displayed on the MATLAB command line.

    ### Make will not be invoked - template makefile is for a different host

• TGT_FCN_LIB template makefile variable

  The template makefile variable TGT_FCN_LIB specifies compiler command line options. The line in the makefile is TGT_FCN_LIB = |>TGT_FCN_LIB<|. By default, the Real-Time Workshop software expands the |>TGT_FCN_LIB<| token to match the setting of the Target function library option on the Real-Time Workshop/Interface pane of the Configuration Parameters dialog box. Possible values for this option include ANSI_C, C99 (ISO), and GNU99 (GNU). You can use this token in a makefile conditional statement to specify compiler options to be used. For example, if you set the token to C99 (ISO), the compiler might need an additional option set to support C99 library functions.

Back to Top

Cross-Compiling Code Generated on a Microsoft Windows System

If you need to generate code with the Real-Time Workshop software on a Microsoft Windows system but compile the generated code on a different supported platform, you can do so by modifying your TMF and model configuration parameters. For

example, you would need to do this if you develop applications with the MATLAB and Simulink products on a Windows system, but you run your generated code on a Linux system.

To set up a cross-compilation development environment, do the following (here a Linux system is the destination platform):

1. On your Windows system, copy the UNIX TMF for your target to a local directory. This will be your working directory for initiating code generation. For example, you might copy matlabroot/rtw/c/grt/grt_unix.tmf to D:/work/my_grt_unix.tmf.

2. Make the following changes to your copy of the TMF:

   • Add the following line near the SYS_TARGET_FILE = line:

      MAKEFILE_FILESEP = /

   • Search for the line 'ifeq ($(OPT_OPTS),$(DEFAULT_OPT_OPTS))' and, for each occurrence, remove the conditional logic and retain only the 'else' code. That is, remove everything from the 'if' to the 'else', inclusive, as well as the closing 'endif'. Only the lines from the 'else' portion should remain. This forces the run-time libraries to build for a Linux system.

3. Open your model and make the following changes in the Real-Time Workshop pane of the Configuration Parameters dialog:

   • Specify the name of your new TMF in the Template makefile text box (for example, my_grt_unix.tmf).

   • Select Generate code only and click Apply.

4. Generate the code.

5. If the build directory (directory from which the model was built) is not already Linux accessible, copy it to a Linux accessible path. For example, if your build directory for the generated code was D:\work\mymodel_grt_rtw, copy that entire directory tree to a path such as /home/user/mymodel_grt_rtw.

6. If the MATLAB directory tree on the Windows system is Linux accessible, skip this step. Otherwise, you must copy all the include and source directories to a Linux accessible drive partition, for example, /home/user/myinstall. These directories appear in the makefile after MATLAB_INCLUDES = and ADD_INCLUDES = and can be found by searching for $(MATLAB_ROOT). Any path that contains $(MATLAB_ROOT) must be copied. Here is an example list (your list will vary depending on your model):

   $(MATLAB_ROOT)/rtw/c/grt 
   $(MATLAB_ROOT)/extern/include 
   $(MATLAB_ROOT)/simulink/include 
   $(MATLAB_ROOT)/rtw/c/src 
   $(MATLAB_ROOT)/rtw/c/tools

   Additionally, paths containing $(MATLAB_ROOT) in the build rules (lines with %.o :) must be copied. For example, based on the build rule

   %.o : $(MATLAB_ROOT)/rtw/c/src/ext_mode/tcpip/%.c

   the following directory should be copied:

   $(MATLAB_ROOT)/rtw/c/src/ext_mode/tcpip

   Note   The path hierarchy relative to the MATLAB root must be maintained. For example, c:\MATLAB\rtw\c\tools\* would be copied to /home/user/mlroot/rtw/c/tools/*. For some blocksets, it is easiest to copy a higher-level directory that includes the subdirectories listed in the makefile. For example, the Signal Processing Blockset product requires the following directories to be copied: $(MATLAB_ROOT)/toolbox/dspblks $(MATLAB_ROOT)/toolbox/rtw/dspblks

7. Make the following changes to the generated makefile:

   • Set both MATLAB_ROOT and ALT_MATLAB_ROOT equal to the Linux accessible path to matlabroot (for example, home/user/myinstall).

   • Set COMPUTER to the appropriate computer value, such as GLNX86. Enter help computer in the MATLAB Command Window for a list of computer values.

   • In the ADD_INCLUDES list, change the build directory (designating the location of the generated code on the Windows system) and parent directories to Linux accessible include directories. For example, change D:\work\mymodel_grt_rtw\ to /home/user/mymodel_grt_rtw.

     Additionally, if matlabroot is a UNC path, such as \\my-server\myapps\matlab, replace the hard-coded MATLAB root with $(MATLAB_ROOT).

8. From a Linux shell, compile the code you generated on the Windows system. You can do this by running the generated model.bat file or by typing the make command line as it appears in the .bat file.

   Note   If errors occur during makefile execution, you may need to run the dos2unix utility on the makefile (for example, dos2unix mymodel.mk).

Back to Top

Controlling the Location and Naming of Libraries During the Build Process

Two configuration parameters, TargetPreCompLibLocation and TargetLibSuffix, are available for you to use to control values placed in Real-Time Workshop generated makefiles during the token expansion from template makefiles (TMFs). You can use these parameters to

• Specify the location of precompiled libraries, such as blockset libraries or the Real-Time Workshop library. Typically, a target has cross-compiled versions of these libraries and places them in a target-specific directory.

• Control the suffix applied to library file names (for example, _target.a or _target.lib).

Targets can set the parameters inside the system target file (STF) select callback. For example:

function mytarget_select_callback_handler(varargin)
    hDig=varargin{1};
    hSrc=varargin{2};
    slConfigUISetVal(hDig, hSrc,...
    'TargetPreCompLibLocation', 'c:\mytarget\precomplibs');
    slConfigUISetVal(hDig, hSrc, 'TargetLibSuffix',...
    '_diab.library');

The TMF has corresponding expansion tokens:

    |>EXPAND_LIBRARY_LOCATION<|
    |>EXPAND_LIBRARY_SUFFIX<|

Alternatively, you can use a call to the set_param function. For example:

set_param(model,'TargetPreCompLibLocation',...
'c:\mytarget\precomplibs');

Note   If your model contains referenced models, you can use the make option USE_MDLREF_LIBPATHS to control whether libraries used by the referenced models are copied to the parent model's build directory. For more information, see Controlling the Location of Model Reference Libraries.

Specifying the Location of Precompiled Libraries

Use the TargetPreCompLibLocation configuration parameter to:

• Override the precompiled library location specified in the rtwmakecfg.m file (see Using the rtwmakecfg.m API to Customize Generated Makefiles for details)

• Precompile and distribute target-specific versions of product libraries (for example, the Signal Processing Blockset product)

For a precompiled library, such as a blockset library or the Real-Time Workshop library, the location specified in rtwmakecfg.m is typically a location specific to the blockset or the Real-Time Workshop product. It is expected that the library will exist in this location and it is linked against during Real-Time Workshop builds.

However, for some applications, such as custom targets, it is preferable to locate the precompiled libraries in a target-specific or other alternate location rather than in the location specified in rtwmakecfg.m. For a custom target, the library is expected to be created using the target-specific cross-compiler and placed in the target-specific location for use during the Real-Time Workshop build process. All libraries intended to be supported by the target should be compiled and placed in the target-specific location.

You can set up the TargetPreCompLibLocation parameter in its select callback. The path that you specify for the parameter must be a fully qualified absolute path to the library location. Relative paths are not supported. For example:

slConfigUISetVal(hDlg, hSrc, 'TargetPreCompLibLocation',...
'c:\mytarget\precomplibs');

Alternatively, you set the parameter with a call to the set_param function. For example:

set_param(model,'TargetPreCompLibLocation',...
'c:\mytarget\precomplibs');

During the TMF-to-makefile conversion, the Real-Time Workshop build process replaces the token |>EXPAND_LIBRARY_LOCATION<| with the specified location in the rtwmakecfg.m file. For example, if the library name specified in the rtwmakecfg.m file is 'rtwlib', the TMF expands from:

LIBS += |>EXPAND_LIBRARY_LOCATION<|\|>EXPAND_LIBRARY_NAME<|\
|>EXPAND_LIBRARY_SUFFIX<|

to:

LIBS += c:\mytarget\precomplibs\rtwlib_diab.library

By default, TargetPreCompLibLocation is an empty string and the Real-Time Workshop build process uses the location specified in rtwmakecfg.m for the token replacement.

Controlling the Location of Model Reference Libraries

On platforms other than the Apple^® Macintosh^® platform, when building a model that uses referenced models, the Real-Time Workshop build process by default:

• Copies libraries used by the referenced models to the parent model's build directory

• Assigns the filenames of the libraries to MODELREF_LINK_LIBS in the generated makefile

For example, if a model includes a referenced model sub, the Real-Time Workshop build process assigns the library name sub_rtwlib.lib to MODELREF_LINK_LIBS and copies the library file to the parent model's build directory. This definition is then used in the final link line, which links the library into the final product (usually an executable). This technique minimizes the length of the link line.

On the Macintosh platform, and optionally on other platforms, the Real-Time Workshop build process:

• Does not copy libraries used by the referenced models to the parent model's build directory

• Assigns the relative paths and filenames of the libraries to MODELREF_LINK_LIBS in the generated makefile

When using this technique, the Real-Time Workshop build process assigns a relative path such as ../slprj/grt/sub/sub_rtwlib.lib to MODELREF_LINK_LIBS and uses the path to gain access to the library file at link time.

To change to the non-default behavior on platforms other than the Macintosh platform, enter the following command in the Make command field of the Real-Time Workshop pane of the Configuration Parameters dialog box:

make_rtw USE_MDLREF_LIBPATHS=1 

If you specify other Make command arguments, such as OPTS="-g", you can specify the multiple arguments in any order.

To return to the default behavior, set USE_MDLREF_LIBPATHS to 0, or remove it.

Controlling the Suffix Applied to Library File Names

Use the TargetLibSuffix configuration parameter to control the suffix applied to library names (for example, _target.lib or _target.a). The specified suffix string must include a period (.). You can apply TargetLibSuffix to the following libraries:

• Libraries on which a target depends, as specified in the rtwmakecfg.m API. You can use TargetLibSuffix to affect the suffix of both precompiled and non-precompiled libraries configured from the rtwmakecfg API. For details, see Using the rtwmakecfg.m API to Customize Generated Makefiles.

  In this case, a target can set the parameter in its select callback. For example:

  slConfigUISetVal(hDlg, hSrc, 'TargetLibSuffix',...
  '_diab.library');

  Alternatively, you can use a call to the set_param function. For example:

  set_param(model,'TargetLibSuffix','_diab.library');

  During the TMF-to-makefile conversion, the Real-Time Workshop build process replaces the token |>EXPAND_LIBRARY_SUFFIX<| with the specified suffix. For example, if the library name specified in the rtwmakecfg.m file is 'rtwlib', the TMF expands from:

  LIBS += |>EXPAND_LIBRARY_LOCATION<|\|>EXPAND_LIBRARY_NAME<|\
  |>EXPAND_LIBRARY_SUFFIX<|

  to:

  LIBS += c:\mytarget\precomplibs\rtwlib_diab.library

  By default, TargetLibSuffix is set to an empty string. In this case, the Real-Time Workshop build process replaces the token |>EXPAND_LIBRARY_SUFFIX<| with an empty string.

• Shared utility library and the model libraries created with model reference. For these cases, associated makefile variables do not require the |>EXPAND_LIBRARY_SUFFIX<| token. Instead, the Real-Time Workshop build process includes TargetLibSuffix implicitly. For example, for a top model named topmodel with submodels named submodel1 and submodel2, the top model's TMF is expanded from:

  SHARED_LIB         = |>SHARED_LIB<|
  MODELLIB           = |>MODELLIB<|
  MODELREF_LINK_LIBS = |>MODELREF_LINK_LIBS<|

  to:

  SHARED_LIB         = \
  ..\slprj\ert\_sharedutils\rtwshared_diab.library
  MODELLIB           = topmodellib_diab.library
  MODELREF_LINK_LIBS = \
  submodel1_rtwlib_diab.library submodel2_rtwlib_diab.library

  By default, the TargetLibSuffix parameter is an empty string. In this case, the Real-Time Workshop build process chooses a default suffix for these three tokens using a file extension of .lib on Windows hosts and .a on UNIX hosts. (For model reference libraries, the default suffix additionally includes _rtwlib.) For example, on a Windows host, the expanded makefile values would be:

  SHARED_LIB         = ..\slprj\ert\_sharedutils\rtwshared.lib
  MODELLIB           = topmodellib.lib
  MODELREF_LINK_LIBS = submodel1_rtwlib.lib submodel2_rtwlib.lib

Back to Top

Recompiling Precompiled Libraries

You can recompile precompiled libraries included as part of the Real-Time Workshop product, such as rtwlib or dsplib, by using a supplied M-file function, rtw_precompile_libs. You might consider doing this if you need to customize compiler settings for various platforms or environments. For details on using rtw_precompile_libs, see Precompiling S-Function Libraries.

Back to Top

Customizing Post Code Generation Build Processing

The Real-Time Workshop product provides a set of tools, including a build information object, you can use to customize build processing that occurs after code generation. You might use such customizations for target development or the integration of third-party tools into your application development environment. The next figure and the steps that follow show the general workflow for setting up such customizations.

1. Program the post code generation command.

2. Define the post code generation command.

3. Suppress makefile generation, if appropriate for your application.

4. Build the model.

5. Modify the command, if necessary, and rebuild the model. Repeat this step until the build results are acceptable.

Build Information Object

At the start of a model build, the Real-Time Workshop build process logs the following build option and dependency information to a temporary build information object:

• Compiler options

• Preprocessor identifier definitions

• Linker options

• Source files and paths

• Include files and paths

• Precompiled external libraries

You can retrieve information from and add information to this object by using an extensive set of functions. For a list of available functions and detailed function descriptions, see Functions — Alphabetical List in the Real-Time Workshop documentation. Programming a Post Code Generation Command explains how to use the functions to control post code generation build processing.

Programming a Post Code Generation Command

For certain applications, it might be necessary to control aspects of the build process after the code generation. For example, this is necessary when you develop your own target, or you want to apply an analysis tool to the generated code before continuing with the build process. You can apply this level of control to the build process by programming and then defining a post code generation command.

A post code generation command is an M-file that typically calls functions that get data from or add data to the model's build information object. You can program the command as a script or function.

If your post code generation command calls user-defined functions, make sure the functions are on the MATLAB path. If the Real-Time Workshop build process cannot find a function you use in your command, the build process errors out.

You can then call any combination of build information functions to customize the model's post code generation build processing.

The following example shows a fragment of a post code generation command that gets the filenames and paths of the source and include files generated for a model for analysis.

function analyzegencode(buildInfo)
% Get the names and paths of all source and include files
% generated for the model and then analyze them.

% buildInfo - build information for my model.

% Define cell array to hold data.
MyBuildInfo={};

% Get source file information.
MyBuildInfo.srcfiles=getSourceFiles(buildInfo, true, true);
MyBuildInfo.srcpaths=getSourcePaths(buildInfo, true);

% Get include (header) file information.
MyBuildInfo.incfiles=getIncludeFiles(buildInfo, true, true);
MyBuildInfo.incpaths=getIncludePaths(buildInfo, true);

% Analyze generated code.
.
.
.

For a list of available functions and detailed function descriptions, see Functions — Alphabetical List in the Real-Time Workshop documentation.

Defining a Post Code Generation Command

After you program a post code generation command, you need to inform the Real-Time Workshop build process that the command exists and to add it to the model's build processing. You do this by defining the command with the PostCodeGenCommand model configuration parameter. When you define a post code generation command, the Real-Time Workshop build process evaluates the command after generating and writing the model's code to disk and before generating a makefile.

As the following syntax lines show, the arguments that you specify when setting the configuration parameter varies depending on whether you program the command as a script, function, or set of functions.

Note   When defining the command as a function, you can specify an arbitrary number of input arguments. To pass the model's name and build information to the function, specify identifiers modelName and buildInfo as arguments.

Script

set_param(model, 'PostCodeGenCommand',...
'pcgScriptName');

Function

set_param(model, 'PostCodeGenCommand',...
 'pcgFunctionName(modelName)');

Multiple Functions

pcgFunctions=...
'pcgFunction1Name(modelName);...
pcgFunction2Name(buildInfo)';
set_param(model, 'PostCodeGenCommand',...
 pcgFunctions);

The following call to set_param defines PostCodGenCommand to evaluate the function analyzegencode.

set_param(model, 'PostCodeGenCommand',...
'analyzegencode(buildInfo)');

Suppressing Makefile Generation

The Real-Time Workshop product provides the ability to suppress makefile generation during the build process. For example, you might do this to integrate tools into the build process that are not driven by makefiles.

To instruct the Real-Time Workshop build process to not generate a makefile, do one of the following:

• Clear the Generate makefile option on the Real-Time Workshop pane of the Configuration Parameters dialog box.

• Set the value of the configuration parameter GenerateMakefile to off.

When you suppress makefile generation,

• You no longer can explicitly specify a make command or template makefile.

• You must specify your own instructions for any post code generation processing, including compilation and linking, in a post code generation command as explained in Programming a Post Code Generation Command and Defining a Post Code Generation Command.

Back to Top

Interacting with the Build Process

Validating Generated Code