<div class="header">
<div class="headertitle">
<div class="title">If you have not already done so, please make sure you have installed, configured, and tested ArrayFire following the <a class="el" href="installing.htm">installation instructions</a>.</div>
</div>
</div>
<div class="contents">
<div class="textblock">
<h2>The big picture</h2>
The ArrayFire Windows installer installs the following:
<pre class="lang:default decode:true">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</pre>
The installer also appends <span class="lang:default decode:true  crayon-inline ">%AF_PATH%/lib</span>  to the User <span class="lang:default decode:true  crayon-inline ">PATH</span>  variable (see the <a class="el" href="installing.htm">installation instructions</a> for further details).
<h3>Dealing with CUDA NMMV DLLs</h3>
The NVVM DLLs are not a part of the standard <span class="lang:default decode:true  crayon-inline ">CUDA_PATH\bin</span>  directory which is added to PATH at the time of CUDA installation. Hence it is not found automatically by the system dll loading operation. There are a few ways to deal with this:
<ol type="1">
	<li>Copy the DLLs to the exectuable location. This is the solution ArrayFire's examples use. The DLL ios copied to the executable location as a post build event. The steps for this are shown under <a href="#s3partA">Step 3 - Part A</a>.</li>
	<li>Copy <span class="lang:default decode:true  crayon-inline ">CUDA_PATH\nvvm\bin\nvvm64_30_0.dll</span>  to <span class="lang:default decode:true  crayon-inline ">CUDA_PATH\bin</span> . 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.</li>
	<li>Add <span class="lang:default decode:true  crayon-inline ">%CUDA_PATH%\nvvm\bin</span>  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.</li>
</ol>
<h2><a id="step1" class="anchor"></a>Step 1: Running pre-built executables</h2>
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:
<ul>
	<li>Helloworld (examples/helloworld)</li>
	<li>BLAS (examples/benchmarks)</li>
	<li>FFT (examples/benchmarks)</li>
	<li>Pi Estimation (examples/benchmarks)</li>
	<li>Conway (Graphics) (examples/graphics)</li>
</ul>
Note: For the CUDA executables, you will need to copy <span class="lang:default decode:true  crayon-inline ">CUDA_PATH\nvvm\bin\nvvm64_30_0.dll</span>  to the location of the executables.
<h2><a id="step2" class="anchor"></a>Step 2: Build and Run a Project</h2>
<ol type="1">
	<li>Open Visual Studio 2013. Load the HelloWorld solution which is located at <span class="lang:default decode:true  crayon-inline ">AF_PATH/examples/helloworld/helloworld.sln</span> .</li>
	<li>Build the <span class="lang:default decode:true  crayon-inline ">helloworld</span>  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.</li>
	<li>Run the <span class="lang:default decode:true  crayon-inline ">helloworld</span>  example.</li>
</ol>
<h2><a id="step3" class="anchor"></a>Step 3: Using ArrayFire with Visual Studio</h2>
This is divided into 4 parts:
<ul>
	<li><a href="#s3partA">Part A: Adding ArrayFire to an existing solution (Single Backend)</a></li>
	<li><a href="#s3partB">Part B: Adding ArrayFire CUDA to a new/existing CUDA project</a></li>
	<li><a href="#s3partC">Part C: Project with all ArrayFire backends</a></li>
	<li><a href="#s3partD">Part D: ArrayFire with CMake</a></li>
</ul>
<h3><a id="s3partA" class="anchor"></a>Part A: Adding ArrayFire to an existing solution (Single Backend)</h3>
Note: If you plan on using Native CUDA code in the project, use the steps under <a href="#s3partB">Part B</a>.

Adding a single backend to an existing project is quite simple.
<ol type="1">
	<li>Add <code>"<span class="lang:default decode:true  crayon-inline ">$(AF_PATH)/include;</span> "</code> to <em>Project Properties -&gt; C/C++ -&gt; General -&gt; Additional Include Directories</em>.</li>
	<li>Add <code>"<span class="lang:default decode:true  crayon-inline ">$(AF_PATH)/lib;</span> "</code> to <em>Project Properties -&gt; Linker -&gt; General -&gt; Additional Library Directories</em>.</li>
	<li>Add <span class="lang:default decode:true  crayon-inline ">afcpu.lib</span>  or <span class="lang:default decode:true  crayon-inline ">afcuda.lib</span>  or <span class="lang:default decode:true  crayon-inline ">afopencl.lib</span>  to <em>Project Properties -&gt; Linker -&gt; Input -&gt; Additional Dependencies</em>. based on your preferred backend.</li>
	<li>(Optional) You may choose to define <span class="lang:default decode:true  crayon-inline ">NOMINMAX, AF_&lt;CPU/CUDA/OPENCL&gt;</span>  and/or <span class="lang:default decode:true  crayon-inline ">AF_&lt;DEBUG/RELEASE&gt;</span>  in your projects. This can be added to <em>Project Properties -&gt; C/C++ -&gt; General -&gt; Preprocessor-&gt; Preprocessory definitions</em>.</li>
