From RTSC-Pedia

[printable version]  [offline version]

offline version generated on 04-Aug-2010 21:08 UTC

Sharing a Configuration via make

Using make to build multiple applications that share a configuration

Introduction

There are situations where is it desirable to create a single configuration of RTSC modules that can be shared among multiple applications. Suppose, for example, that you have a unit test suite for a particular module and the module has no configuration parameters. More than likely, each test will build with the same configuration. Rather than re-running the configuration step for each program, it is possible to run the configuration step just once and use the results to build all the tests.

Separating the configuration step also has the advantage of minimizing the impact of the configuration process within an existing build framework. The configuration step can be run once at some point within your existing build flow and the resulting output files can be easily referenced.

In the sections below, we describe one way to structure GNU makefiles to enable multiple applications to use a single configuration. The makefiles shown assume you are using a GCC toolchain but are easily modified to support virtually any collection of C language tools; see Consuming Configurable Content/makefiles for examples using other popular tools chains.

In this example, we create separate directories for the application source code and the configuration. The configuration directory contains just the configuration script and a makefile whereas the application directory contains the application sources and a makefile. Although your application's physical design or build system may require a different structure, the core principles shown below should apply.

Configuration directory

The configuration directory contains just two files: the application configuration script, basic.cfg, and the makefile shown below. The purpose of this directory is to run the configuration step and manage the output of this process.

CGTOOLS = $(TOOLS)/gcc/3.2.1/Linux
XDCTARGET = gnu.targets.Linux86
CONFIG = basic
 
all: $(CONFIG)/compiler.opt $(CONFIG)/linker.cmd
 
$(CONFIG)/linker.cmd $(CONFIG)/compiler.opt : $(CONFIG)
 
$(CONFIG) : $(CONFIG).cfg
        xs xdc.tools.configuro -c $(CGTOOLS) -t $(XDCTARGET) $<
 
clean:
        rm -rf $(CONFIG)

Line 1 tells make that it must create just two files: basic/compiler.opt and basic/linker.cmd. Line 2 indicates that these files depend on the basic sub-directory which will contain all files generated by configuro.

Line 3 tells make how to create the basic sub-directory from the basic.cfg configuration file. The configuro tool generates many more files than just basic/compiler.opt and basic/linker.cmd but all the files are placed in the sub-directory created to hold compiler.opt and linker.cmd. This makes the clean command 4 particularly simple.

For completeness we show the configuration script used by the application below but your configuration scripts will (obviously) be more complex. Regardless of the complexity of your configuration script, however, the integration process and the makefiles shown do not change.

xdc.useModule('xdc.runtime.System');

Application directory

The application directory contains all sources and makefiles necessary to build the application. In this simple example, we have just one file, hello.c.

#include <xdc/runtime/System.h>
 
int main(int argc, char **argv)
{
    System_printf("hello world\n");
    return (0);
}

Since this file references a configurable module, xdc.runtime.System, it should be compiled with the options contained in the compiler.opts file generated as part of the configuration step. Recall that the output of the configuration step includes two files that make integration with existing make based build system quite straightforward.

1. linker.cmd - the list of libraries required to use the modules configured (in the order required to ensure proper linkage)
2. compiler.opt - the compiler options required for sources to reference the modules configured and match the runtime options of the libraries named in linker.cmd (big or little endian, packed enums, ...)

The compiler.opts file contains the options necessary to ensure that the xdc/runtime/System.h header included at 1 corresponds to the xdc.runtime.System module configured above. The linker.cmd file ensures that the System_printf reference at 2 is satisfied by a library that corresponds to the same xdc.runtime.System module.

The makefile below illustrates one way to leverage these files. The first line defines a macro that names the directory containing the files generated by configuro. The remaining lines should look familiar; they are minor variants of rules commonly used to build applications. These subtle variations are important to understand, however.

CONFIG = ../cfg/basic
 
CC = $(TOOLS)/gcc/3.2.1/Linux/bin/gcc
LNK = $(CC)
 
all: hello.exe
 
%.o : %.c $(CONFIG)/compiler.opt
        $(CC) $(shell cat $(CONFIG)/compiler.opt) -c $<
 
hello.exe: hello.o $(CONFIG)/linker.cmd
        $(LNK) -o $@ hello.o $(CONFIG)/linker.cmd -lstdc++
 
clean:
        rm -f hello.exe hello.o

Line 2 defines how C sources files should be compiled and ensures that if the options in compile.opt change, your sources will be properly re-built. Similarly, line 3 ensures that your program is re-linked whenever the contents of linker.cmd change. Again, this is important because changes to the configuration script often result in different libraries that your program needs to link with.

Triggering the configuration step

In the application directory example above, we assumed that the configuration step has already been run and, in situations where a "top-level build" is coordinating the build of a system, this is a reasonable assumption. However, if you want to be able to change the configuration script and rebuild entirely from within the application directory, we need to augment the application's makefile to trigger a re-build of the configuration.

The makefile fragment below illustrates how to automatically trigger a rebuild of a configuration when a configuration script changes.

clean:
        rm -f hello.exe hello.o
        @$(MAKE) --no-print-directory -C $(dir $(CONFIG)) $@
 
$(CONFIG)/compiler.opt $(CONFIG)/linker.cmd: $(CONFIG)
 
$(CONFIG): $(CONFIG).cfg
        @$(MAKE) -C $(dir $@)
 

On line 1 we extend the rule to clean to also clean the configuration directory. On lines 2 and 3 we tell make when and how to re-build the files generated by the configuration step; in this case, we simply invoke make in the configuration directory whenever the configuration file is newer than the generated files.

See also

In addition to the GNU Make online manual and tips from Paul Smith, the maintainer of GNU make, the following related RTSC-pedia documents be useful.

[printable version]  [offline version]

offline version generated on 04-Aug-2010 21:08 UTC