Build Integration

This article describes how to add tests 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 Build Tools 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.). Some examples are shown in Sample Stride Target Settings

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)/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)/SDK/Linux/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 (additional samples are here. At a minimum, be sure that:
   • compatibility option is specified correctly, and
   • the CPU endian-ness is specified correctly

   The STRIDE Diagnostics will detect other incorrect settings.

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 STRIDE Diagnostics

To execute the diagnostic tests, use a Windows or Linux host computer that has connectivity with the target system via your configured STRIDE transport (TCP/IP or serial). Additionally, make the generated STRIDE database (.sidb) visible to the host computer via a shared filesystem or a file copy to the host system.

If not already present, install the appropriate Host Tools package on the host computer.

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

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

Specify your database and device options as required.

Interpreting Diagnostic Results

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

Loading database...
Connecting to device...
  runtime version: 4.1.02 
Diagnosing target application...
  Link
    Loopback ....................................................................................................
    Payload Fragmentation
    Stub-Proxy Deadlock
    Target Characteristics
    > 4 passed, 0 failed, 0 in progress, 0 not in use.
  Stat
    > 2 passed, 0 failed, 0 in progress, 0 not in use.
  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...

Once the test run is complete, you will see the files stride.xml (result name defaults to same as database name) and, if you were connected to the Internet when you ran the tests, stride.xsl in the directory from which you ran stride.

By opening stride.xml in a web browser, the xsl is automatically applied to create html in the browser.

All tests should pass.

Uploading Diagnostic Results

Optionally, if you have Internet connectivity and access to your company's Test Space you could run again the diagnostics and upload the results by executing:

stride --diagnostics --database=<path>/stride.sidb --device=<device_address> -u --testspace=https://<user>:<pwd>@<mycompany>.stridetestspace.com --project="Stride Deployment" --space=Diagnostics --run=*