<div class="header">
<div class="headertitle">
<div class="title">Continuing our blog series "<a href="http://sandbox.arrayfire.com/tag/learning-arrayfire-from-scratch/">Learning ArrayFire from scratch</a>" today we will discuss how to set up an ArrayFire project on OSX using XCode, CMake, or Makefiles.</div>
</div>
</div>
<!--more-->

Once you have <a class="el" href="installing.htm">installed</a> ArrayFire on your system, the next thing to do is set up your build system. On OSX, you may create ArrayFire project using almost any editor, compiler, or build system. The only requirement is that you can include the ArrayFire header directory, and link with the ArrayFire library you intend to use.
<h3>The big picture</h3>
By default, the ArrayFire OSX installer will place several files in your computer's <span class="lang:default decode:true  crayon-inline ">/usr/local</span>  directory. The installer will populate this directory with files in the following sub-directories:
<pre class="fragment">include/arrayfire.h         - Primary ArrayFire include file
include/af/*.h              - Additional include files
lib/libaf*                  - CPU, CUDA, and OpenCL libraries (.a, .so)
lib/libforge*               - Visualization library
share/ArrayFire/cmake/*     - CMake config (find) scripts
share/ArrayFire/examples/*  - All ArrayFire examples
</pre>
Because ArrayFire follows standard installation practices, you can use basically any build system to create and compile projects that use ArrayFire. Among the many possible build systems on Linux we suggest using ArrayFire with either CMake or Makefiles with CMake being our preferred build system.
<h3>XCode</h3>
Although we recommend using CMake to build ArrayFire projects on OSX, you can use XCode if this is your preferred development platform. To set up a basic C/C++ project in XCode do the following:
<ol type="1">
	<li>Start up XCode. Choose OSX -&gt; Application, Command Line Tool for the project:
<div class="image"><a href="http://sandbox.arrayfire.com/wp-content/uploads/2015/11/xcode-startup.png"><img class="alignnone wp-image-8596" src="http://sandbox.arrayfire.com/wp-content/uploads/2015/11/xcode-startup.png" alt="xcode-startup" width="650" height="387" /></a></div></li>
	<li>Fill in the details for your project and choose either C or C++ for the project:
<div class="image"><a href="http://sandbox.arrayfire.com/wp-content/uploads/2015/11/project-options.png"><img class="alignnone wp-image-8597" src="http://sandbox.arrayfire.com/wp-content/uploads/2015/11/project-options.png" alt="project-options" width="650" height="393" /></a></div></li>
	<li>Next we need to configure the build settings. In the left-hand pane, click on the project. In the center pane, click on "Build Settings" followed by the "All" button:
<div class="image"><a href="http://sandbox.arrayfire.com/wp-content/uploads/2015/11/build-settings1.png"><img class="alignnone wp-image-8600" src="http://sandbox.arrayfire.com/wp-content/uploads/2015/11/build-settings1.png" alt="build-settings" width="900" height="602" /></a></div></li>
	<li>Now search for "Header Search Paths" and add <span class="lang:default decode:true  crayon-inline ">/usr/local/include</span>  to the list:
<div class="image"><a href="http://sandbox.arrayfire.com/wp-content/uploads/2015/11/header-search-paths.png"><img class="alignnone wp-image-8601" src="http://sandbox.arrayfire.com/wp-content/uploads/2015/11/header-search-paths.png" alt="header-search-paths" width="650" height="279" /></a></div></li>
	<li>Then search for "Library Search Paths" and add <span class="lang:default decode:true  crayon-inline ">/usr/local/lib</span>  to the list:
<div class="image"><a href="http://sandbox.arrayfire.com/wp-content/uploads/2015/11/library-search-paths.png"><img class="alignnone wp-image-8602" src="http://sandbox.arrayfire.com/wp-content/uploads/2015/11/library-search-paths.png" alt="library-search-paths" width="650" height="285" /></a></div></li>
	<li>Next, we need to make sure the executable is linked with an ArrayFire library: To do this, click the "Build Phases" tab and expand the "Link with Binary Library" menu:
<div class="image"><a href="http://sandbox.arrayfire.com/wp-content/uploads/2015/11/build-phases.png"><img class="alignnone wp-image-8603" src="http://sandbox.arrayfire.com/wp-content/uploads/2015/11/build-phases.png" alt="build-phases" width="900" height="269" /></a></div></li>
	<li>In the search dialog that pops up, choose the "Add Other" button from the lower right. Specify the<span class="lang:default decode:true  crayon-inline ">/usr/local/lib</span>  folder:
<div class="image"><a href="http://sandbox.arrayfire.com/wp-content/uploads/2015/11/library-folder-path.png"><img class="alignnone wp-image-8599" src="http://sandbox.arrayfire.com/wp-content/uploads/2015/11/library-folder-path.png" alt="library-folder-path" width="650" height="567" /></a></div></li>
	<li>Next, select the ArrayFire library with which you wish to link your program. Your options will be:</li>
</ol>
<div class="fragment">
<div class="line">
<pre class="lang:default decode:true ">libafcuda.*.dylib   - CUDA backend
libafopencl.*.dylib - OpenCL backend
libafcpu.*.dylib    - CPU backend
libaf.*.dylib       - Unified backend</pre>
In the picture below, we have elected to link with the OpenCL backend:

<a href="http://sandbox.arrayfire.com/wp-content/uploads/2015/11/pick-arrayfire-library.png"><img class="alignnone wp-image-8598" src="http://sandbox.arrayfire.com/wp-content/uploads/2015/11/pick-arrayfire-library.png" alt="pick-arrayfire-library" width="650" height="566" /></a>

</div>
</div>
9. Lastly, lets test ArrayFire's functionality. In the left hand pane open the main.cpp` file and insert the following code:
<div class="image"></div>
<div class="fragment">
<div class="line">
<pre class="lang:default decode:true "> // Include the ArrayFire header file
#include &lt;arrayfire.h&gt;
 
int main(int argc, const char * argv[]) {
   // Gather some information about the ArrayFire device
   af::info();
   return 0;
}</pre>
&nbsp;

</div>
</div>
Finally, click the build button and you should see some information about your graphics card in the lower-section of your screen:
<div class="image"><a href="http://sandbox.arrayfire.com/wp-content/uploads/2015/11/afinfo-result.png"><img class="alignnone size-medium wp-image-8594" src="http://sandbox.arrayfire.com/wp-content/uploads/2015/11/afinfo-result-300x85.png" alt="afinfo-result" width="300" height="85" /></a></div>
<h3>CMake</h3>
We recommend that the CMake build system be used to create ArrayFire projects. 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-project-templates">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 <code>${ArrayFire_Unified}</code> in the<span class="lang:default decode:true  crayon-inline ">TARGET_LINK_LIBRARIES</span>  command above. If you intend on building your software to link with all of these backends, please see the <a href="https://github.com/arrayfire/arrayfire-project-templates">CMake Project Example</a> which makes use of some fairly fun CMake tricks to avoid re-compiling code whenever possible.

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:
<pre class="fragment">cd your-project-directory
mkdir build
cd build
cmake ..
make
</pre>
<em>NOTE:</em> If you have installed ArrayFire to a non-standard location, CMake can still help you out. When you execute CMake specify the path to the <span class="lang:default decode:true  crayon-inline ">ArrayFireConfig*</span>  files that are found in the <span class="lang:default decode:true  crayon-inline ">share/ArrayFire/cmake</span>  subdirectory of the installation folder. For example, if ArrayFire were installed locally to <span class="lang:default decode:true  crayon-inline ">/opt/ArrayFire</span>  then you would modify the <span class="lang:default decode:true  crayon-inline ">cmake</span> command above to contain the following definition:
<pre class="fragment">cmake -DArrayFire_DIR=/opt/ArrayFire/share/ArrayFire/cmake ..
</pre>
You can also specify this information in the ccmake command-line interface.
<h3>MakeFiles</h3>
Building ArrayFire projects with Makefiles is fairly similar to CMake except you must specify all paths and libraries manually. As with any make project, you need to specify the include path to the directory containing <code><a class="el" href="arrayfire_8h.htm">arrayfire.h</a></code> file. This should be <span class="lang:default decode:true  crayon-inline ">-I /usr/local/include</span>  if you followed our installation instructions. Similarly, you will need to specify the path to the ArrayFire library using the <span class="lang:default decode:true  crayon-inline ">-L</span>  option (e.g. <span class="lang:default decode:true  crayon-inline ">-L/usr/local/lib</span> ) followed by the specific ArrayFire library you wish to use using the <code>-l</code> option (for example <span class="lang:default decode:true  crayon-inline ">-lafcpu</span> , <span class="lang:default decode:true  crayon-inline ">-lafopencl</span> , <span class="lang:default decode:true  crayon-inline ">-lafcuda</span> , or <span class="lang:default decode:true  crayon-inline ">-laf</span>  for the CPU, OpenCL, CUDA, and unified backends respectively.

Here is a minimial example MakeFile which uses ArrayFire's CPU backend:
<pre class="fragment">LIBS=-lafcpu
LIB_PATHS=-L/usr/lib
INCLUDES=-I/usr/include
CC=g++ $(COMPILER_OPTIONS)
COMPILER_OPTIONS=-std=c++11 -g

all: main.cpp Makefile
    $(CC) main.cpp -o test $(INCLUDES) $(LIBS) $(LIB_PATHS)</pre>