Using OpenCPI Environment Variables

Various environment variables are used to control OpenCPI. All start with the prefix OCPI_. Nearly all are optional. During installation, some are set when external tools are installed in non-default locations. Most are only used during development, and a few are used when applications run. Some of these variables are useful for debugging purposes. The OpenCPI environment is established when the user sources the opencpi-setup.sh script, in its installed location, which is the cdk subdirectory of the source installation (git repo).

When the setup script is sourced, the OCPI_CDK_DIR environment variable (which points to the OpenCPI installation) is set to the directory where the script lives; for example, ~/opencpi/cdk.

The setup command is:

source <location-of-opencpi>/cdk/opencpi-setup.sh -s

So, if OpenCPI is installed at ~/opencpi, the command is:

source ~/opencpi/cdk/opencpi-setup.sh -s

Sourcing this script with no arguments (or with the -h or --help option), will display more options for special cases. If you prefer the OpenCPI environment to be set up automatically at login, place this command in the shell (bash) login startup file (usually ~/.profile) after the export PATH line. Note that this will only take effect when you log in or when you start a new “login shell” using the -l (ell) option to bash, like:

bash -l

Any persistent site-specific environment variable settings are placed in the user-env.sh file in the installation directory (OCPI_ROOT_DIR). The file is created automatically during installation.

OpenCPI currently only supports the bash shell.

The first table below lists variables only relevant to the execution of applications, whether in a development environment or a deployed runtime environment. The second table is for variables only used in a development environment.

Table 7: OpenCPI Environment Variables for Runtime Configuration
Name	Description
OCPI_CDK_DIR	This variable set by OpenCPI automatically and indicates the location of the OpenCPI development or runtime installation. This variable should not be set directly. Even though it has CDK in its name, it is indeed used at runtime to locate the OpenCPI runtime installation.
OCPI_LIBRARY_PATH	A colon-separated set of directories to be searched for runtime artifacts. When referencing the artifacts exported by a project with sources, be sure to reference the project’s `exports` subdirectory, not its source location. When running unit tests or applications in projects, this variable is set automatically if not set already. In pure runtime environments, it may need to be set when artifacts are placed in directories of the user’s choice.
OCPI_LOG_LEVEL	The log level (amount of logging) output by the runtime system. The default is zero (0), indicating no logging output. The maximum is 20. Commonly useful startup and diagnostic information (for example, artifact discovery feedback) is provided at log level 8. Unusual events are logged at level 4. Logging is to `stderr`.
OCPI_SYSTEM_CONFIG	The runtime system XML system configuration file. If not specified, the file is located trying these locations in order: `$OCPI_ROOT_DIR/system.xml` `$OCPI_CDK_DIR/default-system.xml`
OCPI_DMA_MEMORY	Allows super-user privileged processes to specify physical DMA memory to use when the OpenCPI kernel driver is not used. The format is `<mbytes>M$0x<address>`, with `mbytes` in decimal, and `address` in hexadecimal. Rarely used.
OCPI_SMB_SIZE	The size (in bytes, decimal, with optional K or M suffix) of the memory pool to be used for buffers in software containers. Must support buffers for all ports used to communicate into or out of the container.

Table 8: OpenCPI Environment Variables for Development Configuration
Name	Description
OCPI_PROJECT_PATH	A colon-separated set of project directories to be considered in addition to those that are registered. This variable can be used to temporarily augment the project registry when testing a new project. Rarely used.
OCPI_PROJECT_REGISTRY_DIR	The location of the current project registry when dealing with unregistered projects or ocpidev show commands. By default, this location is `$OCPI_ROOT_DIR/project-registry`, but setting this variable overrides this.

All of these variables are optional. If you want permanent settings made when using a given OpenCPI installation, settings (export commands) may be placed in the user‑env.sh file in the installation.