/build/arrayfire/src/arrayfire-full-3.6.1/docs/pages/using_on_osx.md
Go to the documentation of this file.
1 Using ArrayFire on OSX {#using_on_osx}
2 ======================================
3 
4 Once you have [installed](\ref installing) ArrayFire on your system, the next
5 thing to do is set up your build system. On OSX, you may create ArrayFire
6 project using almost any editor, compiler, or build system. The only requirement
7 is that you can include the ArrayFire header directory, and link with the
8 ArrayFire library you intend to use.
9 
10 ## <a name="big-picture"/> The big picture
11 
12 By default, the ArrayFire OSX installer will place several files in your
13 computer's `/opt/arrayfire` directory. The installer will populate this
14 directory with files in the following sub-directories:
15 
16  include/arrayfire.h - Primary ArrayFire include file
17  include/af/*.h - Additional include files
18  lib/libaf* - CPU, CUDA, and OpenCL libraries (.a, .so)
19  lib/libforge* - Visualization library
20  lib/libcu* - CUDA backend dependencies
21  lib/libglbinding* - OpenGL graphics dependencies
22  share/ArrayFire/cmake/* - CMake config scripts
23  share/ArrayFire/examples/* - ArrayFire examples
24 
25 Because ArrayFire follows standard installation practices, you can use basically
26 any build system to create and compile projects that use ArrayFire. Among the
27 many possible build systems on Linux we suggest using ArrayFire with either
28 CMake or Makefiles with CMake being our preferred build system.
29 
30 ## Build Instructions:
31 * [CMake](#CMake)
32 * [Makefiles](#Makefiles)
33 
34 ## <a name="CMake"></a>CMake
35 
36 The CMake build system can be used to create ArrayFire projects. As [discussed
37 above](#big-picture), ArrayFire ships with a series of CMake scripts to make
38 finding and using our library easy.
39 
40 First create a file called `CMakeLists.txt` in your project directory:
41 
42  cd your-project-directory
43  touch CMakeLists.txt
44 
45 and populate it with the following code:
46 
47  find_package(ArrayFire)
48  add_executable(<my_executable> [list your source files here])
49 
50  # To use Unified backend, do the following.
51  # Unified backend lets you choose the backend at runtime
52  target_link_libraries(<my_executable> ArrayFire::af)
53 
54 where `my_executable` is the name of the executable you wish to create. See the
55 [CMake documentation](https://cmake.org/documentation/) for more information on
56 how to use CMake. To link with a specific backend directly, replace the
57 `ArrayFire::af` with the following for their respective backends.
58 
59 * `ArrayFire::afcpu` for CPU backend.
60 * `ArrayFire::afcuda` for CUDA backend.
61 * `ArrayFire::afopencl` for OpenCL backend.
62 
63 Next we need to instruct CMake to create build instructions and then compile. We
64 suggest using CMake's out-of-source build functionality to keep your build and
65 source files cleanly separated. To do this open the CMake GUI.
66 
67  cd your-project-directory
68  mkdir build
69  cd build
70  cmake ..
71  make
72 
73 *NOTE:* If you have installed ArrayFire to a non-standard location, CMake can
74 still help you out. When you execute CMake specify the path to ArrayFire
75 installation root as `ArrayFire_DIR` variable.
76 
77 For example, if ArrayFire were installed locally to `/home/user/ArrayFire` then
78 you would modify the `cmake` command above to contain the following definition:
79 
80  cmake -DArrayFire_DIR=/home/user/ArrayFire ..
81 
82 You can also specify this information in the `ccmake` command-line interface.
83 
84 ## <a name="Makefiles"></a> Makefiles
85 
86 Building ArrayFire projects with Makefiles is fairly similar to CMake except you
87 must specify all paths and libraries manually.
88 
89 As with any make project, you need to specify the include path to the directory
90 containing `arrayfire.h` file. This should be `-I /opt/arrayfire/include` if you
91 followed our installation instructions.
92 
93 Similarly, you will need to specify the path to the ArrayFire library using the
94 `-L` option (e.g. `-L/opt/arrayfire/lib`) followed by the specific ArrayFire
95 library you wish to use using the `-l` option (for example `-lafcpu`,
96 `-lafopencl`, `-lafcuda`, or `-laf` for the CPU, OpenCL, CUDA, and unified
97 backends respectively.
98 
99 Here is a minimal example Makefile which uses ArrayFire's CPU backend:
100 
101  LIBS=-lafcpu
102  LIB_PATHS=-L/opt/arrayfire/lib
103  INCLUDES=-I/opt/arrayfire/include
104  CC=g++ $(COMPILER_OPTIONS)
105  COMPILER_OPTIONS=-std=c++11 -g
106 
107  all: main.cpp Makefile
108  $(CC) main.cpp -o test $(INCLUDES) $(LIBS) $(LIB_PATHS)