1 Using ArrayFire with Microsoft Windows and Visual Studio {#using_on_windows}
2 ============================================================================
4 If you have not already done so, please make sure you have installed,
5 configured, and tested ArrayFire following the [installation instructions](\ref
10 The ArrayFire Windows installer creates the following:
11 1. **AF_PATH** environment variable to point to the installation location. The
12 default install location is `C:\Program Files\ArrayFire\v3`
13 2. **AF_PATH/include** : Header files for ArrayFire (include directory)
14 3. **AF_PATH/lib** : All ArrayFire backends libraries, dlls and dependency dlls
16 4. **AF_PATH/examples** : Examples to get started.
17 5. **AF_PATH/cmake** : CMake config files
18 6. **AF_PATH/uninstall.exe** : Uninstaller
20 The installer will prompt the user for following three options.
21 * Do not add **%%AF_PATH%/lib** to PATH
22 * Add **%%AF_PATH%/lib** to PATH environment variable of current user
23 * Add **%%AF_PATH%/lib** to PATH environment variable for all users
25 If you chose not to modify PATH during installation please make sure to do so
26 manually so that all applications using ArrayFire libraries will be able to find
29 ## <a name="section1" />Build and Run Helloworld
31 This can be done in two ways either by using CMake build tool or using Visual
34 ### <a name="section1part1"/> Using CMake
35 1. Download and install [CMake](https://cmake.org/download/), preferrably the
37 2. Open CMake-GUI and set the field __Where is the source code__ to the root
38 directory of examples.
39 3. Set the field __Where to build the binaries__ to
40 **path_to_examples_root_dir/build** and click the `Configure` button towards
41 the lower left bottom.
42 4. CMake will prompt you asking if it has to create the `build` directory if
43 it's not already present. Click yes to create the build directory.
44 5. Before the configuration begins, CMake will show you a list(drop-down menu)
45 of available Visual Studio versions on your system to chose from. Select one
46 and check the radio button that says **Use default native compilers** and
47 click finish button in the bottom right corner.
48 6. CMake will show you errors in red text if any once configuration is finished.
49 Ideally, you wouldn't need to do anything and CMake should be able to find
50 ArrayFire automatically. Please let us know if it didn't on your machine.
51 7. Click **Generate** button to generate the Visual Studio solution files for
53 8. Click **Open Project** button that is right next to **Generate** button to
54 open the solution file.
55 9. You will see a bunch of examples segregated into three sets named after the
56 compute backends of ArrayFire: cpu, cuda & opencl if you have installed all
57 backends. Select the helloworld project from any of the installed backends
58 and mark it as startup project and hit `F5`.
59 10. Once the helloworld example builds, you will see a console window with the
60 output from helloworld program.
62 ### <a name="section1part2"/> Using Visual Studio
64 1. Open Visual Studio of your choice and create an empty C++ project.
65 2. Right click the project and add an existing source file
66 `examples/helloworld/helloworld.cpp` to this project.
67 3. Add `"$(AF_PATH)/include;"` to _Project Properties -> C/C++ -> General ->
68 Additional Include Directories_.
69 4. Add `"$(AF_PATH)/lib;"` to _Project Properties -> Linker -> General ->
70 Additional Library Directories_.
71 5. Add `afcpu.lib` or `afcuda.lib` or `afopencl.lib` to _Project Properties ->
72 Linker -> Input -> Additional Dependencies_. based on your preferred backend.
73 6. (Optional) You may choose to define `NOMINMAX`, `AF_<CPU/CUDA/OPENCL>` and/or
74 `AF_<DEBUG/RELEASE>` in your projects. This can be added to _Project
75 Properties -> C/C++ -> General -> Preprocessor-> Preprocessory definitions_.
76 7. Build and run the project. You will see a console window with the output from
79 ## <a name="section2" />Using ArrayFire within Existing Visual Studio Projects
80 This is divided into three parts:
81 * [Part A: Adding ArrayFire to an existing solution (Single
82 Backend)](#section3partA)
83 * [Part B: Adding ArrayFire CUDA to a new/existing CUDA project](#section3partB)
84 * [Part C: Project with all ArrayFire backends](#section3partC)
86 ### <a name="section3partA" />Part A: Adding ArrayFire to an existing solution (Single Backend)
87 Note: If you plan on using Native CUDA code in the project, use the steps under
88 [Part B](#section3partB).
90 Adding a single backend to an existing project is quite simple.
92 1. Add `"$(AF_PATH)/include;"` to _Project Properties -> C/C++ -> General ->
93 Additional Include Directories_.
94 2. Add `"$(AF_PATH)/lib;"` to _Project Properties -> Linker -> General ->
95 Additional Library Directories_.
96 3. Add `afcpu.lib`, `afcuda.lib`, `afopencl.lib`, or `af.lib` to _Project
97 Properties -> Linker -> Input -> Additional Dependencies_. based on your
100 ### <a name="section3partB" />Part B: Adding ArrayFire CUDA to a new/existing CUDA project
101 Lastly, if your project contains custom CUDA code, the instructions are slightly
102 different as it requires using a CUDA NVCC Project:
104 1. Create a custom "CUDA NVCC project" in Visual Studio
105 2. Add `"$(AF_PATH)/include;"` to _Project Properties -> CUDA C/C++ -> General
106 -> Additional Include Directories_.
107 3. Add `"$(AF_PATH)/lib;"` to _Project Properties -> Linker -> General ->
108 Additional Library Directories_.
109 4. Add `afcpu.lib`, `afcuda.lib`, `afopencl.lib`, or `af.lib` to _Project Properties ->
110 Linker -> Input -> Additional Dependencies_. based on your preferred backend.
112 ### <a name="section3partC" />Part C: Project with all ArrayFire backends
113 If you wish to create a project that allows you to use all the ArrayFire
114 backends with ease, you should use `af.lib` in step 3 from [Part
117 You can alternately download the template project from [ArrayFire Template
118 Projects](https://github.com/arrayfire/arrayfire-project-templates)
120 ## <a name="section4" />Using ArrayFire with CMake
121 ArrayFire ships with a series of CMake scripts to make finding and using our
124 First create a file called `CMakeLists.txt` in your project directory:
126 cd your-project-directory
129 and populate it with the following code:
131 find_package(ArrayFire)
132 add_executable(<my_executable> [list your source files here])
134 # To use Unified backend, do the following.
135 # Unified backend lets you choose the backend at runtime
136 target_link_libraries(<my_executable> ArrayFire::af)
138 where `<my_executable>` is the name of the executable you wish to create. See the
139 [CMake documentation](https://cmake.org/documentation/) for more information on
140 how to use CMake. To link with a specific backend directly, replace the
141 `ArrayFire::af` with the following for their respective backends.
143 * `ArrayFire::afcpu` for CPU backend.
144 * `ArrayFire::afcuda` for CUDA backend.
145 * `ArrayFire::afopencl` for OpenCL backend.
147 Next we need to instruct CMake to create build instructions and then compile. We
148 suggest using CMake's out-of-source build functionality to keep your build and
149 source files cleanly separated. To do this open the CMake GUI.
151 * Under source directory, add the path to your project
152 * Under build directory, add the path to your project and append /build
153 * Click configure and choose a 64 bit Visual Studio generator.
154 * If configuration was successful, click generate. This will create a
155 my-project.sln file under build. Click `Open Project` in CMake-GUI to open the
156 solution and compile the ALL_BUILD project.