/build/arrayfire/src/arrayfire-full-3.6.1/docs/pages/using_on_windows.md
Go to the documentation of this file.
1 Using ArrayFire with Microsoft Windows and Visual Studio {#using_on_windows}
2 ============================================================================
3 
4 If you have not already done so, please make sure you have installed,
5 configured, and tested ArrayFire following the [installation instructions](\ref
6 installing).
7 
8 ## The big picture
9 
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
15  (library directory)
16 4. **AF_PATH/examples** : Examples to get started.
17 5. **AF_PATH/cmake** : CMake config files
18 6. **AF_PATH/uninstall.exe** : Uninstaller
19 
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
24 
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
27 the required DLLs.
28 
29 ## <a name="section1" />Build and Run Helloworld
30 
31 This can be done in two ways either by using CMake build tool or using Visual
32 Studio directly.
33 
34 ### <a name="section1part1"/> Using CMake
35 1. Download and install [CMake](https://cmake.org/download/), preferrably the
36  latest version.
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
52  the examples.
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.
61 
62 ### <a name="section1part2"/> Using Visual Studio
63 
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
77  helloworld program.
78 
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)
85 
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).
89 
90 Adding a single backend to an existing project is quite simple.
91 
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
98  preferred backend.
99 
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:
103 
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.
111 
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
115 A](#section3partA).
116 
117 You can alternately download the template project from [ArrayFire Template
118 Projects](https://github.com/arrayfire/arrayfire-project-templates)
119 
120 ## <a name="section4" />Using ArrayFire with CMake
121 ArrayFire ships with a series of CMake scripts to make finding and using our
122 library easy.
123 
124 First create a file called `CMakeLists.txt` in your project directory:
125 
126  cd your-project-directory
127  touch CMakeLists.txt
128 
129 and populate it with the following code:
130 
131  find_package(ArrayFire)
132  add_executable(<my_executable> [list your source files here])
133 
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)
137 
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.
142 
143 * `ArrayFire::afcpu` for CPU backend.
144 * `ArrayFire::afcuda` for CUDA backend.
145 * `ArrayFire::afopencl` for OpenCL backend.
146 
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.
150 
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.