Get Started

  • 2021.2
  • 03/26/2021
  • Public Content

Configure Your System

Intel® oneAPI Rendering Toolkit
If you use the
Intel® oneAPI Rendering Toolkit
(Render Kit) from the Intel® DevCloud, you can skip the prerequisite and configuration sections and start with running a sample application. Intel® DevCloud already has all the
Intel® oneAPI Rendering Toolkit
components installed. See Get Started with Intel DevCloud for oneAPI for details.
To set up your system, you need to:
Install the software prerequisites and the
Intel® oneAPI Rendering Toolkit
to the default installation directories. Otherwise, you might get an error.

Install Software Prerequisites

Open a new terminal session and run the following commands:
Ubuntu*
  1. Corporate network users: Ensure package management tools (for example, apt) can connect through your proxy servers if necessary. Set the following variables to configure your proxy:
    export http_proxy=http://<user>:<pass>@proxy.<server>.com:<port>
    export https_proxy=https://<user>:<pass>@proxy.<server>.com:<port>
    export HTTP_PROXY=${http_proxy}
    export HTTPS_PROXY=${https_proxy}
  2. Optional: If you want to run the build programs or run samples from a Docker* container, proceed with step 2. Otherwise, skip to step 3:
    1. Install Docker:
      sudo -E apt update
      sudo -E apt install docker.io
    2. Give a Docker session access to a window manager using Xhost*:
      xhost +
      Without the Xhost, GUI-based Intel oneAPI Rendering Toolkit samples launched from the Docker can give
      X11: Failed to open display
      error.
    3. Run the Docker and work from a container:
      • If you have proxy set up:
        sudo -E docker run --name renderkit --rm -it --privileged -e DISPLAY=$DISPLAY -v /tmp/.X11-unix:/tmp/.X11-unix -e HTTP_PROXY=$HTTP_PROXY -e HTTPS_PROXY=$HTTPS_PROXY -e http_proxy=$http_proxy -e https_proxy=$https_proxy ubuntu bash
      • If you do not have proxy set up:
        sudo -E docker run --name renderkit --rm -it --privileged -e DISPLAY=$DISPLAY -v /tmp/.X11-unix:/tmp/.X11-unix ubuntu bash
    4. In the Docker container, install sudo for convenience:
      apt update
      apt install sudo
    5. In the Docker container, install CPIO* and
      ncurses-term
      to support Intel oneAPI Rendering Toolkit installation:
      apt install cpio ncurses-term
    6. Copy your chosen
      Render Kit
      install files to the Docker container. Launch a new host terminal and copy the installer to your container. For example, if you have the offline installer downloaded, replace the
      <version>
      with your Render Kit version and run the following from the host terminal:
      sudo docker container ls
      sudo docker cp ~/Downloads/l_RenderKit_<version>_offline.sh <your_container_id>:/.
    7. In the Docker container, install the
      Intel® oneAPI Rendering Toolkit
      :
      Recommended:
      Use the
      opt-in
      option when installing the toolkit to send usage statistics. This helps Intel maintain the product.
      ./l_RenderKit_<version>_offline.sh
      For additional installation instructions, refer to the Installation Guide for Intel® oneAPI Toolkits.
      Run all the steps below from your Docker container.
  3. Install dependencies for building and running samples:
    1. Install pkg-config, GNU* Development Tools, and the Kitware* repository dependencies.
      sudo -E apt install apt-transport-https ca-certificates gnupg software-properties-common wget pkg-config build-essential
    2. Install the latest CMake* from the Kitware repository for your OS distribution, See full instruction at the Kitware APT Repository. For example, for Ubuntu OS 20.04:
      1. Check your OS distribution. For Ubuntu OS 20.04, it reports
        Focal Fossa
        .
        cat /etc/*release
      2. Add the repository to your sources and update:
        wget -O - https://apt.kitware.com/keys/kitware-archive-latest.asc 2>/dev/null | gpg --dearmor - | sudo tee /etc/apt/trusted.gpg.d/kitware.gpg >/dev/null
        sudo -E apt-add-repository 'deb https://apt.kitware.com/ubuntu/ focal main'
        sudo -E apt update
        sudo -E apt info cmake
      3. Install CMake:
        sudo -E apt -y install cmake
      If you already have the CMake installed, the Kitware version may conflict on updated dependencies. If your version of CMake is not from the Kitware repository, you can run the following to remove the conflicting version and reinstall:
      apt purge cmake
      Some OS distributions use older versions CMake that do not work with the Intel oneAPI Rendering Toolkit. Skip this step if you want to keep your version of CMake.
      Note the following:
      • Although
        the CMake and pkg-config build tools are
        not required by the oneAPI tools and toolkits, many oneAPI samples are provided as CMake projects and require CMake to build them.
        In some cases pkg-config is necessary to locate libraries needed to complete a build of the application.
      • Expected compiler toolchains access GNU Development Tools to provide a complete C/C++ development environment. If your distribution of Linux does not include the complete suite of GNU development tools, you need to install these tools. In the commands above, GNU development tools are installed with the
        build-essentials
        package. The
        Render Kit
        is validated with compilers that support C99 and C++11.
    3. Install Mozilla Firefox*, Grip*, Evince*, Eye of GNOME* image viewer, Git*, and ImageMagick*:
      sudo -E apt update
      sudo -E apt install git eog grip evince firefox imagemagick
      The installation of the GUI applications above applies GUI support libraries that enable advanced tutorials to run. Use these applications to:
      • Mozilla Firefox, Grip*, and Evince* to review advanced sample usage instructions.
      • A
        .ppm
        image viewer (for example, Image Magick, Eye of GNOME or GIMP*) to open result images.
      • Git to get the samples.
    4. Install the GLU and the imaging libraries:
      sudo -E apt install libpng-dev libpng16-16 libjpeg-turbo8-dev libjpeg-turbo8 libglfw3 libglfw3-dev libglu1-mesa libopenimageio-dev libopenimageio-doc libopenimageio2.1
      In the repository, the
      libopenimageio
      can be a different version for your OS distribution.
      dev
      -suffixed packages are used for building, while non-
      dev
      packages are used at application run time.
Red Hat* and Fedora*
Follow the Ubuntu* 18.04 setup section but use yum package manager equivalents for command lines that show apt manager use. For example, here are equivalent commands for installing CMake, pkg-config, and GNU DevTools:
sudo yum update sudo yum -y install cmake pkgconfig sudo yum groupinstall "Development Tools"
SUSE*
Follow the Ubuntu* 18.04 setup section but use zypper package manager equivalents for command lines that show apt manager use. For example, here are equivalent commands for installing CMake, pkg-config, and GNU DevTools:
sudo zypper update sudo zypper --non-interactive install cmake pkg-config sudo zypper --non-interactive install pattern devel_C_C++
Verify the Installation
Verify the installation by displaying the installation location with this command:
which cmake pkg-config make gcc g++
Location of each utility display:
/usr/bin/cmake
/usr/bin/pkg-config
/usr/bin/make
/usr/bin/gcc
/usr/bin/g++
For more information about CMake, refer to CMake.org.
If you are unable to install CMake using your Linux distribution's standard package manager, see the CMake.org downloads page for additional installation options.

Intel® Implicit SPMD Program Compiler

Intel® ISPC automatically vectorizes and leverages Intel® Streaming SIMD Extensions, Intel® Advanced Vector Extensions, Intel® Advanced Vector Extensions 2 and Intel® Advanced Vector Extensions 512 instructions.
You can download and install the Intel® ISPC from https://ispc.github.io/.
Intel® ISPC is not included in the
Render Kit
. By default, the
Render Kit
tutorial assets are set to be built with a system compiler.
If you want to use the
rkUtil
superbuild script to build the Intel oneAPI Rendering Toolkit, the Intel® ISPC is downloaded automatically. Using the
rkUtil
superbuild script is recommended for new and returning developers.
Using the Intel® ISPC is recommended to optimize application performance.

Set Environment Variables

To work at a Command Line Interface (CLI), you may configure the components of the oneAPI toolkits using environment variable script.
Option 1: Configure environment variables once per session
Option 1a
: Use the global environment script for Intel® oneAPI Toolkits once for your session. This sets variables for all installed components.
source <install-dir>/setvars.sh
where
<install-dit>
is the Intel oneAPI Toolkits installation directory. By default, it is
/opt/intel/oneapi/
.
Option 1b
: Run one of the component-specific environment scripts before running corresponding precompiled tutorial samples. The individual environment scripts are in the relative location of
env/vars.sh
for each component. By default, they are located at:
  • For Intel® OSPRay:
    /opt/intel/oneapi/ospray/latest/env/vars.sh
  • For Intel® Embree:
    /opt/intel/oneapi/embree/latest/env/vars.sh
  • For Intel® Open Image Denoise:
    /opt/intel/oneapi/oidn/latest/env/vars.sh
  • For Intel® Open Volume Kernel Library (Intel® Open VKL):
    /opt/intel/oneapi/openvkl/latest/env/vars.sh
  • For Intel® OSPRay Studio:
    /opt/intel/oneapi/ospray_studio/latest/env/vars.sh
For example, to set up environment variables for Intel Embree, run the following:
source /opt/intel/oneapi/embree/latest/env/vars.sh
Component scripts set the
LD_LIBRARY_PATH
variable to search directories with
oneTBB
libraries suitable for the tutorial programs. Within a bash terminal session, run precompiled samples only for one component, as
LD_LIBRARY_PATH
may cause a
oneTBB
mismatch if you have multiple
oneTBB
versions installed on your system.
Render Kit
programs typically use the following
oneTBB
libraries:
libtbb.so.2
,
libtbbmalloc.so.2
, and
libtbbmalloc_proxy.so.2
.
If your program execution results in segmentation faults or library-based symbol errors, consider using the option 1a to set environment variables. Use the
env -i
command to launch default shells.
Option 2: Configure environment variables to be set up automatically
Setting variables automatically in the shell session is not necessary and only recommended for advanced users of the
Intel® oneAPI Rendering Toolkit
.
If you choose this option to set the environment variables, make sure you set environment variables in the correct order that resolves your intended
oneTBB
dependency library
libtbb.so
.
You can use a component-specific script or a global script.
To set environment variables using component-specific scripts
:
  • To have the environment automatically set up for all projects, add a
    source <install_dir>/<component_dir>/latest/env/vars.sh
    component-specific command to a startup script where it will be invoked automatically. Replace
    <install_dir>
    with the path to your oneAPI install location and
    <component_dir>
    to the directory name for a specific component.
    For example, you can add the
    source <install_dir>/<component_dir>/latest/env/vars.sh
    command to your
    ~/.bashrc
    ,
    ~/.bashrc_profile
    , or
    ~/.profile
    file.
  • To make the settings permanent for all accounts on your system, create a one-line
    .sh
    script in your system's
    /etc/profile.d
    folder that sources
    vars.sh
    (for more details, see /etc/profile.d/).
To set environment variables using the global script:
You can find the
setvars.sh
script in the root folder of your oneAPI installation, which is typically
/opt/intel/oneapi/
for sudo or root users and
~/intel/oneapi/
when installed as a normal user.
To have the environment automatically set up for projects, add a
source <install_dir>/setvars.sh
component-specific command to a startup script where it will be invoked automatically (replace
<install_dir>
with the path to your oneAPI install location).
For example, you can add the
source <install_dir>/setvars.sh
command to your
~/.bashrc
or
~/.bashrc_profile
or
~/.profile
file. To make the settings permanent for all accounts on your system, create a one-line
.sh
script in your system's
/etc/profile.d
folder that sources
setvars.sh
(for more details, see Ubuntu documentation on Environment Variables).
For example, you can add the
source <install_dir>/setvars.sh
command to your
~/.zhrc
or
~/.zprofile
file.
Option 3: No environment variables
Setting environment variables in the Intel oneAPI Rendering Toolkit simplifies running sample applications. However, they are otherwise not absolutely required for building programs. Deployed applications can be built with a relative
rpath
for the local directory
.
that allows the dynamic linker to find required libraries.
  1. Build your programs with the
    rpath
    set similarly or to the local directory.
  2. Stage the desired version of the
    oneTBB
    runtime libraries along with resulting executables to disambiguate distributions of the
    oneTBB
    installed on the system.
Developers interested in this deployment are well suited to review the
superbuild
CMake script as part of the
rkUtil
component. See the Build Intel® oneAPI Rendering Toolkit Libraries for Linux OS article for details.

Feedback

Share your feedback on this article in the
Intel® oneAPI Rendering Toolkit
forum
.

Product and Performance Information

1

Performance varies by use, configuration and other factors. Learn more at www.Intel.com/PerformanceIndex.