$darkmode
A high-performance general-purpose compute library
/home/abuild/rpmbuild/BUILD/arrayfire-full-v3.9.0/docs/pages/using_on_linux.md
Go to the documentation of this file.
1 Using ArrayFire on Linux {#using_on_linux}
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 Linux, you can create ArrayFire
6 projects using almost any editor, compiler, or build system. The only
7 requirements are that you include the ArrayFire header directories and link with
8 the ArrayFire library you intend to use i.e. CUDA, OpenCL, CPU, or Unified
9 backends.
10 
11 ## The big picture {#big-picture-linux}
12 
13 On Linux, we recommend installing ArrayFire to `/opt/arrayfire` directory. The
14 installer will populate 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, oneAPI and OpenCL libraries (.a, .so)
19  lib/libforge* - Visualization library
20  lib/libcu* - CUDA backend dependencies
21  lib/libOpenCL.so - OpenCL ICD Loader library
22  share/ArrayFire/cmake/* - CMake config (find) scripts
23  share/ArrayFire/examples/* - All 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 ## Prerequisite software
31 
32 To build ArrayFire projects you will need a compiler
33 
34 #### Fedora, Centos and Redhat
35 
36 Install EPEL repo (not required for Fedora)
37 
38 ```
39 yum install epel-release
40 yum update
41 ```
42 
43 Install build dependencies
44 
45 ```
46 yum install gcc gcc-c++ cmake3 make
47 ```
48 
49 #### Debian and its derivatives
50 
51 Install common dependencies
52 
53 ```
54 apt install build-essential cmake cmake-curses-gui
55 ```
56 
57 ## CMake
58 
59 We recommend that the CMake build system be used to create ArrayFire projects.
60 As [discussed above](#big-picture-linux), ArrayFire ships with a series of CMake
61 scripts to make finding and using our library easy.
62 
63 First create a file called `CMakeLists.txt` in your project directory:
64 
65  cd your-project-directory
66  touch CMakeLists.txt
67 
68 and populate it with the following code:
69 
70  find_package(ArrayFire)
71  add_executable(<my_executable> [list your source files here])
72 
73  # To use Unified backend, do the following.
74  # Unified backend lets you choose the backend at runtime
75  target_link_libraries(<my_executable> ArrayFire::af)
76 
77 where `my_executable` is the name of the executable you wish to create. See the
78 [CMake documentation](https://cmake.org/documentation/) for more information on
79 how to use CMake. To link with a specific backend directly, replace the
80 `ArrayFire::af` with the following for their respective backends.
81 
82 * `ArrayFire::afcpu` for CPU backend.
83 * `ArrayFire::afcuda` for CUDA backend.
84 * `ArrayFire::afoneapi` for oneAPI backend.
85 * `ArrayFire::afopencl` for OpenCL backend.
86 
87 Next we need to instruct CMake to create build instructions and then compile. We
88 suggest using CMake's out-of-source build functionality to keep your build and
89 source files cleanly separated. To do this open the CMake GUI.
90 
91  cd your-project-directory
92  mkdir build
93  cd build
94  cmake ..
95  make
96 
97 *NOTE:* If you have installed ArrayFire to a non-standard location, CMake can
98 still help you out. When you execute CMake specify the path to ArrayFire
99 installation root as `ArrayFire_DIR` variable.
100 
101 For example, if ArrayFire were installed locally to `/home/user/ArrayFire` then
102 you would modify the `cmake` command above to contain the following definition:
103 
104  cmake -DArrayFire_DIR=/home/user/ArrayFire ..
105 
106 You can also specify this information in the `ccmake` command-line interface.
107 
108 ## Makefiles
109 
110 Building ArrayFire projects with Makefiles is fairly similar to CMake except you
111 must specify all paths and libraries manually.
112 
113 As with any `make` project, you need to specify the include path to the
114 directory containing `arrayfire.h` file. This should be `-I
115 /opt/arrayfire/include` if you followed our installation instructions.
116 
117 Similarly, you will need to specify the path to the ArrayFire library using the
118 `-L` option (e.g. `-L/opt/arrayfire/lib`) followed by the specific ArrayFire
119 library you wish to use using the `-l` option (for example `-lafcpu`,
120 `-lafopencl`, `-lafoneapi`, `-lafcuda`, or `-laf` for the CPU, OpenCL, oneAPI
121 and CUDA, and unified backends, respectively.
122 
123 Here is a minimal example Makefile which uses ArrayFire's CPU backend:
124 
125  LIBS=-lafcpu
126  LIB_PATHS=-L/opt/arrayfire/lib
127  INCLUDES=-I/opt/arrayfire/include
128  CC=g++ $(COMPILER_OPTIONS)
129  COMPILER_OPTIONS=-std=c++11 -g
130 
131  all: main.cpp Makefile
132  $(CC) main.cpp -o test $(INCLUDES) $(LIBS) $(LIB_PATHS)