</ol>
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 <em>Project Properties -&gt; Build Events -&gt; Post Build Events</em> dialog and add the following lines to it.
<div class="fragment">
<pre class="lang:default decode:true">echo copy "$(CUDA_PATH)\nvvm\bin\nvvm64*.dll" "$(OutDir)" 
echo copy "$(CUDA_PATH)\nvvm\bin\nvvm64*.dll" "$(OutDir)"</pre>
<h3 class="line"> <a id="s3partB" class="anchor"></a>Part B: Adding ArrayFire CUDA to a new/existing CUDA project</h3>
</div>
Lastly, if your project contains custom CUDA code, the instructions are slightly different as it requires using a CUDA NVCC Project:
<ol type="1">
	<li>Create a custom "CUDA NVCC project" in Visual Studio</li>
	<li>Add <code>"<span class="lang:default decode:true  crayon-inline ">$(AF_PATH)/include;</span> "</code> to <em>Project Properties -&gt; CUDA C/C++ -&gt; General -&gt; Additional Include Directories</em>.</li>
	<li>Add <code>"<span class="lang:default decode:true  crayon-inline ">$(AF_PATH)/lib;</span> "</code> to <em>Project Properties -&gt; Linker -&gt; General -&gt; Additional Library Directories</em>.</li>
	<li>Add <span class="lang:default decode:true  crayon-inline ">afcpu.lib</span>  or <span class="lang:default decode:true  crayon-inline ">afcuda.lib</span>  or <span class="lang:default decode:true  crayon-inline ">afopencl.lib</span>  to <em>Project Properties -&gt; Linker -&gt; Input -&gt; Additional Dependencies</em>. based on your preferred backend.</li>
	<li>(Optional) You may choose to define <span class="lang:default decode:true  crayon-inline ">NOMINMAX, AF_CUDA</span>  and/or <span class="lang:default decode:true  crayon-inline ">AF_&lt;DEBUG/RELEASE&gt;</span>  in your projects. This can be added to <em>Project Properties -&gt; C/C++ -&gt; General -&gt; Preprocessor-&gt; Preprocessory definitions</em>.</li>
	<li>Pick a solution to handle the NVVM DLLs. We recommend the post build event method used in <a href="#s3partA">Part A</a>.</li>
</ol>
<h3><a id="s3partC" class="anchor"></a>Part C: Project with all ArrayFire backends</h3>
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 <em>HelloWorld sln/vcxproj/cpp</em> 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 <a href="https://github.com/arrayfire/arrayfire-template-projects">ArrayFire Template Projects</a>
<h3><a id="s3partD" class="anchor"></a>Part D: ArrayFire with CMake</h3>
<em>NOTE:</em> The ArrayFire installer sets up CMake file and registry so that it can be found by CMake by simply using the <span class="lang:default decode:true  crayon-inline ">Find_PACKAGE(ArrayFire)</span>  command.

If you are writing a new ArrayFire project in C/C++ from scratch, we suggest you grab a copy of our <a href="https://github.com/arrayfire/arrayfire-template-projects">CMake Project Example</a>; however, it is useful to read the documentation below in case you need to add ArrayFire to an existing project.

As <a href="#big-picture">discussed above</a>, 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 <span class="lang:default decode:true  crayon-inline ">CMakeLists.txt</span>  in your project directory:
<pre class="fragment">cd your-project-directory
touch CMakeLists.txt
</pre>
and populate it with the following code:
<pre class="fragment">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})
</pre>
where <span class="lang:default decode:true  crayon-inline ">my_executable</span>  is the name of the executable you wish to create. See the <a href="https://cmake.org/documentation/">CMake documentation</a> for more information on how to use CMake. Clearly the above code snippet precludes the use of both CUDA and OpenCL, see the <a href="https://github.com/bkloppenborg/arrayfire-cmake-example">ArrayFire CMake Example</a> for an example of how to build executables for both backends from the same CMake script.

In the above code listing, the <span class="lang:default decode:true  crayon-inline ">FIND_PACKAGE</span>  will find the ArrayFire include files, libraries, and define several variables including:
<pre class="fragment">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
</pre>
If you wish to use a specific backend, the find script also defines these variables:
<pre class="fragment">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
</pre>
Therefore, if you wish to target a specific specific backend, simply replace <span class="lang:default decode:true  crayon-inline ">${ArrayFire_LIBRARIES}</span>  with <span class="lang:default decode:true  crayon-inline ">${ArrayFire_CPU}</span> ,<span class="lang:default decode:true  crayon-inline "> ${ArrayFire_OPENCL}</span> , <span class="lang:default decode:true  crayon-inline ">${ArrayFire_CUDA}</span> , or <span class="lang:default decode:true  crayon-inline ">${ArrayFire_Unified}</span>  in the <span class="lang:default decode:true  crayon-inline ">TARGET_LINK_LIBRARIES</span>  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.
<ul>
	<li>Under source directory, add the path to your project</li>
	<li>Under build directory, add the path to your project and append /build</li>
	<li>Click configure and choose Visual Studio 2013 Win 64 as the generator.</li>
	<li>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.</li>
</ul>
The <a href="https://github.com/bkloppenborg/arrayfire-cmake-example">ArrayFire CMake Example</a> 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.

</div>
</div>