svenevs/README.md

## README.md

      
    Raw
  

              README.md
            
          
    Unofficial Installation Guide for librealsense on OSX

These instructions are for how to build librealsense on OSX
with OpenMP support.
Install the Dependencies

Setup Brew (the OSX Package Manager)

The easiest way to get everything setup correctly on OSX is to install the
dependencies with brew.  After pasting the command on the linked
website, make sure you read the instructions it reports.  Brew may tell you
about additional steps you need to take.  After following any of the directions
it may have stated, you are advised to run
$ brew doctor
Install the Dependencies using Brew

Now that you have brew installed, you need to install the dependencies.
# Install a modern version of CMake
$ brew install cmake

# pkg-config allows us to find libusb
$ brew install pkg-config

# libusb is for transfer protocols
$ brew install libusb

# librealsense on OSX defaults to a libuvc backend
$ brew install libuvc

# Install GLFW3 for OpenGL windows
$ brew install homebrew/versions/glfw3
This guide is written to enable you to install librealsense using OpenMP
threading support.  You can skip this next step if you decide you do not want
threaded support for image conversions / compression operations.  Generally
speaking, you do want OpenMP support.
# This may take a while to install!
$ brew install llvm
Build librealsense

Acquire librealsense

For this tutorial, you will need to be an administrator on your computer.  If
you are not, then install it somewhere underneath your home directory instead.
We will build librealsense in /opt/librealsense_build, and ultimately
install it to /opt/librealsense.  You can choose to build / install it
anywhere you prefer.
# Go to /opt and clone the repository
sven:~> cd /opt

sven:/opt> sudo git clone https://github.com/IntelRealSense/librealsense.git librealsense_build
Password:
Cloning into 'librealsense_build'...
remote: Counting objects: 34377, done.
remote: Compressing objects: 100% (24/24), done.
remote: Total 34377 (delta 8), reused 19 (delta 5), pack-reused 34347
Receiving objects: 100% (34377/34377), 97.32 MiB | 885.00 KiB/s, done.
Resolving deltas: 100% (24823/24823), done.
Now that you have the repository, give your user ownership of the directory.
sven:/opt> echo $USER
sven

sven:/opt> sudo chown -R sven librealsense_build/
Now that you can modify the directory structure, you are encouraged to checkout
a stable release tag rather than building from the master branch.  At the time
of writing this, the latest stable release is v2.8.0.
sven:/opt> cd librealsense_build/

sven:/opt/librealsense_build> git tag -l
...
v2.7.7
v2.7.9
v2.8.0
...

sven:/opt/librealsense_build> git checkout v2.8.0
Note: checking out 'v2.8.0'.

...
Build librealsense

Assuming you followed the instructions above and performed brew install llvm,
we will use this to compile librealsense as it will contain a fully-featured
LLVM compiler toolchain, complete with OpenMP support.  We set four variables to
ensure everything will work correctly when using CMake (skip if you are not
building OpenMP support):
sven:/opt/librealsense_build> export CC=/usr/local/opt/llvm/bin/clang
sven:/opt/librealsense_build> export CXX=/usr/local/opt/llvm/bin/clang++
sven:/opt/librealsense_build> export LDFLAGS="-L/usr/local/opt/llvm/lib"
sven:/opt/librealsense_build> export CPPFLAGS="-I/usr/local/opt/llvm/include"
CMake uses the CC and CXX environment variables to determine which compiler
to use.  The LDFLAGS and CPPFLAGS environment variables will be used to set
where the libraries being linked against are (particularly, libiomp.so), and
where the C++ standard library headers are.
We can now build librealsense as follows, where you would change
CMAKE_INSTALL_PREFIX to wherever you want the final installation to end up.
# Always build projects "out of source"
sven:/opt/librealsense_build> mkdir build

sven:/opt/librealsense_build> cd build

sven:/opt/librealsense_build/build> cmake .. -DBUILD_EXAMPLES=ON -DCMAKE_INSTALL_PREFIX=/opt/librealsense
...
-- Check for working C compiler: /usr/local/opt/llvm/bin/clang -- works
...
-- Check for working CXX compiler: /usr/local/opt/llvm/bin/clang++ -- works
...
-- Info: REALSENSE_VERSION_STRING=2.8.0
...
-- Found OpenMP_C: -fopenmp=libomp (found version "3.1")
-- Found OpenMP_CXX: -fopenmp=libomp (found version "3.1")
CMake Warning at CMakeLists.txt:461 (message):
  Using libuvc!

...
-- Checking for one of the modules 'libusb-1.0'
...
Assuming the configuration output reports success / uses the compiler you want,
we can now build and then install
# First build the library
sven:/opt/librealsense_build/build> make -j 4

# If everything was built correctly, install it recalling that
# in this tutorial we are installing to /opt/librealsense
sven:/opt/librealsense_build/build> sudo make install
Enable librealsense for Other CMake Projects

The reason for building in /opt/librealsense_build, and installing to
/opt/librealsense is so that we can make changes or update easily.  The
default CMAKE_INSTALL_PREFIX is /usr/local, it is generally dangerous to
try and selectively delete things from there.  In the future, if you want to
get a new version (say v2.8.9 was released):
$ cd /opt/librealsense_build

$ git pull

$ git tag -l

# NOTE: does not currently exist, just an example
$ git checkout v2.8.9
You can now delete the entire build directory and start over.  The consequence
if this strategy is that while it is easier to maintain / update installations,
there is nothing currently indicating to other projects that this is where
librealsense is installed.  If you want to use librealsense in a project,
you are encouraged to add the following to your shell configuration file
(e.g., your ~/.bashrc):
# Shell access to the built executables (e.g., `realsense-viewer`)
export PATH="/opt/librealsense/bin${PATH:+:${PATH}}"

# Linkage paths for building libraries that depend on `librealsense2`
export LD_LIBRARY_PATH="/opt/librealsense/lib${LD_LIBRARY_PATH:+:${LD_LIBRARY_PATH}}"
export DYLD_LIBRARY_PATH="/opt/librealsense/lib${DYLD_LIBRARY_PATH:+:${DYLD_LIBRARY_PATH}}"

# Allow e.g. `pkg-config --cflags --libs realsense2`
export PKG_CONFIG_PATH="/opt/librealsense/lib/pkgconfig${PKG_CONFIG_PATH:+:${PKG_CONFIG_PATH}}"

# Allow for `find_package(realsense2)` in CMake projects
export CMAKE_MODULE_PATH="/opt/librealsense/lib/cmake${CMAKE_MODULE_PATH:+:${CMAKE_MODULE_PATH}}"