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 backends libraries, dlls and dependency dlls (library directory)
  4. AF_PATH/examples : Examples to get started. Some examples also have pre-built exectuables
  5. AF_PATH/cmake : CMake config files for automatic configuration by external projects
  6. AF_PATH/uninstall.exe : Uninstaller
  7. AF_PATH/* : Other miscellenous files including licenses, logos, copyrights

The installer also appends %AF_PATH%/lib to the User PATH variable.

To add %AF_PATH%/lib to PATH for all users see the windows section in installation instructions.

Dealing with CUDA NMMV DLLs

When using CUDA with ArrayFire you may encounter a linker error indicating the NVVM DLLs are missing. This is because the NVVM DLLs are not part of the standard CUDA_PATH\bin installation directory that is added to your PATH when the CUDA installer runs. Thus, NVVM will not be found during runtime. There are a few ways to deal with this issue:

  1. Copy the DLLs to the exectuable location. This is, by far, the cleanest solution and we recommend doing this with ArrayFire projects. To do so, create a post-build event to copy the NVVM DLL as discusses below in Step 3 - Part A.
  2. Copy CUDA_PATH\nvvm\bin\nvvm64_30_0.dll to CUDA_PATH\bin. This is a one time copy such that the NVVM DLL is now with all the other CUDA dlls and in a directory that is a part of PATH and hence the DLL can be detected automatically.
  3. Add %CUDA_PATH%\nvvm\bin to the system PATH environment variable. This will allow automatic detection by the system and No further copying will be required. ArrayFire does not add this to PATH since the CUDA installer doesn't add it to PATH.

Step 1: Running pre-built executables

The ArrayFire installer ships with a few pre-built executables with the examples. These should run out of the box when double clicked.

Some prebuilt examples are:

  • Helloworld (examples/helloworld)
  • BLAS (examples/benchmarks)
  • FFT (examples/benchmarks)
  • Pi Estimation (examples/benchmarks)
  • Conway (Graphics) (examples/graphics)

Note: For the CUDA executables, you will need to copy CUDA_PATH\nvvm\bin\nvvm64_30_0.dll to the location of the executables.

Step 2: Build and Run a Project

  1. Open Visual Studio 2013. Load the HelloWorld solution which is located at AF_PATH/examples/helloworld/helloworld.sln.
  2. Build the helloworld example. Be sure to, select the platform/configuration of your choice using the platform drop-down (the options are CPU, CUDA, OpenCL, and Unified) and Solution Configuration drop down (options of Release and Debug) menus.
  3. Run the helloworld example.

Step 3: Using ArrayFire within Visual Studio

This is divided into 4 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 or afcuda.lib or afopencl.lib to Project Properties -> Linker -> Input -> Additional Dependencies. based on your preferred backend.
  4. (Optional) You may choose to define NOMINMAX, AF_<CPU/CUDA/OPENCL> and/or AF_<DEBUG/RELEASE> in your projects. This can be added to Project Properties -> C/C++ -> General -> Preprocessor-> Preprocessory definitions.

If you are using the CUDA backend, it is important to ensure that the CUDA NVVM DLLs are copied to the exectuable directory. This can be done by adding a post build event.

Open the Project Properties -> Build Events -> Post Build Events dialog and add the following lines to it.

echo copy "$(CUDA_PATH)\nvvm\bin\nvvm64*.dll" "$(OutDir)"
copy "$(CUDA_PATH)\nvvm\bin\nvvm64*.dll" "$(OutDir)"

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 or afcuda.lib or afopencl.lib to Project Properties -> Linker -> Input -> Additional Dependencies. based on your preferred backend.
  5. (Optional) You may choose to define NOMINMAX, AF_CUDA and/or AF_<DEBUG/RELEASE> in your projects. This can be added to Project Properties -> C/C++ -> General -> Preprocessor-> Preprocessory definitions.
  6. Pick a solution to handle the NVVM DLLs. We recommend the post build event method used in Part A.

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, the best way to go is to copy the HelloWorld sln/vcxproj/cpp file trio and rename them to suit your project.

All the ArrayFire examples are pre-configured for all ArrayFire backends as well as the Unified API. These can be chosen from the Solution/Platform configuration drop down boxes.

You can alternately download the template project from ArrayFire Template Projects

Part D: ArrayFire with CMake

NOTE: The ArrayFire installer sets up CMake file and registry so that it can be found by CMake by simply using the Find_PACKAGE(ArrayFire) command.

If you are writing a new ArrayFire project in C/C++ from scratch, we suggest you grab a copy of our CMake Project Example; however, it is useful to read the documentation below in case you need to add ArrayFire to an existing project.

As discussed above, ArrayFire ships with a series of CMake scripts to make finding and using our library easy. The scripts will automatically find all versions of the ArrayFire library and pick the most powerful of the installed backends (typically CUDA).

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)
INCLUDE_DIRECTORIES(${ArrayFire_INCLUDE_DIRS})

... [gather source files, etc.]

# If you intend to use OpenCL, you need to find it
FIND_PACKAGE(OpenCL)
SET(EXTRA_LIBS ${CMAKE_THREAD_LIBS_INIT} ${OpenCL_LIBRARIES})

# Or if you intend to use CUDA, you need it as well as NVVM:
FIND_PACKAGE(CUDA)
FIND_PACKAGE(NVVM) # this FIND script can be found in the ArrayFire CMake example repository
SET(EXTRA_LIBS ${CMAKE_THREAD_LIBS_INIT} ${CUDA_LIBRARIES} ${NVVM_LIB})

ADD_EXECUTABLE(my_executable [list your source files here])
TARGET_LINK_LIBRARIES(my_executable ${ArrayFire_LIBRARIES} ${EXTRA_LIBS})

where my_executable is the name of the executable you wish to create. See the CMake documentation for more information on how to use CMake. Clearly the above code snippet precludes the use of both CUDA and OpenCL, see the ArrayFire CMake Example for an example of how to build executables for both backends from the same CMake script.

In the above code listing, the FIND_PACKAGE will find the ArrayFire include files, libraries, and define several variables including: 

ArrayFire_INCLUDE_DIRS    - Location of ArrayFire's include directory.
ArrayFire_LIBRARIES       - Location of ArrayFire's libraries.
                            This will default to a GPU backend if one
                            is found
ArrayFire_FOUND           - True if ArrayFire has been located

If you wish to use a specific backend, the find script also defines these variables: 

ArrayFire_CPU_FOUND         - True of the ArrayFire CPU library has been found.
ArrayFire_CPU_LIBRARIES     - Location of ArrayFire's CPU library, if found
ArrayFire_CUDA_FOUND        - True of the ArrayFire CUDA library has been found.
ArrayFire_CUDA_LIBRARIES    - Location of ArrayFire's CUDA library, if found
ArrayFire_OpenCL_FOUND      - True of the ArrayFire OpenCL library has been found.
ArrayFire_OpenCL_LIBRARIES  - Location of ArrayFire's OpenCL library, if found
ArrayFire_Unified_FOUND     - True of the ArrayFire Unified library has been found.
ArrayFire_Unified_LIBRARIES - Location of ArrayFire's Unified library, if found

Therefore, if you wish to target a specific specific backend, simply replace ${ArrayFire_LIBRARIES} with ${ArrayFire_CPU}, ${ArrayFire_OPENCL}, ${ArrayFire_CUDA}, or ${ArrayFire_Unified} in the TARGET_LINK_LIBRARIES command above.

Next we need to instruct CMake to create build instructions and then compile. 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 Visual Studio 2013 Win 64 as the generator.
  • If configuration was successful, click generate. This will create a my-project.sln file under build. You can open this in Visual Studio and compile the ALL_BUILD project.

The ArrayFire CMake Example is a CMake project used to demo how ArrayFire can be using with a CMake project.

Note: The CMake project does not add the post build event to copy the NVVM DLLs in case of CUDA backend. You will need to either copy it manually to the exectuable directory, or pick another solution for it.