A newer version of this document is available. Customers should click here to go to the newest version.
Visible to Intel only — GUID: GUID-583E6CDC-9CB5-4043-8ABC-2BCC0EBC7289
Use the setvars and oneapi-vars Scripts with Windows*
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 and it shortens the PATH names to help fix problems with long PATH names.
With the new Unified Directory Layout, you will see components installed together in a collection of common folders (eg., 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:
"C:\Program Files(x86)\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 oneAPI component tool folders contain an environment script named env\vars.bat 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) vars script on Windows is located at C:\Program Files (x86)\Intel\oneAPI\ipp\latest\env\vars.bat 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.bat is provided in the oneAPI installation folder. For example, in a default Component Directory Layout installation: C:\Program Files (x86)\Intel\oneAPI\setvars.bat. 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 run the script named oneapi-vars.bat. In a default Unified Directory Layout installation, on a Windows machine, that script is located here: C:\Program Files (x86)\Intel\oneAPI\<toolkit-version>\oneapi-vars.bat. The <toolkit-version> corresponds to the version number of the oneAPI toolkit that you installed. For example: C:\Program Files (x86)\Intel\oneAPI\2024.0\oneapi-vars.bat or C:\Program Files (x86)\Intel\oneAPI\2024.1\oneapi-vars.bat.
Running the setvars.bat script without any arguments causes it to locate and run all <component>\latest\env\vars.bat scripts in the Component Directory Layout installation. Changes made to the environment by these scripts can be seen by running the Windows set command after running setvars.bat.
Running the oneapi-vars.bat script without any arguments causes it to configure the environment for the specific toolkit version in which that oneapi-vars.bat script is located. It will also run any optional C:\Program Files (x86)\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 Windows set env command after running the oneapi-vars.bat script.
To learn more about how oneapi-vars.bat works, see Environment Initialization in the Unified Directory Layout
Visual Studio Code extension
Visual Studio Code* developers can install a oneAPI environment extension to run the setvars.bat within Visual Studio Code. Learn more in Using Visual Studio Code with Intel oneAPI Toolkits.
Command Line Arguments
The setvars.bat | oneapi-vars.bat script supports several command-line arguments, which are displayed using the --help option. For example:
Component Directory Layout
"C:\Program Files (x86)\Intel\oneAPI\setvars.bat" --help
Unified Directory Layout
"C:\Program Files (x86)\Intel\oneAPI\<toolkit-version>\oneapi-vars.bat" --help
The --config=file argument and the ability to include arguments that will be passed to the vars.bat scripts that are called by the setvars.bat | oneapi-vars.bat script can be used to customize the environment setup. The --config=file option is only supported by the setvars.bat 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.bat script to only call the vars.bat environment scripts for those two oneAPI components. More details and examples are provided in Use a Config file for setvars.bat on Windows.
Any extra arguments passed on the setvars.bat | oneapi-vars.bat command line that are not described in the setvars.bat | oneapi-vars.bat help message will be passed to every called vars.bat script. That is, if the setvars.bat | oneapi-vars.bat script does not recognize an argument, it assumes the argument is meant for use by one or more component vars scripts and passes those extra arguments to every component vars.bat 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® Threading Building Blocks (Intel® TBB) libraries to specify the application target architecture.
If more than one version of Microsoft Visual Studio* is installed on your system, you can specify which Visual Studio environment should be initialized as part of the oneAPI setvars.bat | oneapi-vars.bat environment initialization by adding the vs2017, vs2019, or vs2022 argument to the setvars.bat | oneapi-vars.bat command line. By default, the most recent version of Visual Studio is located and initialized.
Inspect the individual vars.bat scripts to determine which, if any, command line arguments they accept.
How to Run
Component Directory Layout
<install-dir>\setvars.bat
To run setvars.bat or a vars.bat script in a PowerShell window, use the following:
cmd.exe "/K" '"C:\Program Files (x86)\Intel\oneAPI\setvars.bat" && powershell'
Unified Directory Layout
<install-dir>\<toolkit-version>\oneapi-vars.bat
To run oneapi-vars.bat or a vars.bat script in a PowerShell window, use the following:
cmd.exe "/K" '"C:\Program Files (x86)\Intel\oneAPI\<toolkit-version>\oneapi-vars.bat" && powershell'
How to Verify
After executing setvars.bat | oneapi-vars.bat, verify success by searching for the SETVARS_COMPLETED environment variable. If setvars.bat | oneapi-vars.bat was successful the SETVARS_COMPLETED environment variable will have a value of 1:
set | find "SETVARS_COMPLETED"
Return value
SETVARS_COMPLETED=1
If the return value is anything other than SETVARS_COMPLETED=1 the test failed and oneapi-vars.bat did not complete properly.
Multiple Runs
Because many of the individual env\vars.bat scripts make significant changes to PATH, CPATH, and other environment variables, the top-level setvars.bat | oneapi-vars.bat script will not allow multiple invocations of itself in the same session. This is done to ensure that your environment variables do not exceed the maximum provided environment space, especially the %PATH% environment variable. Exceeding the available environment space results in unpredictable behavior in your terminal session and should be avoided.
This behavior can be overridden by passing setvars.bat | oneapi-vars.bat the --force flag. In this example, the user tries to run setvars.bat | oneapi-vars.bat twice. The second instance is stopped because setvars.bat | oneapi-vars.bat has already been run.
Component Directory Layout
> <install-dir>\setvars.bat :: initializing oneAPI environment ... (SNIP: lot of output) :: oneAPI environment initialized
> <install-dir>\setvars.bat .. code-block:: WARNING: setvars.bat has already been run. Skipping re-execution. To force a re-execution of setvars.bat, use the '--force' option. Using '--force' can result in excessive use of your environment variables.
In the third instance, the user runs <install-dir>\setvars.bat --force and the initialization is successful.
> <install-dir>\setvars.bat --force :: initializing oneAPI environment ... (SNIP: lot of output) :: oneAPI environment initialized
Unified Directory Layout
> <install-dir>\<toolkit-version>oneapi-vars.bat :: initializing oneAPI environment ... (SNIP: lot of output) :: oneAPI environment initialized
> <install-dir>\<toolkit-version>\oneapi-vars.bat .. code-block:: WARNING: oneapi-vars.bat has already been run. Skipping re-execution. To force a re-execution of oneapi-vars.bat, use the '--force' option. Using '--force' can result in excessive use of your environment variables.
In the third instance, the user runs <install-dir>\<toolkit-version>\oneapi-vars.bat --force and the initialization is successful.
> <install-dir>\<toolkit-version>\oneapi-vars.bat --force :: initializing oneAPI environment ... (SNIP: lot of output) :: oneAPI environment initialized
Environment Initialization in the Unified Directory Layout
Initializing the environment for the Unified Directory Layout is done by the oneapi-vars.bat script, not the setvars.bat 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%\<toolkit-version>\opt\<component-name>\latest\env\vars.bat
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.
ONEAPI_ROOT Environment Variable
The ONEAPI_ROOT variable is set by the top-level setvars.bat and oneapi-vars.bat scripts when either script is run. If there is already a ONEAPI_ROOT environment variable defined, setvars.bat | oneapi-vars.bat overwrites it in the cmd.exe session in which you ran the setvars.bat or oneapi-vars.bat script. This variable is primarily used by the oneapi-cli sample browser and the Microsoft Visual Studio and Visual Studio Code* sample browsers to help them locate oneAPI tools and components, especially for locating the setvars.bat or oneapi-vars.bat script if the SETVARS_CONFIG feature has been enabled. For more information about the SETVARS_CONFIG feature, see Automate the setvars.bat Script with Microsoft Visual Studio*.
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 environment variables.
Customizing the Call to the Microsoft Visual Studio* vcvarsall.bat Configuration Script
The Intel oneAPI development environment includes support for working with your Visual Studio project at the command prompt. For example, see the “Windows Start Menu > All apps > Visual Studio 2022” folder which typically contains shortcuts to multiple preconfigured Visual Studio setup scripts, such as the “Developer Command Prompt for VS 2022” shortcut. These shortcuts call a Microsoft Visual Studio configuration batch file named vcvarsall.bat which is typically found in the “%ProgramFiles%\Microsoft Visual Studio\2022\Professional\VC\Auxiliary\Build\” directory.
If you call the Intel oneAPI environment setup script (setvars.bat) at a command prompt, it will call the Visual Studio vcvarsall.bat script as part of the oneAPI environment setup process. Normally, the vcvarsall.bat environment setup is configured to match the setvars.bat environment setup. For example, it insures that the Visual Studio vcvarsall.bat is setup for 64-bit application development if setvars.bat is setup for a 64-bit oneAPI development environment (the default case).
If setvars.bat (or the compiler’s env\vars.bat) detects that the Visual Studio vcvarsall.bat has already been run, the vcvarsall.bat will not be run a second time. In other words, the setvars.bat script will honor the pre-existing Visual Studio vcvarsall.bat environment and configure itself to match (64-bit with 64-bit or 32-bit with 32-bit).
Other than the 32-bit or 64-bit arguments, the setvars.bat and compiler’s env\vars.bat scripts do not pass any arguments to the vcvarsall.bat script. If you wish to further customize the Visual Studio environment, you must do so before running setvars.bat or the compiler’s env\vars.bat script. For example:
run vcvarsall.bat directly with the necessary arguments
run setvars.bat (or the compiler’s env\vars.bat) script
At which point, your command prompt development environment will be configured.
The available vcvarsall.bat arguments for a Visual Studio 2022 Professional installation can be reviewed by typing:
> "%ProgramFiles%\Microsoft Visual Studio\2022\Professional\VC\Auxiliary\Build\vcvarsall.bat" help
at your Windows command prompt.