The most common customization to the TargetRTS is porting it to a new platform. A platform is defined by the TargetRTS as the combination of the operating system, target hardware and the compiler/linker tool chain. A new operating system requires the most work since it often requires implementation changes. However, a new compiler may also require changes, in particular, to the configuration files.
The ports supported by ObjecTime Ltd. and shipped with the TargetRTS source are a good place to begin considering design alternatives for a new port. The root directory for the TargetRTS source will be referred to from this point forward using the environment variable RTS_HOME. It is usually a subdirectory of $OBJECTIME_HOME ($OBJECTIME_HOME/C++/TargetRTS or $OBJECTIME_HOME/C/TargetRTS). In the sections that follow, examples are extracted from this source.
The major steps for implementing the port are as follows:
The first step in implementing a port is picking the name for the platform. This name and parts of it are used by the various loadbuild tools to find the files needed to build the TargetRTS for that platform. It is also used during compilation of the ObjecTime models. There are two parts to the name: target and libset. The resulting names for TargetRTS configurations are defined as combinations of the target and libset names in the following pattern:
<platform> ::= <target>.<libset>
Examples are given in Table 3
Name | Description |
|---|---|
The target name presents the implementation-specific components of the TargetRTS. These components are generally specific to a given configuration, of a given version, of a given operating system. The target name is also used to name the configuration of the target, for example, single versus multi-threaded. The target name is defined as follows:
<target> ::= <OS name><OS version><RTS config>
For example: SUN5T. The components of <target> are defined as follows:
SUN)
5 meaning SunOS 5.x, that is, Solaris 2.x). Do not use periods in the OS version as this will confuse the make utility when trying to build the TargetRTS.
T)
Although the actual libset names can be chosen arbitrarily, by convention those defined by ObjecTime are defined as follows:
<libset> ::= <processor>-<compiler name>-<compiler version>
For example: sparc-gnu-2.7.1. The components of <libset> are defined as follows:
The setup script is a file (setup.pl) containing Perl commands that set up the environment for the compilation of the TargetRTS to the platform. This file is contained in the $(RTS_HOME)/config/<target>.<libset> directory. If the target tool chain environment variables are part of a user's standard environment, then the variables in the setup.pl file may not be necessary. These environment variables defined in the setup.pl file are not available when using the toolset to build user models.
The commands in the setup.pl file are executed before any of the compilation tools are invoked. Typically, definitions for locations of files on the host platform are included in this file. This usually includes setting the shell environment variable PATH to point to the appropriate tools. Two variables must be defined for all targets, namely the preprocessor variable and the supported variable. The preprocessor variable defines the C++ preprocessor command appropriate for the compilation environment. The preprocessor command is used to automatically generate source code dependencies for the TargetRTS. The supported variable defines whether this target is supported by ObjecTime Limited. Valid values for supported are `Yes' and `No'. Another variable to note is target_base. This variable indicates that the implementation of the target-specific features of the TargetRTS are rooted in the same source directory as the target_base target. For example, for the VRTX4T target, the target_base is set to `VRTX3'. Therefore, VRTX4 specific implementations of TargetRTS classes are found in the same source directory as those of the VRTX3 target, that is, $(RTS_HOME)/src/target/VRTX3.
The example file, $(RTS_HOME)/config/VRTX4T.ppc603-Microtec-1.4/setup.pl, includes
$os = $ENV{'OS'};$os = 'default' unless defined( $os );if( $os eq 'Windows_NT' ){ $usr_mri = $ENV{'USR_MRI'}; $ENV{'PATH'} = "$usr_mri/bin;$ENV{'PATH'}";}else{ $usr_mri = "$ENV{'OS_HOME'}/spectra/solaris-ppc603-4.AB"; $ENV{'USR_MRI'} = "$usr_mri"; $ENV{'SPECTRA'} = "$usr_mri/spappc"; $ENV{'MRI_PPC_BIN'} = "$usr_mri/bin"; $ENV{'MRI_PPC_LIB'} = "$usr_mri/lib"; $ENV{'MRI_PPC_INC'} = "$usr_mri/include/mccppc"; $ENV{'PATH'} = "$usr_mri/bin:$ENV{'PATH'}";}$preprocessor = "cccppc -E >MANIFEST.i";$include_opt = '-J';$target_base = 'VRTX3';$supported = 'Yes';Note: The setup file is not used when compiling generated updates. The environment variables defined in the setup file must instead be defined in the user's environment before executing the ObjecTime toolset. In the given example, the setup file assumes that the user's environment has the variables USR_MRI and OS_HOME already defined. This is platform-specific.
Two types of builds are supported by the makefiles for the TargetRTS: compilation of the TargetRTS libraries and compilation of the generated code. The platform-specific definitions are required by both and are thus placed in separate files. The sequencing of the makefiles for the two paths are shown in Figure 2, "Sequencing of Makefiles," on page 35.
As shown, there is a makefile for each of the following:
$RTS_HOME/target/common.mk is the main definition for compiling an update. This makefile cannot be customized and is not discussed further in this document.
$RTS_HOME/src/Makefile is the root makefile for the TargetRTS libraries that selects the host to compile the libraries. See "TargetRTS makefiles" on page 36.
$RTS_HOME/src/main.mk is the main definition for compiling the TargetRTS libraries. This makefile cannot be customized and is not discussed further in this document.
$RTS_HOME/libset/default.mk, the default macro definitions that may be overridden by the platform specific makefiles. See "Default makefile" on page 36.
$RTS_HOME/libset/<libset>/libset.mk is the definition specific to the compiler. See "Libset makefile" on page 39.
$RTS_HOME/target/<target>/target.mk is the definition specific to the target operating system and TargetRTS configuration. See "Target makefile" on page 38.
$RTS_HOME/config/<target>.<libset>/config.mk is the definition specific to the combination of the operating system, TargetRTS configuration, and compiler. See "Config makefile" on page 39.
Note:
The target, libset, and config makefiles are used to compile both the update and TargetRTS libraries.
Compilation of the update is usually performed by compiling an Actor in the ObjecTime Toolset; however, an update can also be compiled from the $UPDATE_DIR by issuing the make command.
Compilation of the TargetRTS is performed from the $RTS_HOME/src directory by issuing the command:
make <target>.<libset>make SUN5T.sparc-gnu-2.8.1
The $RTS_HOME/src/Makefile contains a default target that invokes a Perl script called Build.pl. This script checks the dependencies for the TargetRTS source code and generates a makefile called depend.mk in the $(RTS_HOME)/build-<target>.<libset> directory. It then builds the TargetRTS from this directory.
The target, libset, and config makefiles are expected to override defaults defined in $RTS_HOME/libset/default.mk. The defaults are as follows:
CONFIG = $(TARGET).$(LIBRARY_SET)# Defaults for macros which may be modified by# libset/$(LIBRARY_SET)/libset.mk# target/$(TARGET)/target.mk# or config/$(CONFIG)/config.mkFEEDBACK = $(PERL) "$(RTS_HOME)/tools/feedback.pl"NOP = $(PERL) "$(RTS_HOME)/tools/nop.pl"PERL = perlPRELINK = ld -r -oRM = $(PERL) "$(RTS_HOME)/tools/rm.pl"RMF = $(RM) -fTOUCH = $(PERL) "$(RTS_HOME)/tools/touch.pl"# default pre-compile command, can be modified by libset.mkPRECC = $(NOP)# Macros used when creating an object file from a C++ source fileCC = $(FEEDBACK) -fail \ CC should be defined by libset.mk or generated makefileDEBUG_TAG = -gDEFINE_TAG = -DINCLUDE_TAG = -ILIBSETCCEXTRA =LIBSETCCFLAGS =OBJECT_OPT = -cOBJOUT_OPT = -oOBJOUT_TAG =SHLIBCCFLAGS = -PICSOURCE_TAG =TARGETCCFLAGS =# Macros used when creating an object library from a set of object filesAR_CMD = $(PERL) "$(RTS_HOME)/tools/ar.pl"LIBOUT_OPT =LIBOUT_TAG =RANLIB = $(NOP)# Macros used when creating an shared library from a set of object filesSHLIB_CMD = $(FEEDBACK) -fail Shared libraries not supported.SHLIBOUT_OPT = -oSHLIBOUT_TAG =# Macros used when creating an executable from a set of object files, librariesLD = $(CC)DIR_TAG = -LLIBSETLDFLAGS =LIB_TAG = -lOT_LIB_TAG = -lTARGETLDFLAGS =TARGETLIBS =EXEOUT_OPT = -oEXEOUT_TAG =# Macros used to construct names of various kinds of filesEXEC_EXT =LIB_PFX = libLIB_EXT = .aCPP_EXT = .ccOBJ_EXT = .oSHLIB_PFX = libSHLIB_EXT = .so#RTS_LIBRARY = $(RTS_HOME)/lib/$(CONFIG)EXTERNAL_LIBS = $(DIR_TAG)"$(RTS_LIBRARY)" \ $(OT_LIB_TAG)ObjecTimeTransport \ $(OT_LIB_TAG)ObjecTimeTypesSYSTEM_LIBS = $(DIR_TAG)"$(RTS_LIBRARY)" \ $(OT_LIB_TAG)ObjecTime \ $(OT_LIB_TAG)ObjecTimeTransport \ $(OT_LIB_TAG)ObjecTimeTypesSYSTEM_DIRECTORY = $(LOCAL_DIRECTORY)/$(UPDATE)/C++/systemSYSTEM_DEPENDENCY = $(SYSTEM_DIRECTORY)/RTSystem.h \ $(SYSTEM_DIRECTORY)/initData.hALL_ACTORS_LIST = $(ALL_ACTORS)
The $RTS_HOME/target/<target>/target.mk makefile provides definitions specific to the operating system and TargetRTS configuration. The definitions in this makefile override the defaults in $(RTS_HOME)/target/common.mk. An example target makefile template file, RTS_HOME/target/SUN5T/target.mk, is as follows:
# Define the _REENTRANT macro to enforce thread safetyTARGETCCFLAGS = $(DEFINE_TAG)_REENTRANT# Add in the nsl and socket libraries and to pass on the RTS# library directory to the run-time linkerTARGETLDFLAGS = $(LIB_TAG)nsl $(LIB_TAG)socket -R$(RTS_LIBRARY)# Add in the posix4 and thread librariesTARGETLIBS = $(LIB_TAG)posix4 $(LIB_TAG)thread
The $RTS_HOME/libset/<libset>/libset.mk makefile provides definitions specific to the compiler. The definitions in this makefile override the defaults in $(RTS_HOME)/target/default.mk. An example libset makefile template file, $RTS_HOME/libset/sparc-gnu-2.7.1/libset.mk, is as follows:
# C++ compiler name and common argumentsCC = g++ -V2.7.1# Command to make shared librariesSHLIB_CMD = $(CC) -shared -z text -o # Use pragmas to specify interface and implementationLIBSETCCFLAGS = -DPRAGMA# More c++ flags to turn on optimization, specify processor version# and tune warningsLIBSETCCEXTRA = -O4 -finline -finline-functions \ -mv8 -Wall -Winline -Wwrite-strings# C compiler flags for building shared librariesSHLIBCCFLAGS = -fPIC# If SHLIBS is set to nothing,shared libraries will not be builtSHLIBS =
The $RTS_HOME/config/<target>.<libset>/config.mk makefile provides definitions specific to the combination of the operating system, TargetRTS configuration, and the compiler. This makefile is empty for most target/libset combinations. Usually this file will only be needed to work around problems that may not appear in either the target or libset alone. In the C++ TargetRTS, an example use of this file is as follows:
$RTS_HOME/config/VRTX4T.ppc603-Microtec-1.3C/config.mk:
EXEC_EXT = .xTARGETLIBS = $(USR_MRI)/lib/cppcb.libTable 4 defines which make macros can be redefined and where they are set.