A high-performance general-purpose compute library
Using ArrayFire with Microsoft Windows and Visual Studio

If you have not already done so, please make sure you have installed, configured, and tested ArrayFire following the installation instructions.

The big picture

The ArrayFire Windows installer creates the following:

  1. AF_PATH environment variable to point to the installation location. The default install location is C:\Program Files\ArrayFire\v3
  2. AF_PATH/include : Header files for ArrayFire (include directory)
  3. AF_PATH/lib : All ArrayFire backend libraries, dlls, and dependency dlls (library directory)
  4. AF_PATH/examples : Examples to get started
  5. AF_PATH/cmake : CMake config files
  6. AF_PATH/uninstall.exe : Uninstaller

Build and Run Helloworld

This can be done in two ways either by using CMake build tool or using Visual Studio directly.

Using CMake

  1. Download and install CMake, preferably the latest version.
  2. Open CMake-GUI and set the field Where is the source code to the root directory of examples.
  3. Set the field Where to build the binaries to path_to_examples_root_dir/build and click the Configure button.
  4. CMake will prompt you to create the build directory if not already present. Click "yes" to create the build directory.
  5. Before the configuration begins, CMake will show you a list (drop-down menu) of available Visual Studio versions. Select one and check the radio button that says Use default native compilers and click finish.
  6. CMake will show you errors in red text, if any, once configuration is finished. Sometimes a second configuration is necessary.
  7. Click Generate button to generate the Visual Studio solution files for the examples.
  8. Click Open Project button that is right next to Generate button to open the solution file.
  9. You will see the examples segregated into four sets named after the compute backends of ArrayFire: cpu, cuda, oneapi, & opencl, if you installed all backends. Select the helloworld project from any of the installed backends, mark it as startup project, and hit F5.
  10. Once the helloworld example builds, you will see a console window with the output from helloworld program.

Using Visual Studio

  1. Open Visual Studio and create an empty C++ project.
  2. Right-click the project and add an existing source file examples/helloworld/helloworld.cpp to this project.
  3. Add "$(AF_PATH)/include;" to Project Properties -> C/C++ -> General -> Additional Include Directories.
  4. Add "$(AF_PATH)/lib;" to Project Properties -> Linker -> General -> Additional Library Directories.
  5. Add afcpu.lib, afcuda.lib, afoneapi.lib, or afopencl.lib to Project Properties -> Linker -> Input -> Additional Dependencies. based on your preferred backend.
  6. (Optional) You may choose to define NOMINMAX, AF_<CPU/CUDA/ONEAPI/OPENCL>, or AF_<DEBUG/RELEASE> in your projects. This can be added to Project Properties -> C/C++ -> General -> Preprocessor-> Preprocessory definitions.
  7. Build and run the project. You will see a console window with the output from helloworld program.

Using ArrayFire within Existing Visual Studio Projects

This is divided into three parts:

Part A: Adding ArrayFire to an existing solution (Single Backend)

Note: If you plan on using Native CUDA code in the project, use the steps under Part B.

Adding a single backend to an existing project is quite simple:

  1. Add "$(AF_PATH)/include;" to Project Properties -> C/C++ -> General -> Additional Include Directories.
  2. Add "$(AF_PATH)/lib;" to Project Properties -> Linker -> General -> Additional Library Directories.
  3. Add afcpu.lib, afcuda.lib, afopencl.lib, or af.lib to Project Properties -> Linker -> Input -> Additional Dependencies. based on your preferred backend.

Part B: Adding ArrayFire CUDA to a new/existing CUDA project

Lastly, if your project contains custom CUDA code, the instructions are slightly different as it requires using a CUDA NVCC Project:

  1. Create a custom "CUDA NVCC project" in Visual Studio
  2. Add "$(AF_PATH)/include;" to Project Properties -> CUDA C/C++ -> General -> Additional Include Directories.
  3. Add "$(AF_PATH)/lib;" to Project Properties -> Linker -> General -> Additional Library Directories.
  4. Add afcpu.lib, afcuda.lib, afopencl.lib, or af.lib to Project Properties -> Linker -> Input -> Additional Dependencies. based on your preferred backend.

Part C: Project with all ArrayFire backends

If you wish to create a project that allows you to use all the ArrayFire backends with ease, you should use af.lib in step 3 from Part A.

You can alternately download the template project from ArrayFire Template Projects

Using ArrayFire with CMake

ArrayFire ships with a series of CMake scripts to make finding and using the library easy.

First, create a file called CMakeLists.txt in your project directory: 

cd your-project-directory
touch CMakeLists.txt

and populate it with the following code: 

find_package(ArrayFire)
add_executable(<my_executable> [list your source files here])

# The Unified backend lets you choose the backend at runtime.
# To use the Unified backend, do the following:
target_link_libraries(<my_executable> ArrayFire::af)

, where <my_executable> is the name of the executable to create. See the CMake documentation for more information on how to use CMake. To link with a specific backend directly, replace the ArrayFire::af with the following for their respective backends.

  • ArrayFire::afcpu for CPU backend.
  • ArrayFire::afcuda for CUDA backend.
  • ArrayFire::afoneapi for oneAPI backend.
  • ArrayFire::afopencl for OpenCL backend.

Next, instruct CMake to create build instructions and compile them. We suggest using CMake's out-of-source build functionality to keep your build and source files cleanly separated. To do this, open the CMake GUI.

  • Under "source directory", add the path to your project.
  • Under "build directory", add the path to your project and append /build.
  • Click "configure" and choose a 64-bit Visual Studio generator.
  • If the configuration was successful, click "generate". This will create a my-project.sln file under build. Click Open Project in CMake-GUI to open the solution and compile the ALL_BUILD project.