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.
Note
Changes to your environment made by running the setvars.bat
| oneapi-vars.bat
script (or the individual vars.bat
scripts) are not permanent.
Those changes only apply to the cmd.exe
session in which the
setvars.bat
| oneapi-vars.bat
environment script was executed.
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.
Note
Support for Microsoft Visual Studio* 2017 is deprecated as of the Intel® oneAPI 2022.1 release, and will be removed in a future release.
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 argumentsrun 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.