A newer version of this document is available. Customers should click here to go to the newest version.
Visible to Intel only — GUID: GUID-01F2055E-24E6-4AEB-B47F-0D817D662030
Visible to Intel only — GUID: GUID-01F2055E-24E6-4AEB-B47F-0D817D662030
Use the setvars and oneapi-vars Scripts with Linux*
The Unified Directory Layout was implemented in 2024.0. If you have multiple toolkit versions installed, the Unified layout adds the ability to ensure your development environment contains the component versions that were released as part of that specific toolkit version.
With the new Unified Directory Layout, you will see components installed together in a collection of common folders (e.g., bin, lib, include, share, etc.). These common folders are located in a top-level folder that is named for the toolkit version number. For example:
/opt/intel/oneapi/2024.0/ |-- bin |-- lib |-- include ...etc...
The directory layout that was used prior to 2024.0 is still supported on new and existing installations. This prior layout is called the Component Directory Layout. Now you have the option to use the Component Directory Layout or the Unified Directory Layout.
Differences in Component Directory Layout and Unified Directory Layout
Most of the component tool folders contain an environment script named env/vars.sh that configures the environment variables needed by that component to support oneAPI development work. For example, in a default installation, the Intel® Integrated Performance Primitives (Intel® IPP) env/vars script on Linux is located at: /opt/intel/oneapi/ipp/latest/env/vars.sh in the Component Directory Layout. This pattern is shared by all oneAPI components that include an env\vars setup script.
In the Component Directory Layout the component env/vars scripts can be called directly or collectively. To call them collectively, a script named setvars.sh is provided in the oneAPI installation folder. For example, in a default Component Directory Layout installation on a Linux machine: /opt/intel/oneapi/setvars.sh. The Unified Directory Layout does not use the env/vars.sh scripts to initialize the development environment. Instead, each component is “corralled” into shared folders that are common to the components. In other words, each component contributes its header files to a single common include folder, its library files to a single common lib folder, and so on.
Advantages of the Unified Directory Layout
The Unified Directory Layout makes it much easier to switch between different toolkit versions without having to build and maintain setvars config files or play games with installation of multiple oneAPI toolkits. It is also useful for limiting the length of environment variables, especially the PATH variable, on Windows development systems, a troublesome issue for some Windows developers.
The Unified Directory Layout environment variables can only be setup collectively. To initialize the development environment variables a script named oneapi-vars.sh. In a default Unified Directory Layout installation, on a Linux machine, that script is located here: /opt/intel/oneapi/<toolkit-version>/oneapi-vars.sh. The <toolkit-version> corresponds to the version number of the oneAPI toolkit that you installed.
Example:
/opt/intel/oneapi/2024.0/oneapi-vars.sh /opt/intel/oneapi/2024.1/oneapi-vars.sh
Sourcing the setvars.sh script without any arguments causes it to locate and source all <component>/latest/env/vars.sh scripts in the Component Directory Layout installation. Changes made to the environment by these scripts can be seen by running the env command after running the environment setup scripts.
Sourcing the oneapi-vars.sh script without any arguments causes it to configure the environment for the specific toolkit version in which that oneapi-vars.sh script is located. It will also source any optional /opt/intel/oneapi/<toolkit-version>/etc/<component>/vars.sh scripts that are part of that Unified Directory installation. Changes made to the environment by these scripts can be seen by running the env command after sourcing the oneapi-vars.sh script.
To learn more about the differences in setvars and oneapi-vars, see Environment Initialization in the Unified Directory Layout
Command Line Arguments
The setvars.sh / oneapi-vars script supports several command-line arguments, which are displayed using the --help option. For example:
Component Directory Layout
For system-wide installations:
. /opt/intel/oneapi/setvars.sh --help
For private installations:
. ~/intel/oneapi/setvars.sh --help
Unified Directory Layout
For system-wide installations:
. /opt/intel/oneapi/<version>/oneapi-vars.sh --help
For private installations:
. ~/intel/oneapi/<version>/oneapi-vars.sh --help
The --config=file argument and the ability to include arguments that will be passed to the vars.sh scripts that are called by the setvars.sh / oneapi-vars.sh script can be used to customize the environment setup. The --config=file option is only supported by the setvars.sh script.
The --config=file argument provides the ability to limit environment initialization to a specific set of oneAPI components. It also provides a way to initialize the environment for specific component versions. For example, to limit environment setup to just the Intel® IPP library and the Intel® oneAPI Math Kernel Library (oneMKL), pass a config file that tells the setvars.sh / oneapi-vars script to only call the vars.sh environment scripts for those two oneAPI components. More details and examples are provided in Use a Config file for setvars.sh on Linux.
Any extra arguments passed on the setvars.sh / oneapi-vars command line that are not described in the setvars.sh / oneapi-vars help message will be passed to every called vars.sh script. That is, if the setvars.sh / oneapi-vars script does not recognize an argument, it assumes the argument is meant for use by one or more component scripts and passes those extra arguments to every component vars.sh script that it calls. The most common extra arguments are ia32 and intel64, which are used by the Intel compilers and the Intel® IPP, oneMKL, and Intel® oneAPI Threading Building Blocks libraries to specify the application target architecture.
Inspect the individual vars.sh scripts to determine which, if any, command line arguments they accept.
How to Run
Component Directory Layout
source <install-dir>/setvars.sh
Unified Directory Layout
source <install-dir>/<toolkit-version>/oneapi-vars.sh
Component Directory Layout
$ bash -c 'source <install-dir>/setvars.sh ; exec csh'
Unified Directory Layout
$ bash -c 'source <install-dir>/<toolkit-version>/oneapi-vars.sh ; exec csh'
If environment variables are set correctly, you will see a confirmation message similar to this:
If you receive an error message, troubleshoot using the Diagnostics Utility for Intel® oneAPI Toolkits, which provides system checks to find missing dependencies and permissions errors. Learn more.
Alternatively, use the modulefiles scripts to set up your development environment. The modulefiles scripts work with all Linux shells.
If you wish to fine tune the list of components and the version of those components, use a setvars config file to set up your development environment.
Multiple Runs
Because many of the individual env/vars.sh scripts make significant changes to PATH, CPATH, and other environment variables, the top-level setvars.sh / oneapi-vars script will not allow multiple invocations of itself in the same session. This is done to ensure that your environment variables do not become too long due to redundant path references, especially the $PATH environment variable.
This behavior can be overridden by passing setvars.sh / oneapi-vars the --force flag. In this example, the user tries to run setvars.sh / oneapi-vars twice. The second instance is stopped because setvars.sh / oneapi-vars has already been run.
Component Directory Layout
$ source <install-dir>/setvars.sh initializing oneAPI environment ... (SNIP: lot of output) oneAPI environment initialized ::
$ source <install-dir>/setvars.sh WARNING: setvars.sh has already been run. Skipping re-execution. To force a re-execution of setvars.sh, use the '--force' option. Using '--force' can result in excessive use of your environment variables
In the third instance, the user runs setvars.sh --force and the initialization is successful.
$ source <install-dir>/setvars.sh --force initializing oneAPI environment ... (SNIP: lot of output) code-block:: oneAPI environment initialized ::
Sourcing setvars.sh with the –force argument may lead to argument pollution with bash version 3.x and 4.x, as shown below:
source <install-dir>/setvars.sh --force initializing oneAPI environment ... (SNIP: lot of output) oneAPI environment initialized :: $ echo ${@} advisor=latest ccl=latest compiler=latest dal=latest debugger=latest dev-utilities=latest dnnl=latest dpcpp-ct=latest dpl=latest ipp=latest ippcp=latest mkl=latest mpi=latest tbb=latest vtune=latest
Note: This is not an issue when setvars.sh is sourced with bash version 5.x, zsh, ksh or dash.
To work around this issue pass the shell command-line options via the SETVARS_ARGS environment variable.
For example:
$ SETVARS_ARGS="--force" source <install-dir>/setvars.sh initializing oneAPI environment ... (SNIP: lot of output) oneAPI environment initialized :: $ echo ${@} $
Unified Directory Layout
$ source <install-dir>/<version>/oneapi-vars.sh initializing oneAPI environment ... (SNIP: lot of output) oneAPI environment initialized ::
$ source <install-dir>/<toolkit-version>/oneapi-vars.sh WARNING: setvars.sh has already been run. Skipping re-execution. To force a re-execution of setvars.sh, use the '--force' option. Using '--force' can result in excessive use of your environment variables
In the third instance, the user runs oneapi-vars.sh --force and the initialization is successful.
$ source <install-dir>/ ``oneapi-vars.sh`` --force initializing oneAPI environment ... (SNIP: lot of output) oneAPI environment initialized ::
Sourcing oneapi-vars.sh with the --force argument may lead to argument pollution with bash version 3.x and 4.x, as shown below:
$ source <install-dir>/<toolkit-version>/oneapi-vars.sh --force initializing oneAPI environment ... (SNIP: lot of output) oneAPI environment initialized :: $ echo ${@} advisor=latest ccl=latest compiler=latest dal=latest debugger=latest dev-utilities=latest dnnl=latest dpcpp-ct=latest dpl=latest ipp=latest ippcp=latest mkl=latest mpi=latest tbb=latest vtune=latest
Note: This is not an issue when oneapi-vars.sh is sourced with bash version 5.x, zsh, ksh or dash.
To work around this issue pass the shell command-line options via the SETVARS_ARGS environment variable.
For example:
$ SETVARS_ARGS="--force" source <install-path>/<toolkit-version>/oneapi-vars.sh .. code-block:: initializing oneAPI environment ... (SNIP: lot of output) .. code-block:: oneAPI environment initialized :: $ echo ${@} $
Environment Initialization in the Unified Directory Layout
The Unified Directory Layout was implemented with the 2024.0 release. If you are unfamiliar with the change, please see Use the setvars and oneapi-vars Scripts with Linux at the top of this page.
Initializing the environment for a “unified” directory is done by the oneapi-vars.sh script, not the setvars.sh script. The usage of oneapi-vars is similar to setvars, but there are some subtle differences.
The key difference between the setvars script and the oneapi-vars script is that the setvars script does not define any environment variables (other than ONEAPI_ROOT) and the oneapi-vars script defines the common environment variables.
In the Component Directory Layout, each component is responsible for defining the environment variables needed in order to function. For example, in the Component Directory Layout each component adds its linkable library folders to LD_LIBRARY_PATH and include headers to CPATH, etc. The components do this via their individual vars scripts, which are always located in:
$ONEAPI_ROOT/<component-name>/<component-version>/env/vars.sh
The Unified Directory Layout combines the externally facing include, lib, and bin folders into a set of common folders. In this scenario, the top-level oneapi-vars script defines the environment variables that are needed to locate these common folders. For example, setvars will define LD_LIBRARY_PATH as $ONEAPI_ROOT/lib and CPATH as $ONEAPI_ROOT/include and so on.
Modulefiles continue to be supported in the 2024.0 release, and can be used as an alternative to using setvars.sh to initialize an environment setup. Modulefiles scripts are only supported on Linux.
ONEAPI_ROOT Environment Variable
The ONEAPI_ROOT variable is set by the top-level setvars.sh and oneapi-vars.sh script when either script is sourced. If there is already a ONEAPI_ROOT environment variable defined, setvars.sh overwrites it in the terminal session in which you sourced the setvars.sh or oneapi-vars.sh script. This variable is primarily used by the oneapi-cli sample browser and the Eclipse* and Visual Studio Code* sample browsers to help them locate oneAPI tools and components, especially for locating the setvars.sh script if the SETVARS_CONFIG feature has been enabled. For more information about the SETVARS_CONFIG feature, see Automate the setvars.sh Script with Eclipse*.
With the 2024.0 release, the installer does not add the ONEAPI_ROOT variable to the environment. To add it to your default environment, define the variable in your local shell initialization file(s) or in the system’s /etc/environment file.