Setting up an ArrayFire project on Windows

Brian KloppenborgArrayFire Leave a Comment

Continuing our blog series “Learning ArrayFire from scratch” today we will discuss how to set up an ArrayFire project on Windows using Visual Studio or CMake.

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:

AF_PATH                 Environment variable to point to the installation location.
                        This is normally C:/Program Files/ArrayFire/v*
AF_PATH/include         Header files for ArrayFire (Include Dir)
AF_PATH/lib             All ArrayFire backends libraries, dlls and dependency dlls 
                        (Library dir)
AF_PATH/examples        Examples to get started. Some examples also have pre-built 
                        exectuables
AF_PATH/cmake           CMake config files for automatic configuration by external 
                        projects
AF_PATH/uninstall.exe   Uninstaller
AF_PATH/*               Other miscellenous files including licenses, logos, copyrights

The installer also appends %AF_PATH%/lib  to the User PATH  variable (see the installation instructions for further details).

Dealing with CUDA NVVM 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 the linking stage. There are a few ways to deal with this issue:

  1. Copy the DLLs to the executable 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 discussed 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)" 
echo copy "$(CUDA_PATH)\nvvm\bin\nvvm64*.dll" "$(OutDir)"

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

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 Project Templates

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.

Leave a Reply

Your email address will not be published. Required fields are marked *