Project

General

Profile

RFIES Variants - Detailed

SETTING UP AND USING VARIANTS WITH RFIES TOOLS

Roger Tokarek
June 7, 2015

 

WHY THIS GUIDE

Document my steps to creating and deploying project variants as defined by the RFIES tools.

This example describes the steps required to let variants:
  1. do the work of creating their own boot directories,
  2. transfer the appropriate startup scripts to each variant boot directory,
  3. properly transfer compiled code to each variant boot directory, and
  4. use conditional compilation to compile only variant specific code.

 


STARTING NOTES

My project area is vmeint. I want it to support possibly slightly different compilation for three front ends named nbeam, pxint and anub. These names will also become the names of my variants.

There are two descriptions of variants that are used. The Target variant eg, MVME5500-pxint_64, is a fully qualified term that uniquely defines the selected target from the Targets file. The variant name is pxint.

In order to take full advantage of the power of variants, the variant name (pxint) should be identical to the name of the boot directory, fecode-bd/vxworks_boot/fe/pxint.

variant name must equal fe boot directory name ideally equals front end name

If the variant name is not specified then the variant is the same as the project.
 

STEP 1 - CREATE VARIANTS

Edit the Targets file and add Target variants. "MVME5500_64 /usr/local/vxworks/scripts/wind6.4_mv5500.bash" is copied and modified to
"MVME5500-pxint_64 /usr/local/vxworks/scripts/wind6.4_mv5500.bash" for example.

  • A Target variant name is made of 3 parts: the module type (MVME5500), a variant name (pxint), and an optional trailing identifier (_64).
  • The hyphen separating module type and variant name is required.
  • The variant name is arbitrary but to take full advantage of the power of variants it should match the name of its fe boot directory.
  • The trailing identifier, _64, is only required if you wish to "individualize" the versions. For example MVME5500-pxint_64 and MVME5500-pxint_pizza are both acceptable targets.
  • The Targets file is not tolerant of empty lines either within the block of text or trailing the text.

MVME5500_64 /usr/local/vxworks/scripts/wind6.4_mv5500.bash

I added variants named nbeam, pxint, and anub to the Targets file displayed below and disabled the target MVME5500_64.
Disabling MVME5500_64 was for my convenience, it is not required in my application.
However, If not disabled, compilation against MVME5500_64 will direct the output toward the
fe boot area sharing same project directory name, in this case vmeint. All other
compilation will be directed towards the variant boot directories. After finishing the editing I have:

~/esd/src/vmeint> cat Targets
# Id: $Id: Targets,v 1.4 2014/09/02 19:33:07 tokarek Exp $
#
# format TARGET[-variant][_buildVariant] (in that order)
# e.g., MVME5500-rrbpm_61
# The first target listed will become the 'default'
#
# MVME5500_64 /usr/local/vxworks/scripts/wind6.4_mv5500.bash
MVME5500-nbeam_64 /usr/local/vxworks/scripts/wind6.4_mv5500.bash
MVME5500-pxint_64 /usr/local/vxworks/scripts/wind6.4_mv5500.bash
MVME5500-anub_64 /usr/local/vxworks/scripts/wind6.4_mv5500.bash

 

STEP 2 - SET A VARIANT AS CURRENT

To make sure the desired target variant is current. The easiest way to do this is to type targs or targets, and copy and paste your desired selection, eg, target MVME5500-pxint_64 into the command line. (Alternate.)

~/esd/src/vmeint>  targs
target MVME5500-nbeam_64
target MVME5500-pxint_64
target MVME5500-anub_64

~/esd/src/vmeint> target MVME5500-pxint_64
t> Using target MVME5500-pxint_64 (remains unchanged) ...
t> Running /usr/local/vxworks/scripts/wind6.4_mv5500.bash for target MVME5500-pxint_64 ...

 

STEP 3 - CREATE THE VARIANT BOOT DIRECTORY (One Time Step)

