Build Integration

This article describes how to add the STRIDE build toolchain to your target build. It assumes that your have completed the steps described in the article Runtime Integration.

Adding STRIDE Build Tools to Your Target Build

If you haven't already done so, download and install the appropriate package on your target build machine. The STRIDE Build Tools must be run as part of your build process to generate additional artifacts needed to build and run your tests.

Build Artifacts

The STRIDE Build Tools take one or more .h files as input, and produce

• A STRIDE database (.sidb) file that contains metadata describing the tests declared in the input header files
  • This file is used as an intermediate file in the build process, and is used by the host Stride Runner
• Generated .h and .c (or .cpp) source files
  • These files implement harnessing which allows the tests to be run remotely

Build Order

STRIDE Build Process Overview

The Build Tools-generated source code--referred to as an Intercept Module--is compiled and linked along with the rest of your target sources, therefore the Build Tools must be run (and the IM source compiled) before your target link takes place. Often the simplest approach is to add the STRIDE Build Tools so that they run as the first step in your build process.

Build Tool Inputs

The collection of .h files that comprise the input to the Build Tools (specifically, the s2scompile tool) will change as new test assets are created. It's important that the process of adding new test files to the target build is simple and straightforward. Therefore, a technique that supports this changing input is recommended.

The Makefile provided as part of the standard Platform SDKs uses such a technique: a directory is designated to contain all files to be input to the s2scompile tool.

Compiler Settings

The s2scompile tool requires settings that customize compiler settings for your target environment.

Complete information can be found in s2scompile, but the most important options are as follows:

--c / --c++

Controls the language semantics used to parse the input .h files and language semantics used in generated code.

--compatibility

Controls which language extensions are recognized in the input .h files

--targ_*

Sets datatype characteristics (size, alignment, etc.).

Build Tools Integration

The Makefile included with any standard Platform SDK can serve as an example of build tools make integration. Another stripped-down Makefile is shown below.

Note: If you copy and paste any content from this example into a makefile, be aware that you will probably need to replace leading spaces with tabs for any lines that specify rules (since make utilities typically require tab indentation for rules).

Example GNU Makefile

# Makefile for Stride Build
.PHONY: clean all _build _instrument
.PRECIOUS: Makefile

