Real-Time Workshop

Template Makefiles

To configure or customize template makefiles, you should be familiar with how the make command works and how the make command processes makefiles. You should also understand makefile build rules. For information of these topics, please refer to the documentation provided with the make utility you use. There are also several good books on the make utility.

Template makefiles are made up of statements containing tokens. The Real-Time Workshop build process expands tokens and creates a makefile, model.mk. Template makefiles are designed to generate makefiles for specific compilers on specific platforms. The generated model.mk file is specifically tailored to compile and link code generated from your model, using commands specific to your development system.

Figure 14-5: Creation of model.mk

Template Makefile Tokens

The make_rtw M-file command (or a different command provided with some targets) directs the process of generating model.mk. The make_rtw command processes the template makefile specified on the Target configuration section of the Real-Time Workshop pane of the Simulation Parameters dialog. make_rtw copies the template makefile, line by line, expanding each token encountered. Table 14-3 lists the tokens and their expansions.

Table 14-3: Template Makefile Tokens Expanded by make_rtw 

Token	Expansion
|>COMPUTER<|	Computer type. See the MATLAB computer command.
|>MAKEFILE_NAME<|	model.mk -- The name of the makefile that was created from the template makefile.
|>MATLAB_ROOT<|	Path to where MATLAB is installed.
|>MATLAB_BIN<|	Location of the MATLAB executable.
|>MEM_ALLOC<|	Either RT_MALLOC or RT_STATIC. Indicates how memory is to be allocated.
|>MEXEXT<|	MEX-file extension. See the MATLAB mexext command.
|>MODEL_NAME<|	Name of the Simulink block diagram currently being built.
|>MODEL_MODULES<|	Any additional generated source (.c) modules. For example, you can split a large model into two files, model.c and model1.c. In this case, this token expands to model1.c.
|>MODEL_MODULES_OBJ<|	Object filenames (.obj) corresponding to any additional generated source (.c) modules.
|>MULTITASKING<|	True (1) if solver mode is multitasking, otherwise False (0).
|>NUMST<|	Number of sample times in the model.
|>RELEASE_VERSION<|	The release version of MATLAB.
|>S_FUNCTIONS<|	List of noninlined S-function (.c) sources.
|>S_FUNCTIONS_LIB<|	List of S-function libraries available for linking.
|>S_FUNCTIONS_OBJ<|	Object (.obj) file list corresponding to noninlined S-function sources.
|>SOLVER<|	Solver source filename, e.g., ode3.c.
|>SOLVER_OBJ<|	Solver object (.obj) filename, e.g., ode3.obj.
|>TID01EQ<|	True (1) if sampling rates of the continuous task and the first discrete task are equal, otherwise False (0).
|>NCSTATES<|	Number of continuous states.
|>BUILDARGS<|	Options passed to make_rtw. This token is provided so that the contents of your model.mk file will change when you change the build arguments, thus forcing an update of all modules when your build options change.
|>EXT_MODE<|	True (1) to enable generation of external mode support code, otherwise False (0).

These tokens are expanded by substitution of parameter values known to the build process. For example, if the source model contains blocks with two different sample times, the template makefile statement

• NUMST = |>NUMST<| 
  

expands to the following in model.mk.

• NUMST = 2 
  

In addition to the above, make_rtw expands tokens from other sources:

• Target-specific tokens defined via the Target configuration section of the Real-Time Workshop pane of the Simulation Parameters dialog box.
• Structures in the RTW Options section of the system target file. Any structures in the rtwoptions structure array that contain the field makevariable are expanded.

• The following example is extracted from matlabroot/rtw/c/grt/grt.tlc. The section starting with BEGIN_RTW_OPTIONS contains M-file code that sets up rtwoptions. The directive

  • rtwoptions(2).makevariable = 'EXT_MODE'
    

  causes the |>EXT_MODE<| token to be expanded into 1 (on) or 0 (off), depending on how you set the External mode option in the Code generation options section of the Real-Time Workshop pane.

The Make Command

After creating model.mk from your template makefile, Real-Time Workshop invokes a make command. To invoke make, Real-Time Workshop issues this command.

• makecommand -f model.mk
  

makecommand is defined by the MAKE macro in your system's template makefile (see Figure 14-6). You can specify additional options to make in the Make command field of the Real-Time Workshop pane. (see Make Command Field and Template Makefiles and Make Options.)

For example, specifying OPT_OPTS=-O2 in the Make command field causes make_rtw to generate the following make command.

• makecommand -f model.mk OPT_OPTS=-O2
  

A comment at the top of the template makefile specifies the available make command options. If these options do not provide you with enough flexibility, you can configure your own template makefile.

Make Utilities

The make utility lets you control nearly every aspect of building your real-time program. There are several different versions of make available. Real-Time Workshop provides the Free Software Foundation's GNU Make for both UNIX and PC platforms in the platform-specific subdirectories below matlabroot/rtw/bin.

It is possible to use other versions of make with Real-Time Workshop, although GNU Make is recommended. To ensure compatibility with Real-Time Workshop, make sure that your version of make supports the following command format.

• makecommand -f model.mk
  

Structure of the Template Makefile

A template makefile has four sections:

• The first section contains initial comments that describe what this makefile targets.
• The second section defines macros that tell make_rtw how to process the template makefile. The macros are:
• MAKE -- This is the command used to invoke the make utility. For example, if MAKE = mymake, then the make command invoked is

• mymake -f model.mk

