[arrayfire] 214/248: Add XCode instructions, assets.
Ghislain Vaillant
ghisvail-guest at moszumanska.debian.org
Tue Nov 17 15:54:28 UTC 2015
This is an automated email from the git hooks/post-receive script.
ghisvail-guest pushed a commit to branch dfsg-clean
in repository arrayfire.
commit ba5ca793cd4fe210e8306686a995edcc526c82e8
Author: Brian Kloppenborg <brian at kloppenborg.net>
Date: Fri Nov 6 16:37:48 2015 -0500
Add XCode instructions, assets.
---
assets | 2 +-
docs/pages/using_on_osx.md | 209 +++++++++++++++++++++++++++++++++++----------
2 files changed, 166 insertions(+), 45 deletions(-)
diff --git a/assets b/assets
index d5b0b7c..7c2a127 160000
--- a/assets
+++ b/assets
@@ -1 +1 @@
-Subproject commit d5b0b7cd5d44299458696571df7fb1aa7d99701e
+Subproject commit 7c2a12739ac0f5830d26334731e9ac96ba01e2d7
diff --git a/docs/pages/using_on_osx.md b/docs/pages/using_on_osx.md
index d8025dc..5e437c0 100644
--- a/docs/pages/using_on_osx.md
+++ b/docs/pages/using_on_osx.md
@@ -1,48 +1,151 @@
Using ArrayFire on OSX {#using_on_osx}
=====
+Once you have [installed](\ref installing) 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.
-Among the many possible build systems on OSX we suggest using ArrayFire with
-either CMake or Makefiles.
+## The big picture
-## Pre-requisites
+By default, the ArrayFire OSX installer will place several files in your
+computer's `/usr/local` directory.
+The installer will populate this directory with files in the following
+sub-directories:
-Before you get started, make sure you have the necessary pre-requisites.
+ 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
-- If you want to use ArrayFire with CUDA, please make sure you have [CUDA 7](https://developer.nvidia.com/cuda-downloads) installed on your system.
- - [Contact us](support at arrayfire.com) for custom builds (eg. different toolkits)
+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.
-- Install the latest Xcode from the App Store
+## XCode
-- Install [brew](http://brew.sh/)
+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:
+
+1. Start up XCode. Choose OSX -> Application, Command Line Tool for the project:
+<img src="xcode-setup/xcode-startup.png" alt="Create a command line too XCode Project" width="100%" />
+
+2. Fill in the details for your project and choose either C or C++ for the project:
+<img src="xcode-setup/project-options.png" alt="Create a C/C++ project" width="100%" />
+
+3. 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:
+<img src="xcode-setup/build-settings.png" alt="Configure build settings" width="100%" />
+
+4. Now search for "Header Search Paths" and add `/usr/local/include` to the list:
+<img src="xcode-setup/header-search-paths.png" alt="Configure build settings" width="100%" />
+
+5. Then search for "Library Search Paths" and add `/usr/local/lib` to the list:
+<img src="xcode-setup/library-search-paths.png" alt="Configure build settings" width="100%" />
+
+6. 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:
+<img src="xcode-setup/build-phases.png" alt="Configure build settings" width="100%" />
+
+7. In the search dialog that pops up, choose the "Add Other" button from the
+ lower right. Specify the `/usr/local/lib` folder:
+<img src="xcode-setup/library-folder-path.png" alt="Configure build settings" width="100%" />
+
+8. Lastly, select the ArrayFire library with which you wish to link your program.
+ Your options will be:
+
+~~~~~
+libafcuda.*.dylib - CUDA backend
+libafopencl.*.dylib - OpenCL backend
+libafcpu.*.dylib - CPU backend
+libaf.*.dylib - Unified backend
+~~~~~
+
+In the picture below, we have elected to link with the OpenCL backend:
+
+<img src="xcode-setup/pick-arrayfire-library.png" alt="Configure build settings" width="100%" />
+
+9. Lastly, lets test ArrayFire's functionality. In the left hand pane open
+ the main.cpp` file and insert the following code:
+
+~~~~~
+// Include the ArrayFire header file
+#include <arrayfire.h>
+
+int main(int argc, const char * argv[]) {
+ // Gather some information about the ArrayFire device
+ af::info();
+ return 0;
+}
+~~~~~
+
+Finally, click the build button and you should see some information about your
+graphics card in the lower-section of your screen:
+
+<img src="xcode-setup/afinfo-result.png" alt="Configure build settings" width="100%" />
## CMake
-This is the suggested method of using ArrayFire on OSX.
-ArrayFire ships with support for CMake by default, including a series of
-`Find` scripts installed in the `/usr/local/share/ArrayFire/cmake` (or similar)
-directory.
-These scripts will automatically find the CUDA, OpenCL, and CPU versions
-of ArrayFire and automatically choose the most powerful installed backend
-(typically CUDA).
-Following version 3.2, the scripts will also check for the Unified backend of
-ArrayFire.
+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
+[CMake Project Example](https://github.com/arrayfire/arrayfire-project-templates);
+however, it is useful to read the documentation below in case you need to add
+ArrayFire to an existing project.
+
+As [discussed above](#big-picture), 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).
-To use ArrayFire, simply insert the `FIND_PACKAGE` command inside of your
-`CMakeLists.txt` file as follows:
+First create a file called `CMakeLists.txt` in your project directory:
+
+ cd your-project-directory
+ touch CMakeLists.txt
+
+and populate it with the following code:
FIND_PACKAGE(ArrayFire)
INCLUDE_DIRECTORIES(${ArrayFire_INCLUDE_DIRS})
- ...
- ADD_EXECUTABLE(some_executable ...)
- TARGET_LINK_LIBRARIES(some_executable ${ArrayFire_LIBRARIES} )
+ ... [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})
-The find script will automatically define several variables including:
+ # 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})
+
+where `my_executable` is the name of the executable you wish to create.
+See the [CMake documentation](https://cmake.org/documentation/) for more
+information on how to use CMake.
+Clearly the above code snippet precludes the use of both CUDA and OpenCL, see
+the
+[ArrayFire CMake Example](https://github.com/bkloppenborg/arrayfire-cmake-example)
+for an example of how to build executables for both backends from the same
+CMake script.
+
+In the above code listing, the `FIND_PACKAGE` will find the ArrayFire include
+files, libraries, and define several variables including:
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
+ 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
If you wish to use a specific backend, the find script also defines these variables:
@@ -56,32 +159,50 @@ If you wish to use a specific backend, the find script also defines these variab
ArrayFire_Unified_FOUND - True of the ArrayFire Unified library has been found.
ArrayFire_Unified_LIBRARIES - Location of ArrayFire's Unified library, if found
-Therefore, if you wish to target a specific specific backend, switch
-`${ArrayFire_LIBRARIES}` to `${ArrayFire_CPU}` `${ArrayFire_OPENCL}`
-`${ArrayFire_CUDA}` or `${ArrayFire_Unified}` in the `TARGET_LINK_LIBRARIES`
+Therefore, if you wish to target a specific specific backend, simply replace
+`${ArrayFire_LIBRARIES}` with `${ArrayFire_CPU}`, `${ArrayFire_OPENCL}`,
+`${ArrayFire_CUDA}`, or `${ArrayFire_Unified}` in the `TARGET_LINK_LIBRARIES`
command above.
+If you intend on building your software to link with all of these backends,
+please see the
+[CMake Project Example](https://github.com/arrayfire/arrayfire-project-templates)
+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:
+
+ cd your-project-directory
+ mkdir build
+ cd build
+ cmake ..
+ make
+
+*NOTE:* 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
+`ArrayFireConfig*` files that are found in the `share/ArrayFire/cmake`
+subdirectory of the installation folder.
+For example, if ArrayFire were installed locally to `/opt/ArrayFire` then you
+would modify the `cmake` command above to contain the following definition:
-Finally, 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 `ArrayFireConfig*` files that
-are found in the `share/ArrayFire/cmake` subdirectory of the installation folder.
-For example, if ArrayFire were installed locally to `/opt/ArrayFire` then you would
-modify the `cmake` command above to contain the following definition:
+ cmake -DArrayFire_DIR=/opt/ArrayFire/share/ArrayFire/cmake ..
-```
-cmake -DArrayFire_DIR=/opt/ArrayFire/share/ArrayFire/cmake ...
-```
+You can also specify this information in the ccmake command-line interface.
## MakeFiles
-Using ArrayFire with Makefiles is almost as easy as CMake, but you will
-need to specify paths manually. In your makefile specify the include path to
-the directory containing `arrayfire.h`. Typically this will be `-I /usr/include`
-or `-I /usr/local/include` if you installed ArrayFire using our installation
+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 `arrayfire.h` file.
+This should be `-I /usr/local/include` if you followed our installation
instructions.
-Then, in your linker line specify the path to ArrayFire using the `-L` option
-(typically `-L/usr/lib` or `-L/usr/local/lib` and the specific ArrayFire backend
-you wish to use with the `-l` option (i.e. `-lafcpu`, `-lafopencl` or `-lafcuda`
-`-laf` for the CPU, OpenCL, CUDA and Unified backends repsectively).
+Similarly, you will need to specify the path to the ArrayFire library using
+the `-L` option (e.g. `-L/usr/local/lib`) followed by the specific ArrayFire
+library you wish to use using the `-l` option (for example `-lafcpu`,
+`-lafopencl`, `-lafcuda`, or `-laf` for the CPU, OpenCL, CUDA, and unified
+backends respectively.
Here is a minimial example MakeFile which uses ArrayFire's CPU backend:
--
Alioth's /usr/local/bin/git-commit-notice on /srv/git.debian.org/git/debian-science/packages/arrayfire.git
More information about the debian-science-commits
mailing list