[arrayfire] 197/248: Update CMake and Make examples.
Ghislain Vaillant
ghisvail-guest at moszumanska.debian.org
Tue Nov 17 15:54:26 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 e0dcaa6ac1a0041216066331f94023e1964a67f0
Author: Brian Kloppenborg <brian at kloppenborg.net>
Date: Mon Nov 2 17:25:13 2015 -0500
Update CMake and Make examples.
---
docs/pages/using_on_linux.md | 174 ++++++++++++++++++++++++-------------------
1 file changed, 99 insertions(+), 75 deletions(-)
diff --git a/docs/pages/using_on_linux.md b/docs/pages/using_on_linux.md
index 33bb05c..2c25fc7 100644
--- a/docs/pages/using_on_linux.md
+++ b/docs/pages/using_on_linux.md
@@ -1,23 +1,33 @@
Using ArrayFire on Linux {#using_on_linux}
=====
-
+Once you have [installed](\ref installing) ArrayFire on your system, the next thing to do is
+set up your build system. On Linux, you can create ArrayFire projects using
+almost any editor, compiler, or build system. The only requirements are
+that you include the ArrayFire header directories and link with the ArrayFire
+library you intend to use.
+
+## The big picture
+
+On Linux, we suggest you install ArrayFire to the `/usr/local` directory
+so that all of the include files and libraries are part of your standard path.
+The installer will populate files in the following sub-directories:
+
+ 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
+
+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 the preferred build system.
-
-## Pre-requisites
-
-Before you get started, make sure you have the necessary pre-requisites.
+either CMake or Makefiles with CMake being our preferred build system.
-- If you are using 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)
+## Prerequisite software
-- If you are using OpenCL, please make sure you have one of the following SDKs.
- - [AMD OpenCL SDK](http://developer.amd.com/tools-and-sdks/opencl-zone/amd-accelerated-parallel-processing-app-sdk/)
- - [Intel OpenCL SDK](https://software.intel.com/en-us/articles/download-the-latest-intel-amt-software-development-kit-sdk)
- - [NVIDIA CUDA](https://developer.nvidia.com/cuda-downloads)
-
-You will also need the following dependencies to use ArrayFire.
+To build ArrayFire projects you will need a compiler
#### Fedora, Centos and Redhat
@@ -28,73 +38,74 @@ yum install epel-release
yum update
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-Install the common dependencies
+Install build dependencies
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
yum install gcc gcc-c++ cmake make
-yum install freeimage
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-Install glfw (not required for no-gl installers)
-
-Fedora:
-
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-yum install glfw
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-For Centos and Redhat, please follow [these instructions](https://github.com/arrayfire/arrayfire/wiki/GLFW-for-ArrayFire)
-
#### Debian and Ubuntu
Install common dependencies
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
apt-get install build-essential cmake cmake-curses-gui
-apt-get install libfreeimage3
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-Install glfw (not required for no-gl installers)
-
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-apt-get install libglfw3
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-For Debian 7 and Ubuntu 14.04, please follow [these instructions](https://github.com/arrayfire/arrayfire/wiki/GLFW-for-ArrayFire)
+## CMake
-**Special instructions for Tegra-K1**
+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/bkloppenborg/arrayfire-cmake-example);
+however, it is useful to read the documentation below in case you need to add
+ArrayFire to an existing project.
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-sudo apt-get install libatlas3gf-base libatlas-dev libfftw3-dev liblapacke-dev
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+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).
-## CMake
+First create a file called `CMakeLists.txt` in your project directory:
-This is the suggested method of using ArrayFire on Linux.
-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.
+ cd your-project-directory
+ touch CMakeLists.txt
-To use ArrayFire, simply insert the `FIND_PACKAGE` command inside of your
-`CMakeLists.txt` file as follows:
+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})
+
+ # 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})
-The find script will automatically define several variables including:
+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:
@@ -108,32 +119,45 @@ 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.
-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:
+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:
+
+ 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