What is Aspen?

Aspen is a command line tool that checks Understand CodeChecks against their test files. It will automatically create .und projects for each CodeCheck it finds and then validate the results. Aspen can be used to help your team achieve DO-178C ( Previously DO-178B ) certification. We have a guide for writing custom CodeChecks here. Or if you would like us to implement your standard, please reach out to support@scitools.com.


How to use

Each CodeCheck that Aspen tests will need corresponding test files. Test files should be located in the same directory as the CodeCheck itself. Examples of Understand CodeChecks and their test files can be found in your Understand installation directory under conf->plugin->SciTools->CodeCheck. In simple terms, these test files have code samples that demonstrate both good and bad coding practices in regards to the rule they are created for. Both good and bad examples are marked using comments in the test file. Aspen ensures each CodeCheck triggers violations at the appropriate places.


  • Aspen is in Beta and currently does not ship with Understand. If you would like to use Aspen, please email support@scitools.com
  • After receiving Aspen, download a copy of aspen_config.txt ( Available below ) and place a copy of aspen_config.txt here:
  • Windows: %appdata%/SciTools/aspen_config.txt
  • Linux: ~/.config/SciTools/aspen_config.txt
  • Mac: /Library/Application Support/SciTools/aspen_config.txt
  • Settings can be changed in the aspen_config.txt, or passed in via the command line, which overrides that setting in the config file.
  • Run aspen. The results will be output as a csv file to the results_file setting path. The default is the current working directory and the name aspen_results.csv.


Example

Let's say that we want to use Aspen to validate the AUTOSAR standard. Here are the steps I used:

  1. Open Aspen's configuration file aspen_config.txt in an editor. If I don't have this file already, I can download an example from the bottom of this page. I'm going to leave most of the settings at their default values, but since I am only interested in AUTOSAR, I'm going to edit my search_directory to be a bit more specific.
    I build Understand from source, so my path is going to be a little different from yours. If you're on Windows, the default path for AUTOSAR would be: 
    C:\Program Files\SciTools\conf\plugin\SciTools\CodeCheck\Published Standards\AUTOSAR

  2. My results_file is currently just "aspen_results.csv". That means my Aspen results will be generated in the current working directory whenever I run Aspen. If I want these results to appear somewhere else, I could add a path before file name.

  3. Next, I'm going to update my preferred_prefix because I want the AUTOSAR Ids to be shown. Many checks have multiple Ids as they exist in multiple standards. For example, several checks exists in both the MISRA 2004 and MISRA 2012 standards. But since I'm focusing on AUTOSAR, I want the AUTOSAR Ids for my report.

    All AUTOSAR Ids start with either an 'A' or 'M'. So I can use something like this: "^A,^M". The problem is, all the MISRA standards have Ids that start with 'MISRA'. So I want to exclude Ids that start with 'MI'. That gives me this preferred_prefix: "^A,^M,!MI"

  4. Now we just run Aspen:
  5. After completion, I can see I have 5 AUTOSAR tests that are failing Aspen. A0-1-4, A20-8-6, A8-4-12, A9-3-1 and M8-5-2.
    Now, I know exactly which tests need to be review and which checks need to be updated.


Aspen Settings

Settings for Aspen are taken from a config file (example below) that should be called aspen_config.txt.  All settings in the aspen_config.txt ( listed below ), can be overwritten on the command line using a - followed by the name of the setting. Here are the various settings and what they control

  • search_directory - This is where Aspen will look for CodeChecks and test files. If you are using custom CodeChecks, those are typically installed in the same location as aspen_config.txt in the plugin->CodeCheck directory.
  • all_csv_columns - This determines if all columns are generated for the Aspen report. 0=off 1=on 
  • results_file - The full path of where Aspen should write the CSV report. If blank, no report is generated.
  • project_directory - The full path of where .und projects should be created, leave blank to use the users directory listed above
  • log_level - The level of logging, 0=minimal 1=normal 2=verbose 3=debug
  • interactive_mode - Launch Aspen in interactive mode 0=off 1=on
  • force_project - Force create new .und projects and parse them instead of using existing projects and parsing only changed files, 0=off 1=on
  • force_clean - Deletes all projects found at project_directory 0=off 1=on 
  • violation_keyword - Sets the comment used in test files to specify a violation; default is "UndCC_Violation"
  • valid_keyword - Sets the comment used in test files to specify a valid example; default is "UndCC_Valid"
  • falsepos_keyword - Sets the comment used in test files to specify a false positive; default is "UndCC_FalsePos"
  • falseneg_keyword - Sets the comment used in test files to specify a false negative; default is "UndCC_FalseNeg"
  • violation_keyword_case - Determine if the violation keywords above are case sensitive 0=off 1=on 
  • filter_checks - All CodeChecks have a 'checkID' method that returns that CodeCheck's unique identifier(s). This setting filters the identifiers you would like to be tested. These filters are regex separated by ,
    If you lead the regex with a !, it will turn it into an ignore. Default is no filter and all CodeChecks will be tested.
    Example 1: "CPP, !CPP_P, !CPP_A002" will get all CodeChecks that have an identifier that starts with 'CPP' except ones that lead with CPP_P and the specific chech CPP_A002
    Example 2: "^M, !0$" Any identifier that starts with M but doesn't end with 0
  • preferred_prefix - Many CodeChecks actually have multiple identifiers. This setting displays the identifier with the following prefix, if it doesn't contain one of the following, it will use the last.
    Example: "^A, MISRA" This will use checks identifier that start with A, if not available then MISRA.


Configuring Projects created by Aspen

Aspen generates projects using default settings. Sometimes, the defaults aren't correct for a specific CodeCheck. We can change the project settings used by Aspen for a given CodeCheck by creating a file called aspen_commands.txt in the same directory as the CodeCheck. This file is used by Aspen for running a set of und commands before testing that the CodeCheck passes validation. There should be one und command per line and there is no need to include the word, 'und' in the commands themselves. So if we wanted to tell Aspen to use the fuzzy parser, we would have a single line like this:


settings -c++usestrict off

Only use one aspen_commands.txt per CodeCheck.


Configuring individual CodeChecks

CodeChecks can be written with different options using the define_options method. If you would like Aspen to exercise these different options, you may add multiple aspen_config* sub-folders for each check. Each subfolder can have 1 aspen_config*.json file. The * being the same name for both the directory and JSON file. An easy way to generate these configuration files is to setup up the Check using the CodeCheck feature in Understand and then export the CodeCheck configuration. An example of one of these configurations is available below.