Name

ocpidev-run — runs applications and component unit tests

Synopsis

ocpidev run [<options>] <noun> [<name>]

DESCRIPTION

The run verb is the OpenCPI command for running applications and component unit tests in the development (project) environment.

When running applications (all in the applications/ subdirectory of the project), this command runs them based their XML file and any run-related attributes/options found there. Applications may be simple XML-based applications without their own directories, XML-based applications with their own directories or ACI-based (C++/Python) applications in their own directories.

When running component unit tests with default options, all unit tests are run, with any required preparation done before the tests are run. Running component unit tests normally proceeds in three phases:

  • Prepare: discover available built workers, HDL assemblies and available platforms, creating execution scripts to execute all feasible tests.
  • Execute: execute (prepared) tests for all workers, configurations, test cases and platforms.
  • Verify: verify results from the execution of tests on workers and platforms.

Normally all three are run, but they can be individually run or two out of three can be run using the --phase option to this run verb.

The --only-platform and --exclude-platform options are used to limit the runtime platforms used during the phases of unit testing.

Asset types to be specified in the <noun> argument are:

application
Run the specified application.
applications
Run all the applications in a project.
library
Run all the unit tests in the specified component library.
project
Run all applications and component unit tests in the specified project.
test
Run the specified component unit test.
tests
Run all the component unit tests in a project or library.

When running applications or unit tests from within their directories, no noun or name arguments are required.

OPTIONS

In addition to the options common to all OpenCPI tools (see opencpi(1)), the following options can be specified for the run verb. In the option descriptions below, a plus sign (+) indicates that the option can be specified more than once on the command line.

Options That Apply to Applications Only

--after <args>+
Specify the argument(s) to insert at the end of the execution command line.
--before <args>+
Specify the argument(s) to insert before the ACI executable or the ocpirun command; for example, environment settings or prefix commands.
--run-arg <args>+
Specify the argument(s) to insert immediately after the ACI executable or the ocpirun command.

You can also add run-arg arguments after the application <name>; for example, to specify options to ocpirun for XML applications. Preface these arguments with the double hyphen (--) notation to indicate that they are not options to the ocpidev command itself. For example, if you want to run an application with a number of run-arg arguments, you can use any of the following syntaxes:

ocpidev run application myapp -- -v -d -Pxsim
ocpidev run application myapp --run-arg=-v --run-arg=-d --run-arg=-Pxsim
ocpidev run application myapp --run-arg="-v -d -Pxsim"

For an XML application, these command lines perform the command:

ocpirun -v -d -Pxsim myapp

For more information on how to use these options, see the section "Applications in Projects" in the OpenCPI Application Development Guide.

Options That Apply to Component Unit Tests Only

-G <platform>, --only-platform=<platform>+
Specify the runtime platform to use with a unit test.
-Q <platform>, --exclude-platform=<platform>+
Specify the runtime platform to omit from a component unit test.
-l <library>, --library=<library>
Run the component unit test suite in the specified library.
--accumulate-errors
Report execution or verification errors as they occur rather than ending the test on the first failure detected.
--case=<case-name>[,<case-name>[,<case-name>…]]
Specify the test case(s) to be executed/verified. If this option is not used, all feasible cases are executed/verified. You can specify wildcards in <case-name>. To specify a subcase, use the notation <case-name>.<subcase-number>. Examples: case*., case0.0*, case00.01
--keep-simulations
Keep HDL simulation files regardless of verification results. By default, simulation files are removed if the verification is successful. Warning: Simulation files can become large!
--phase=<phase>+
Specify which non-building phase(s) of unit testing to run. Valid phases here are: prepare, execute, verify, and view. The view phase is used to run only the view scripts for the unit test, without other phases. The --view option can be used to add viewing along with other phases.
--remotes=<system>
Specify the remote system to run the test(s) by setting the OCPI_REMOTE_TEST_SYS variable. See the section "Defining Remote Systems for Executing Tests" in the OpenCPI Component Development Guide for more information.
--view
Run the view script (view.sh) for the test at the conclusion of the test’s execution.

ENVIRONMENT VARIABLES

The following environment variables affect ocpidev run operation:

OCPI_LIBRARY_PATH
A list of directories, separated by colons, to be searched for runtime artifacts. This variable is set automatically (if not already set) when running component unit tests or applications in projects with ocpidev run.

EXAMPLES

  1. Run an application named myapp: 

    ocpidev run application myapp

  2. Run all the applications in the current project: 

    ocpidev run applications

  3. Inside the assets project, run the fir_real_see unit test in the dsp_comps library located at components/dsp_comps: 

    ocpidev run -l dsp_comps test fir_real_sse

  4. Inside the assets project, run all tests in the dsp_comps library located at components/dsp_comps: 

    ocpidev run library dsp_comps

  5. Inside the assets project, run the view script only for the fir_real_sse test in the dsp_comps library located at components/dsp_comps: 

    ocpidev run -l dsp_comps --phase=view test fir_real_sse

BUGS

See https://www.opencpi.org/report-defects

RESOURCES

See the main web site: https://www.opencpi.org

See the OpenCPI Application Development Guide: https://opencpi.gitlab.io/releases/latest/docs/OpenCPI_Application_Development_Guide.pdf

See the OpenCPI Component Development Guide: https://opencpi.gitlab.io/releases/latest/docs/OpenCPI_Component_Development_Guide.pdf

SEE ALSO

ocpidev(1) ocpidev-build(1) ocpidev-clean(1) ocpidev-create(1) ocpidev-delete(1) ocpidev-refresh(1) ocpidev-register(1) ocpidev-set(1) ocpidev-show(1) ocpidev-unregister(1) ocpidev-unset(1) ocpidev-utilization(1) ocpirun(1)

COPYING

Copyright (C) 2023 OpenCPI www.opencpi.org. OpenCPI is free software: you can redistribute it and/or modify it under the terms of the GNU Lesser General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.