[arrayfire] 200/248: More documentation updates for tutorials
Ghislain Vaillant
ghisvail-guest at moszumanska.debian.org
Tue Nov 17 15:54:27 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 69b9acebb9ff69940c7bc68bde1f6d8f1271124e
Author: Shehzan Mohammed <shehzan at arrayfire.com>
Date: Wed Nov 4 17:25:57 2015 -0500
More documentation updates for tutorials
---
docs/pages/INSTALL.md | 12 +-
docs/pages/using_on_windows.md | 261 ++++++++++++++++++++++++++++++++---------
2 files changed, 211 insertions(+), 62 deletions(-)
diff --git a/docs/pages/INSTALL.md b/docs/pages/INSTALL.md
index a2f8f0e..7b2c73e 100644
--- a/docs/pages/INSTALL.md
+++ b/docs/pages/INSTALL.md
@@ -112,10 +112,6 @@ If you are using Ubuntu 14.04, you will need to install GLFW3 from source follow
[instructions listed here](https://github.com/arrayfire/arrayfire/wiki/Build-Instructions-for-Linux#general-dependencies).
After this point, the installation should proceed identically to Ubuntu 14.10 or newer.
-If you are using ArrayFire on the Tegra-K1 also install these packages:
-
- sudo apt-get install libatlas3gf-base libatlas-dev libfftw3-dev liblapacke-dev
-
If your system has a CUDA GPU, we suggest downloading the latest drivers
from NVIDIA in the form of a Debian package and installing using the
package manager. At present, CUDA downloads can be found on the
@@ -128,6 +124,14 @@ with any drivers required for your hardware.
# Enable GPU support (OpenCL):
apt-get install ocl-icd-libopencl1
+### Special instructions for Tegra K1
+If you are using ArrayFire on the Tegra K1 also install these packages:
+
+ sudo apt-get install libatlas3gf-base libatlas-dev libfftw3-dev liblapacke-dev
+
+In addition to these packages, you will need to compile GLFW3 from source
+using the instructions above.
+
Finally, [download](http://arrayfire.com/download/) ArrayFire. After you have
the file, run the installer using:
diff --git a/docs/pages/using_on_windows.md b/docs/pages/using_on_windows.md
index e36fd22..617dc44 100644
--- a/docs/pages/using_on_windows.md
+++ b/docs/pages/using_on_windows.md
@@ -1,79 +1,224 @@
Using ArrayFire with Microsoft Windows and Visual Studio {#using_on_windows}
=====
-## Pre-requisites
-
If you have not already done so, please make sure you have installed,
configured, and tested ArrayFire following the
[installation instructions](\ref installing).
-## Testing the installation
-
-### Step 1: Running pre-built executables
-
-The ArrayFire installer ships with a few pre-built executables with the examples.
-These should run out of the box.
-
-Note: For the CUDA executables, you will need to copy CUDA_PATH\nvvm\bin\nvvm64_30_0.dll
-to the location of the executables.
-
-### Step 2: Verify the path addition functions correctly
-
-1. Open Visual Studio 2013. Open the HelloWorld solution which is located at
- `AF_PATH/examples/helloworld/helloworld.sln`.
-2. Build and run the `helloworld` example. Be sure to, select the
- platform/configuration of your choice using the platform drop-down
- (the options are CPU, CUDA, OpenCL, and Unified) and Solution Configuration
- drop down (options of Release and Debug) menus.
-3. Run the `helloworld` example
-
-## Creating your own Visual Studio Project
-
-### A new project from scratch
+## The big picture
+The ArrayFire Windows installer creates the following:
+1. `AF_PATH` environment variable to point to the installation location. The
+ default install location is C:\Program Files\ArrayFire\v3
+2. `AF_PATH/include` : Header files for ArrayFire (include directory)
+3. `AF_PATH/lib` : All ArrayFire backends libraries, dlls and dependency dlls (library directory)
+4. `AF_PATH/examples` : Examples to get started. Some examples also have pre-built exectuables
+5. `AF_PATH/cmake` : CMake config files for automatic configuration by external projects
+6. `AF_PATH/uninstall.exe` : Uninstaller
+7. `AF_PATH/*` : Other miscellenous files including licenses, logos, copyrights
-If you are creating a new project which is intended to be platform-independent,
-the best option is to simply copy the existing `helloworld` solution files
-and modify them to suit your needs. This will retain all the platform based
-settings that have been configured in the examples. You can find the example
-in the `AF_PATH/examples/helloworld/helloworld.sln` directory.
+The installer also appends `%%AF_PATH%/lib` to the User PATH variable.
-### Adding ArrayFire CPU/OpenCL to a new/existing project
+To add `%%AF_PATH%/lib` to PATH for all users see the windows section in
+[installation instructions](\ref installing).
-If you are adding ArrayFire to a new or existing project that will contain
-custom CPU or OpenCL kernels, you only need to make a few modifications to
-your project soultion:
+### <a name="nvvm_dlls" />Dealing with CUDA NMMV DLLs
+When using CUDA with ArrayFire you may encounter a linker error indicating the
+NVVM DLLs are missing. This is because the NVVM DLLs are not part of the
+standard `CUDA_PATH\bin` installation directory that is added to your `PATH`
+when the CUDA installer runs. Thus, NVVM will not be found during runtime. There
+are a few ways to deal with this issue:
+
+1. Copy the DLLs to the exectuable location. This is, by far, the cleanest
+ solution and we recommend doing this with ArrayFire projects. To do so,
+ create a post-build event to copy the NVVM DLL as discusses below in
+ [Step 3 - Part A](#s3partA).
+2. Copy `CUDA_PATH\nvvm\bin\nvvm64_30_0.dll` to `CUDA_PATH\bin`. This is a one time
+ copy such that the NVVM DLL is now with all the other CUDA dlls and in a
+ directory that is a part of PATH and hence the DLL can be detected automatically.
+3. Add `%%CUDA_PATH%\nvvm\bin` to the system PATH environment variable.
+ This will allow automatic detection by the system and No further copying will
+ be required. ArrayFire does not add this to PATH since the CUDA installer
+ doesn't add it to PATH.
+
+## <a name="step1" />Step 1: Running pre-built executables
-1. Open an existing project or create a new "Empty C/C++ project in Visual Studio"
-2. Add `$(AF_PATH)/include;` to
- _Project Properties -> C/C++ -> General -> Additional Include Directories_
-3. Add `$(AF_PATH)/lib;` to
- _Project Properties -> Linker -> General -> Additional Library Directories_
-4. Add `afcpu.lib` or `afcuda.lib` or `afopencl.lib` to
- _Project Properties -> Linker -> Input -> Additional Dependencies_
- based on your preferred backend.
-5. (Optional) You make choose to define `NOMINMAX`, `AF_<CPU/CUDA/OPENCL>`
- and/or `AF_<DEBUG/RELEASE>` in your projects. This can be added to
- _Project Properties -> C/C++ -> General -> Preprocessor-> Preprocessory definitions_.
+The ArrayFire installer ships with a few pre-built executables with the examples.
+These should run out of the box when double clicked.
-### Adding ArrayFire CUDA to a new/existing project
+Some prebuilt examples are:
+* Helloworld (examples/helloworld)
+* BLAS (examples/benchmarks)
+* FFT (examples/benchmarks)
+* Pi Estimation (examples/benchmarks)
+* Conway (Graphics) (examples/graphics)
-Lastly, if your project contains custom CUDA code, the instructions are slightly
-different:
+Note: For the CUDA executables, you will need to copy `CUDA_PATH\nvvm\bin\nvvm64_30_0.dll`
+to the location of the executables.
-1. Create a custom "CUDA NVCC project" in Visual Studio
-2. Follow steps 2-5 from the _Adding ArrayFire CPU/OpenCL to a new/existing project_
- instructions above
-3. Add the following lines to the
- _Project Properties -> Build Events -> Post Build Events_
- dialog:
+## <a name="step2" />Step 2: Build and Run a Project
+1. Open Visual Studio 2013. Load the HelloWorld solution which is located at
+ `AF_PATH/examples/helloworld/helloworld.sln`.
+2. Build the `helloworld` example. Be sure to, select the platform/configuration
+ of your choice using the platform drop-down (the options are CPU, CUDA,
+ OpenCL, and Unified) and Solution Configuration drop down (options of Release
+ and Debug) menus.
+3. Run the `helloworld` example.
+
+## <a name="step3" />Step 3: Using ArrayFire within Visual Studio
+This is divided into 4 parts:
+* [Part A: Adding ArrayFire to an existing solution (Single Backend)](#s3partA)
+* [Part B: Adding ArrayFire CUDA to a new/existing CUDA project](#s3partB)
+* [Part C: Project with all ArrayFire backends](#s3partC)
+* [Part D: ArrayFire with CMake](#s3partD)
+
+### <a name="s3partA" />Part A: Adding ArrayFire to an existing solution (Single Backend)
+Note: If you plan on using Native CUDA code in the project, use the steps
+under [Part B](#s3partB).
+
+Adding a single backend to an existing project is quite simple.
+
+1. Add `"$(AF_PATH)/include;"` to
+ _Project Properties -> C/C++ -> General -> Additional Include Directories_.
+2. Add `"$(AF_PATH)/lib;"` to
+ _Project Properties -> Linker -> General -> Additional Library Directories_.
+3. Add `afcpu.lib` or `afcuda.lib` or `afopencl.lib` to
+ _Project Properties -> Linker -> Input -> Additional Dependencies_.
+ based on your preferred backend.
+4. (Optional) You may choose to define `NOMINMAX`, `AF_<CPU/CUDA/OPENCL>`
+ and/or `AF_<DEBUG/RELEASE>` in your projects. This can be added to
+ _Project Properties -> C/C++ -> General -> Preprocessor-> Preprocessory definitions_.
+
+If you are using the CUDA backend, it is important to ensure that the CUDA NVVM
+DLLs are copied to the exectuable directory. This can be done by adding a post
+build event.
+
+Open the _Project Properties -> Build Events -> Post Build Events_ dialog and
+add the following lines to it.
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~{.c}
echo copy "$(CUDA_PATH)\nvvm\bin\nvvm64*.dll" "$(OutDir)"
copy "$(CUDA_PATH)\nvvm\bin\nvvm64*.dll" "$(OutDir)"
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-4. Ensure that you use x64 based configurations.
+### <a name="s3partB" />Part B: Adding ArrayFire CUDA to a new/existing CUDA project
+Lastly, if your project contains custom CUDA code, the instructions are slightly
+different as it requires using a CUDA NVCC Project:
+
+1. Create a custom "CUDA NVCC project" in Visual Studio
+2. Add `"$(AF_PATH)/include;"` to
+ _Project Properties -> CUDA C/C++ -> General -> Additional Include Directories_.
+3. Add `"$(AF_PATH)/lib;"` to
+ _Project Properties -> Linker -> General -> Additional Library Directories_.
+4. Add `afcpu.lib` or `afcuda.lib` or `afopencl.lib` to
+ _Project Properties -> Linker -> Input -> Additional Dependencies_.
+ based on your preferred backend.
+5. (Optional) You may choose to define `NOMINMAX`, `AF_CUDA`
+ and/or `AF_<DEBUG/RELEASE>` in your projects. This can be added to
+ _Project Properties -> C/C++ -> General -> Preprocessor-> Preprocessory definitions_.
+6. Pick a solution to handle the NVVM DLLs. We recommend the post build event
+ method used in [Part A](#s3partA).
+
+### <a name="s3partC" />Part C: Project with all ArrayFire backends
+If you wish to create a project that allows you to use all the ArrayFire
+backends with ease, the best way to go is to copy the *HelloWorld sln/vcxproj/cpp*
+file trio and rename them to suit your project.
+
+All the ArrayFire examples are pre-configured for all ArrayFire backends as well
+as the Unified API. These can be chosen from the Solution/Platform configuration
+drop down boxes.
+
+You can alternately download the template project from
+[ArrayFire Template Projects](https://github.com/arrayfire/arrayfire-template-projects)
+
+### <a name="s3partD" />Part D: ArrayFire with CMake
+*NOTE:* The ArrayFire installer sets up CMake file and registry so that it can be found
+by CMake by simply using the `Find_PACKAGE(ArrayFire)` command.
+
+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-template-projects);
+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).
+
+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})
+
+ ... [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})
+
+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
+ 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:
+
+ 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
+
+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.
+
+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 open the CMake GUI.
+
+* Under source directory, add the path to your project
+* Under build directory, add the path to your project and append /build
+* Click configure and choose Visual Studio 2013 Win 64 as the generator.
+* If configuration was successful, click generate. This will create a
+ my-project.sln file under build. You can open this in Visual Studio and
+ compile the ALL_BUILD project.
+
+
+The [ArrayFire CMake Example](https://github.com/bkloppenborg/arrayfire-cmake-example)
+is a CMake project used to demo how ArrayFire can be using with a CMake project.
+
+Note: The CMake project does not add the post build event to copy the NVVM DLLs
+in case of CUDA backend. You will need to either copy it manually to the exectuable
+directory, or pick another solution for it.
-Please note that this method will not work with the ArrayFire examples as
-our implementations are built with the Visual Studio CL compiler rather than
-NVCC to ensure they are supported across various platforms.
--
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