If the boot directory does not already exist, there are two ways to create the fecode-bd/vxworks_boot/fe/"variant name" boot directory, eg. fecode-bd/vxworks_boot/fe/pxint.

  1. cd fecode-bd/vxworks_boot/fe, mkdir pxint, (set permissions, chmod...)
  2. OR, let make do the work.

Good idea to first confirm your current variant: 4 ways to do this

~/esd/src/vmeint> echo $VARIANT
pxint
/esd/src/vmeint> variant
pxint
/esd/src/vmeint> showv
pxint
~/esd/src/vmeint> dumpesd
(...last lines of dump)
Project Setup:
PROJECT = vmeint
USER_PROJECT_DIR = /export/home/tokarek/esd/src/vmeint
TARGET = MVME5500-pxint_64
VARIANT = pxint
REFERENCES = production
VXWORKS_CPU = PPC604
VXWORKS_VERSION = 64
VxWorks headers = /usr/local/vxworks/ppc_3.4/vxworks-6.4/target/h/

Typing make downloaddirectory will create a boot directory for you with the current variant name, pxint, in this case. If the directory already exists the command "does no harm", that is it does not override the current directory, however the messaging will remain as below.

Type helpme for a list of all the RFIES commands and make help for a list of all the make commands.

(Alternative.)

~/esd/src/vmeint> make downloaddirectory
t> NOTE: OLD_VXWORKS_ENV is unset
t> Running /usr/local/vxworks/scripts/wind6.4_mv5500.bash for target MVME5500-pxint_64 ...
t> Running make downloaddirectory for PROJECT=vmeint REFERENCES=PRODUCTION RELEASE=SANDBOX TARGET=MVME5500 VARIANT=pxint ...
m> Creating download directory /fecode-bd/vxworks_boot/fe/pxint ...
m> Project vmeint download directory created for target MVME5500.
t> Make downloaddirectory completed for PROJECT=vmeint REFERENCES=PRODUCTION RELEASE=SANDBOX TARGET=MVME5500 VARIANT=pxint

This creates the boot directory fecode-bd/vxworks_boot/fe/pxint.

 

STEP 4 - TRANSFER THE STARTUP SCRIPT (Optional)

Assuming you want to edit your startup scripts in the project area, there are three ways to transfer your scripts to the fe variant boot directory.

  1. cp or mv script from project area to boot directory,
  2. (alternate) pushv (or pushp) script, or
  3. let make installscript do the work.

Using "make installscript"

Assumes you are developing your startup scripts in your project area and your Makefile is capable of discovering them: my Makefile uses the following to identify my startup scripts by variant name: (in Makefile)

# specify all startup script files to be installed in front-end download directory
SCRIPTS = $(VARIANT)startup

My startup script names are nbeamstartup, pxintstartup and anubstartup.

Again, it may be good to confirm you are still in the variants area you want to be,

~/esd/src/vmeint> variant
pxint

make installscript will transfer your script to the boot directory named after the current variant, fecode-bd/vxworks_boot/fe/pxint. (Type make help to be reminded of the make options.)

~/esd/src/vmeint> make installscript
t> NOTE: OLD_VXWORKS_ENV is unset
t> Running /usr/local/vxworks/scripts/wind6.4_mv5500.bash for target MVME5500-pxint_64 ...
t> Running make installscript for PROJECT=vmeint REFERENCES=PRODUCTION RELEASE=SANDBOX TARGET=MVME5500 VARIANT=pxint ...
m> Installing /fecode-bd/vxworks_boot/fe/pxint/pxintstartup ...
m> Done!
t> Make installscript completed for PROJECT=vmeint REFERENCES=PRODUCTION RELEASE=SANDBOX TARGET=MVME5500 VARIANT=pxint

 

STEP 5 - COMPILE AND TRANSFER TO VARIANT BOOT DIRECTORIES