• HOST -- What platform this template makefile is targeted for. This can be HOST=PC, UNIX, computer_name (see the MATLAB computer command), or ANY.
• BUILD -- This tells make_rtw whether or not (BUILD=yes or no) it should invoke make from the Real-Time Workshop build procedure.
• SYS_TARGET_FILE -- Name of the system target file. This is used for consistency checking by make_rtw to verify that the correct system target file was specified in the Target configuration section of the Real-Time Workshop pane of the Simulation Parameters dialog box.
• BUILD_SUCCESS -- An optional macro that specifies the build success string to be displayed on successful make completion on the PC. For example,

• BUILD_SUCCESS = ### Successful creation of

  The BUILD_SUCCESS macro, if used, replaces the standard build success string found in the template makefiles distributed with the bundled Real-Time Workshop targets (such as GRT):

  • @echo ### Created executable $(MODEL).exe
    

  Your template makefile must include either the standard build success string, or use the BUILD_SUCCESS macro. For an example of the use of BUILD_SUCCESS, see

  • matlabroot/toolbox/rtw/c/grt/grt_bc.tmf
    

• BUILD_ERROR -- An optional macro that specifies the build error message to be displayed when an error is encountered during the make procedure. For example,

• BUILD_ERROR = ['Error while building ', modelName]

• The following DOWNLOAD options apply only to the Tornado target:
  • DOWNLOAD -- An optional macro that you can specify as yes or no. If specified as yes (and BUILD=yes), then make is invoked a second time with the download target.

  • make -f model.mk download

  • DOWNLOAD_SUCCESS -- An optional macro that you can use to specify the download success string to be used when looking for a successful download. For example,

  • DOWNLOAD_SUCCESS = ### Downloaded

  • DOWNLOAD_ERROR -- An optional macro that you can use to specify the download error message to be displayed when an error is encountered during the download. For example,

  • DOWNLOAD_ERROR = ['Error while downloading ', modelName]

• The third section defines the tokens make_rtw expands (see Table 14-3).
• The fourth section contains the make rules used in building an executable from the generated source code. The build rules are typically specific to your version of make.

Figure 14-6 shows the general structure of a template makefile.

Figure 14-6: Structure of aTemplate Makefile

Customizing and Creating Template Makefiles

To customize or create a new template makefile, we recommend that you copy an existing template makefile to your local working directory and modify it.

This section shows, through an example, how to use macros and file-pattern-matching expressions in a template makefile to generate commands in the model.mk file.

The make utility processes the model.mk makefile and generates a set of commands based upon dependency rules defined in model.mk. After make generates the set of commands needed to build or rebuild test, make executes them.

For example, to build a program called test, make must link the object files. However, if the object files don't exist or are out of date, make must compile the C code. Thus there is a dependency between source and object files.

Each version of make differs slightly in its features and how rules are defined. For example, consider a program called test that gets created from two sources, file1.c and file2.c. Using most versions of make, the dependency rules would be

• test: file1.o file2.o
          cc -o test file1.o file2.o
  
  file1.o: file1.c
          cc -c file1.c
  
  file2.o: file2.c
          cc -c file2.c
  

In this example, we assumed a UNIX environment. In a PC environment the file extensions and compile and link commands will be different.

In processing the first rule

• test: file1.o file2.o 
  

make sees that to build test, it needs to build file1.o and file2.o. To build file1.o, make processes the rule

• file1.o: file1.c
  

If file1.o doesn't exist, or if file1.o is older than file1.c, make compiles file1.c.

The format of Real-Time Workshop template makefiles follows the above example. Our template makefiles use additional features of make such as macros and file-pattern-matching expressions. In most versions of make, a macro is defined via

• MACRO_NAME = value
  

References to macros are made via $(MACRO_NAME). When make sees this form of expression, it substitutes value for $(MACRO_NAME).

You can use pattern matching expressions to make the dependency rules more general. For example, using GNU Make you could replace the two "file1.o: file1.c" and "file2.o: file2.c" rules with the single rule

• %.o : %.c
          cc -c $<
  

Note that $< above is a special macro that equates to the dependency file (i.e., file1.c or file2.c). Thus, using macros and the "%" pattern matching character, the above example can be reduced to

• SRCS = file1.c file2.c
  OBJS = $(SRCS:.c=.o)
  
  test: $(OBJS)
          cc -o $@ $(OBJS)
  
  %.o : %.c
          cc -c $<
  

Note that the $@ macro above is another special macro that equates to the name of the current dependency target, in this case test.

This example generates the list of objects (OBJS) from the list of sources (SRCS) by using the string substitution feature for macro expansion. It replaces the source file extension (.c) with the object file extension (.o). This example also generalized the build rule for the program, test, to use the special "$@" macro.

Customizing the Makefile Include Path

Real-Time Workshop template makefiles provide rules and macros that let you add source directories, include directories, and libraries to generated makefiles without having to modify the template makefiles themselves. This feature is useful if you need to include your code when building S-functions.

To include a directory needed for a S-Function, you must create an M-function, rtwmakecfg, in a file rtwmakecfg.m. This file must reside in the same directory as your S-function component (.dll on Windows, .mex on UNIX). The rtwmakecfg function is called during the build process. The rtwmakecfg function must return a structured array with following elements:

• makeInfo.includePath: a cell array containing additional include directory names, which must be organized as row vector. These directory names will be expanded into include instructions in the generated makefile.
• makeInfo.sourcePath: a cell array containing additional source directory names, which must be organized as a row vector. These directory names will be expanded into make rules in the generated makefile.
• makeInfo.library: a structure containing additional runtime library names and module objects, which must be organized as a row vector. This information will be expanded into make rules in the generated makefile.
• makeInfo.library(n).Name: String. Specifies the name of the library (without extension).
• makeInfo.library(n).Location: String. Directory in which the library is located.
• makeInfo.library(n).Modules: Cell array. Specifies the C files in the library.

Adding a Custom Target to the System Target File Browser

Creating Device Drivers