#  input to build tools will be all .h files in SCL_DIRS
SCL_DIRS = $(HOME)/stride/SCL_headers
SCL_SRCS_H = $(foreach dir, $(SCL_DIRS), $(wildcard $(dir)/*.h))

# Set this to the directory that contains the
# STRIDE 'Runtime' files
RUNTIME_PATH = $(HOME)/stride/SDK/Runtime

BUILD_ROOT = .

INT_PATH = $(BUILD_ROOT)/Meta
OUT_PATH = $(BUILD_ROOT)
IM_PATH  = $(BUILD_ROOT)/IM

S2SC = s2scompile
S2SB = s2sbind
S2SI = s2sinstrument

INC_PATHS = \
    -I "$(RUNTIME_PATH)" \
    --sys_include "/usr/include" \

DEFINES = 

CFLAGS = $(INC_PATHS) $(DEFINES) --c

COMPILER_OPTIONS_FILE = $(HOME)/stride/SDK/Posix/settings/stride.s2compile

METAS = $(foreach src, $(SCL_SRCS_H:.h=.h.meta), $(INT_PATH)/$(notdir $(src)))

SIDB = stride.sidb

vpath %.h $(foreach dir, $(SCL_DIRS), $(dir))

all: _build _instrument

clean:
    $(RM) $(METAS) $(OUT_PATH)/$(SIDB) $(IM_PATH)/stride*

_build: $(OUT_PATH)/$(SIDB)

#rule to run s2sbind
$(OUT_PATH)/$(SIDB): $(METAS)
    @if [ ! -e $(OUT_PATH) ] ; then mkdir $(OUT_PATH) ; fi
    $(S2SB) --output=$@ $(METAS)

# rule to run s2scompile
$(INT_PATH)/%.meta: %
    @if [ ! -e $(INT_PATH) ] ; then mkdir $(INT_PATH) ; fi
    $(S2SC) --options_file="$(COMPILER_OPTIONS_FILE)" $(CFLAGS) --output="$@" "$<"

# rule to run s2sinstrument
_instrument:
    @if [ ! -e $(IM_PATH) ] ; then mkdir $(IM_PATH) ; fi
    $(S2SI) --im_name=stride --code_output="$(IM_PATH)" --header_output="$(IM_PATH)" "$(OUT_PATH)/$(SIDB)"

The sample here shows only the STRIDE Build Tools phase of a complete target build. In addition to what's shown here, you need to also:

• Include the generated Intercept Module (IM) source file strideIM.c(cpp) in your target compile and link
• Include any source files that implement test units in your target compile and link.

Launching the IM Thread in the Target Application

The STRIDE IM thread must be started in your target application code. This is the thread upon which tests are run.

To achieve that in addition to the target code changes done durring STRIDE Runtime integration you need to do the following:

• Include the generated strideIMEntry.h file.

...

/* STRIDE IM includes */
#include <strideIMEntry.h>
 
int main(int argc, char **argv)
{
  ...

• Start the STRIDE IM thread.

Please refer to the standard pre-packaged Platform SDKs for examples of a startup sequence. Briefly it should be something like:

...

/* STRIDE IM includes */
#include <strideIMEntry.h>
 
int main(int argc, char **argv)
{
  ...

  /* start any IM thread */
  if (strideCreateIMThread(stride) != srTRUE)
    return -1;

  ... 

  /* stop all STRIDE threads and uninitialize STRIDE subsystem */
  ... 

  return 0;   
}

If you implement a custom PAL then here is an example of the startup code:

...

/* STRIDE IM includes */
#include <strideIMEntry.h>
 
int main(int argc, char **argv)
{
  ...

  /* start any IM thread */
  palDWORD dwNID = /* create thread with function strideIMStubThread() */;
  if (dwNID == 0)
    return -1;

  ... 

  /* stop all IM threads */
  palNotify(dwNID, palSTOP_EVENT);

  /* uninitialize STRIDE subsystem */
  ...

  return 0;   
}

Building the Target with STRIDE Diagnostics

For a first-time instrumented target build, we recommend including the built-in diagnostic tests. These tests are implemented in the files srdiag.h and srdiag.c included in the distribution Runtime directory. These tests provide a simple starting point, and will provide diagnostic information if the build isn't right.

1. Include the STRIDE Runtime in your build as described in Runtime Integration.
2. Review the compiler target settings (typically in the file stride.s2compile) for correctness. At a minimum, be sure that:
   • compatibility option is specified correctly, and
   • the CPU endian-ness is specified correctly
3. Make appropriate changes to your target build process so that the STRIDE build tools run as described.
4. Modify your target source so that the STRIDE IM thread is started (and is shutdown when your program terminates).
5. Provide srdiag.h as an input to the STRIDE build tools. (If using the example Makefile above, you would add the file to the SCL_SRCS_H list.)
6. Make appropriate changes to your target build process so that additional source files are included:
   • strideIM.c(cpp) - generated IM code

Running Diagnostics

Start the target app running on the target hardware, then run stride as follows:

stride --diagnostics --database=<path>/stride.sidb --device=<device_address> --run="*" --output=diagnostics

Specify your database and device options as required.

Upon running, the host console running stride will display summary test results on the console:

Loading database...
Connecting to device...
  runtime version: 5.x.yy 
Executing diagnostics...
  test unit "Link"
    Loopback ............
    Payload Fragmentation
    Stub-Proxy Deadlock
    Target Characteristics
    > 4 passed, 0 failed, 0 in progress, 0 not in use.
  test unit "Stat"
    > 2 passed, 0 failed, 0 in progress, 0 not in use.
  test unit "Time"
    > 2 passed, 0 failed, 0 in progress, 0 not in use.
  --------------------------------------------------------------------- 
  Summary: 8 passed, 0 failed, 0 in progress, 0 not in use.

Disconnecting from device...
Saving result file...

Also a report diagnostics.xml is generated (this file is specified via the --output command line option). In addition a diagnostics.html is generated that could be open in a web browser of your choice.