There are three ways to accomplish this,

  1. Use make without options then transfer the compiled code to the boot directory,
  2. or use make development (or make test or make production) which does a (A) single variant build and transfer,
  3. or (B) build and transfer all targets in the Targets file with a single command, builddevelopment, or buildtest, or buildproduction (one word, no "make").

 

(A) Single Variant Build and Transfer:

Remember to confirm your desired variant is current, either by checking with the variant command or by setting your variant using Targets with cut-and-paste. (Alternate) Note change here to variant anub.

~/esd/src/vmeint> targs
target MVME5500-nbeam_64
target MVME5500-pxint_64
target MVME5500-anub_64
~/esd/src/vmeint> target MVME5500-anub_64
t> Changing target to MVME5500-anub_64 ...
t> Running /usr/local/vxworks/scripts/wind6.4_mv5500.bash for target MVME5500-anub_64 ...
~/esd/src/vmeint> make development

Will compile and transfer the executable to /fecode-bd/vxworks_boot/fe/anub.

Repeat this process, set the desired target variant to be current then make development or make ....

 

(B) Build and Transfer All Variants:

If you wish to compile and deploy the executable to all variant boot directories (as listed in the Targets file) with a single command,

~/esd/src/vmeint> builddevelopment

"builddevelopment", "buildtest", and "buildproduction" are all single functions (no "make").

Each variant is compiled and transferred sequentially.

 

STEP 7 - CONDITIONAL COMPILATION WITH VARIANTS (Optional)

VMEInt& VMEInt::getInstance() {
  static VMEInt instance;
#if VARIANT == nbeam
  printf("IS NBEAM\n");
#elif VARIANT == pxint
  printf("IS PXINT\n");
#elif VARIANT == anub
  printf("IS ANUB\n");
#else
  printf("NOT A VARIANT!?\n");
#endif
return instance;
}

As a test I am asking the compiled version of the code to tell me which version I am using. So when I run the nbeamstartup script I should see "IS NBEAM" and "IS PXINT" when I run the pxintstartup script.

I accomplished this by modifying the line, "DEFINES = ", in my Makefile:

DEFINES = -Dnbeam=37890 -Dpxint=37891 -Danub=37892

I created my own numbers. They are arbitrary and unique. There should be no spaces between the -D, the variant name, the equals sign and the number. It is to be read as a single token.

With the conditional compilation statements in the getInstance() method above, I see:
  • "IS NBEAM" when I run the nbeam startup script,
  • "IS PXINT" when I run the pxint startup script, and
  • "IS ANUB" when I run the anub startup script.
    In this example each variant boot area had the same executable.

My Makefile also has a (currently unused) variants area, where the compilation could be uniquely customized for each variant:

# specify additional parameters which affect specific variants
# where xxx is eg, recycler or debug
VARIANT_xxx_C++SOURCES =
VARIANT_xxx_CSOURCES =
VARIANT_xxx_HEADERS =
VARIANT_xxx_SCRIPTS =
VARIANT_xxx_LIBRARIES =
VARIANT_xxx_INCLUDES =
VARIANT_xxx_DEFINES =
VARIANT_xxx_CFLAGS =
VARIANT_xxx_C++FLAGS = $(VARIANT_xxx_CFLAGS)

 

Some Helpful Commands

I have these currently defined in "setup-vmeint" in my vmeint directory.

push - transfer filename to project-named boot directory
pull - transfer a file from project-named boot directory
pushv - transfer a file to variant named boot directory
pullv - tranfer a file from variant named boot directory
showp - display current project name
showv - display current variant name
showt - display target name
variant - display variant name
dumpesd - display all project esd environment variables
helpme - list all commands
make help - list all make options

Examples:

push thisstartupscript

will transfer thisstartupscript from the project area to the boot directory name displayed in showp.

pushv thisstartupscript

will transfer thisstartupscript from the project area to the boot directory name displayed in showv.