/docs/installation.rst

Relevant Search: With Applications for Solr and Elasticsearch

For more in depth reading about search, ranking and generally everything you could ever want to know about how lucene, elasticsearch or solr work under the hood I highly suggest this book. Easily one of the most interesting technical books I have read in a long time. If you are tasked with solving search relevance problems even if not in Solr or Elasticsearch it should be your first reference. Amazon Affiliate Link

  1..
  2  SPDX-License-Identifier: CC-BY-4.0
  3  Copyright Contributors to the OpenColorIO Project.
  4
  5.. _installation:
  6
  7Installation
  8============
  9
 10The easy way
 11************
 12
 13While prebuilt binaries are not yet available for all platforms, OCIO
 14is available via several platform's package managers.
 15
 16Fedora and RHEL
 17^^^^^^^^^^^^^^^
 18
 19In Fedora Core 15 and above, the following command will install OpenColorIO::
 20
 21    yum install OpenColorIO
 22
 23Providing you are using the `Fedora EPEL repository
 24<http://fedoraproject.org/wiki/EPEL>`__ (see the `FAQ for instructions
 25<http://fedoraproject.org/wiki/EPEL/FAQ#Using_EPEL>`__), this same
 26command will work for RedHat Enterprise Linux 6 and higher (including
 27RHEL derivatives such as CentOS 6 and Scientific Linux 6)
 28
 29OS X using Homebrew
 30^^^^^^^^^^^^^^^^^^^
 31
 32You can use the Homebrew package manager to install OpenColorIO on OS X.
 33
 34First install Homebrew as per the instructions on the `Homebrew
 35homepage <http://mxcl.github.com/homebrew/>`__ (or see the `Homebrew wiki
 36<https://github.com/mxcl/homebrew/wiki/Installation>`__ for more
 37detailed instructions)
 38
 39Then simply run the following command to install::
 40
 41    brew install opencolorio
 42
 43To build with the Python library use this command::
 44
 45    brew install opencolorio --with-python
 46
 47
 48.. _building-from-source:
 49
 50Building from source
 51********************
 52
 53Dependencies
 54************
 55
 56The basic requirements for building OCIO are:
 57
 58- cmake >= 3.10
 59- \*Expat >= 2.2.5 (XML parser for CDL/CLF/CTF)
 60- \*yaml-cpp >= 0.6.3 (YAML parser for Configs)
 61- \*IlmBase (Half only) >= 2.3.0 (for half domain LUTs)
 62- \*pystring >= 1.1.3
 63
 64Some optional components also depend on:
 65
 66- \*Little CMS >= 2.2 (for ociobakelut ICC profile baking)
 67- Python 2.x (for the Python bindings and docs)
 68    - \*Sphinx >= 1.8.5
 69- Nuke 6.x or newer (for the Nuke nodes)
 70- OpenImageIO (for apps including ocioconvert)
 71
 72Automated Installation
 73^^^^^^^^^^^^^^^^^^^^^^
 74
 75Listed dependencies with a preceeding * can be automatically installed at 
 76build time by setting the ``OCIO_INSTALL_EXT_PACKAGES`` option in your cmake 
 77command (requires an internet connection). C/C++ libraries are pulled from 
 78external repositories, built, and statically-linked into libOpenColorIO. Python 
 79packages are installed with ``pip``. All installs are fully contained within 
 80your build directory.
 81
 82Three ``OCIO_INSTALL_EXT_PACKAGES`` options are available::
 83
 84    cmake -DOCIO_INSTALL_EXT_PACKAGES=<NONE|MISSING|ALL>
 85
 86- ``NONE`` (default): Use system installed packages. Fail if any are missing or 
 87  don't meet minimum version requireements.
 88- ``MISSING``: Prefer system installed packages. Install any that are not 
 89  found or don't meet minimum version requireements.
 90- ``ALL``: Install all required packages, regardless of availability on the 
 91  current system.
 92
 93Existing Install Hints
 94^^^^^^^^^^^^^^^^^^^^^^
 95
 96When using existing system libraries, the following CMake variables can be 
 97defined to hint at non-standard install locations and preference of shared
 98or static linking:
 99
100- ``-DEXPAT_DIRS=<path>`` (include and/or library root dir)
101- ``-DEXPAT_STATIC_LIBRARY=ON`` (prefer static lib)
102- ``-DYAMLCPP_DIRS=<path>`` (include and/or library root dir)
103- ``-DYAMLCPP_STATIC_LIBRARY=ON`` (prefer static lib)
104- ``-DILMBASE_DIRS=<path>`` (include and/or library root dir)
105- ``-DILMBASE_STATIC_LIBRARY=ON`` (prefer static lib)
106- ``-DPYSTRING_DIRS=<path>`` (include and/or library root dir)
107- ``-DPYSTRING_STATIC_LIBRARY=ON`` (prefer static lib)
108- ``-DLCMS2_DIRS=<path>`` (include and/or library root dir)
109- ``-DLCMS2_STATIC_LIBRARY=ON`` (prefer static lib)
110- ``-DNUKE_INSTALL_PATH=<path>`` (or use ``NDK_PATH`` environment variable)
111
112To hint at Python package locations, add paths to the ``PYTHONPATH`` 
113environment variable prior to configuring the build.
114
115.. _osx-and-linux:
116
117OS X and Linux
118^^^^^^^^^^^^^^
119
120While there is a huge range of possible setups, the following steps
121should work on OS X and most Linux distros. To keep things simple, this guide 
122will use the following example paths - these will almost definitely be 
123different for you:
124
125- source code: ``/source/ocio``
126- the temporary build location: ``/tmp/ociobuild``
127- the final install directory: ``/software/ocio``
128
129First make the build directory and cd to it::
130
131    $ mkdir /tmp/ociobuild
132    $ cd /tmp/ociobuild
133
134Next step is to run cmake, which looks for things such as the
135compiler's required arguments, optional requirements like Python,
136Nuke, OpenImageIO etc
137
138As we want to install OCIO to a custom location (instead of the
139default ``/usr/local``), we will run cmake with
140``CMAKE_INSTALL_PREFIX``.
141
142Still in ``/tmp/ociobuild``, run::
143
144    $ cmake -DCMAKE_INSTALL_PREFIX=/software/ocio /source/ocio
145
146The last argument is the location of the OCIO source code (containing
147the main CMakeLists.txt file). You should see something along the
148lines of::
149
150    -- Configuring done
151    -- Generating done
152    -- Build files have been written to: /tmp/ociobuild
153
154Next, build everything (with the ``-j`` flag to build using 8
155threads)::
156
157    $ make -j8
158
159Starting with CMake 3.12, you can instead run a portable parallel build::
160
161    $ cmake --build . -j 8
162
163This should complete in a few minutes. Finally, install the files into
164the specified location::
165
166    $ make install
167
168If nothing went wrong, ``/software/ocio`` should look something like
169this::
170
171    $ cd /software/ocio
172    $ ls
173    bin/     include/ lib/
174    $ ls bin/
175    ocio2icc    ociobakelut ociocheck
176    $ ls include/
177    OpenColorIO/   PyOpenColorIO/ pkgconfig/
178    $ ls lib/
179    libOpenColorIO.a      libOpenColorIO.dylib
180
181.. _windows-build:
182
183Windows Build
184^^^^^^^^^^^^^
185
186While build environments may vary between user, here is an example batch file
187for compiling on Windows as provided by `@hodoulp <https://github.com/hodoulp>`__::
188
189    @echo off
190
191
192    REM Grab the repo name, default is ocio
193    set repo_name=ocio
194    if not %1.==. set repo_name=%1
195
196
197    REM Using cygwin to have Linux cool command line tools
198    set CYGWIN=nodosfilewarning
199
200    set CMAKE_PATH=D:\OpenSource\3rdParty\cmake-3.12.2
201    set GLUT_PATH=D:\OpenSource\3rdParty\freeglut-3.0.0-2
202    set GLEW_PATH=D:\OpenSource\3rdParty\glew-1.9.0
203    set PYTHON_PATH=C:\Python27
204
205    REM Add glut & glew dependencies to have GPU unit tests
206    set PATH=%GLEW_PATH%\bin;%GLUT_PATH%\bin;D:\Tools\cygwin64\bin;%CMAKE_PATH%\bin;%PATH%
207
208    REM Add Ninja & jom to speed-up command line build i.e. one is enough
209    set PATH=D:\OpenSource\3rdParty\ninja;D:\OpenSource\3rdParty\jom;%PYTHONPATH%;%PATH%
210
211    call "C:\Program Files (x86)\Microsoft Visual Studio 14.0\VC\vcvarsall.bat" x64
212    REM call "C:\Program Files (x86)\Microsoft Visual Studio\2017\Professional\VC\Auxiliary\Build\vcvarsall.bat" x64
213
214    set OCIO_PATH=D:\OpenSource\%repo_name%
215
216    D:
217
218    IF NOT EXIST %OCIO_PATH% ( 
219    echo %OCIO_PATH% does not exist
220    exit /b
221    )
222    cd %OCIO_PATH%
223
224
225    set CMAKE_BUILD_TYPE=Release
226
227    echo *******
228    echo *********************************************
229    echo ******* Building %OCIO_PATH%
230    echo **
231    echo **
232    set are_you_sure = Y
233    set /P are_you_sure=Build in %CMAKE_BUILD_TYPE% ([Y]/N)?  
234    if not %are_you_sure%==Y set CMAKE_BUILD_TYPE=Debug
235
236
237    set BUILD_PATH=%OCIO_PATH%\build_rls
238    set COMPILED_THIRD_PARTY_HOME=D:/OpenSource/3rdParty/compiled-dist_rls
239    set OCIO_BUILD_PYTHON=1
240
241    if not %CMAKE_BUILD_TYPE%==Release (
242    set BUILD_PATH=%OCIO_PATH%\build_dbg
243    set COMPILED_THIRD_PARTY_HOME=D:/OpenSource/3rdParty/compiled-dist_dbg
244    set OCIO_BUILD_PYTHON=0
245    )
246
247    set INSTALL_PATH=%COMPILED_THIRD_PARTY_HOME%/OpenColorIO-2.0.0
248
249    IF NOT EXIST %BUILD_PATH% ( mkdir %BUILD_PATH% )
250    cd %BUILD_PATH%
251
252    echo **
253    echo **
254
255    REM cmake -G "Visual Studio 14 2015 Win64"
256    REM cmake -G "Visual Studio 15 2017 Win64"
257    REM cmake -G "Ninja"
258    cmake -G "NMake Makefiles JOM" ^
259        -DCMAKE_BUILD_TYPE=%CMAKE_BUILD_TYPE% ^
260        -DCMAKE_INSTALL_PREFIX=%INSTALL_PATH% ^
261        -DBUILD_SHARED_LIBS=ON ^
262        -DOCIO_BUILD_APPS=ON ^
263        -DOCIO_BUILD_TESTS=ON ^
264        -DOCIO_BUILD_GPU_TESTS=ON ^
265        -DOCIO_BUILD_DOCS=OFF ^
266        -DOCIO_USE_SSE=ON ^
267        -DOCIO_WARNING_AS_ERROR=ON ^
268        -DOCIO_BUILD_PYTHON=%OCIO_BUILD_PYTHON% ^
269        -DPYTHON_LIBRARY=%PYTHONPATH%\libs\python27.lib ^
270        -DPYTHON_INCLUDE_DIR=%PYTHONPATH%\include ^
271        -DPYTHON_EXECUTABLE=%PYTHONPATH%\python.exe ^
272        -DOCIO_BUILD_JAVA=OFF ^
273        -DCMAKE_PREFIX_PATH=%COMPILED_THIRD_PARTY_HOME%\OpenImageIO-1.9.0;%COMPILED_THIRD_PARTY_HOME%/ilmbase-2.2.0 ^
274        %OCIO_PATH%
275
276    REM Add OCIO & OIIO
277    set PATH=%BUILD_PATH%\src\OpenColorIO;%INSTALL_PATH%\bin;%COMPILED_THIRD_PARTY_HOME%\OpenImageIO-1.9.0\bin;%PATH%
278
279
280    REM Find the current branch
281    set GITBRANCH=
282    for /f %%I in ('git.exe rev-parse --abbrev-ref HEAD 2^> NUL') do set GITBRANCH=%%I
283
284    if not "%GITBRANCH%" == ""  prompt $C%GITBRANCH%$F $P$G
285
286    TITLE %repo_name% (%GITBRANCH%)
287
288    echo *******
289    echo *********************************************
290    if not "%GITBRANCH%" == "" echo branch  = %GITBRANCH%
291    echo *
292    echo Mode         = %CMAKE_BUILD_TYPE%
293    echo Build path   = %BUILD_PATH%
294    echo Install path = %INSTALL_PATH%
295    echo *
296    echo compile = jom all
297    echo test    = ctest -V
298    echo doc     = jom doc
299    echo install = jom install
300    echo *********************************************
301    echo *******
302
303You could create a desktop shortcut with the following command:
304    ``%comspec% /k "C:\Users\hodoulp\ocio.bat" ocio``
305
306Also look to the Appveyor config script at the root of repository for an example
307build sequence.
308
309.. _enabling-optional-components:
310
311Enabling optional components
312^^^^^^^^^^^^^^^^^^^^^^^^^^^^
313
314The OpenColorIO library is probably not all you want - the Python
315libraries bindings, the Nuke nodes and several applications are only
316built if their dependencies are found.
317
318In the case of the Python bindings, the dependencies are the Python
319headers for the version you wish to use. These may be picked up by
320default - if so, when you run cmake you would see::
321
322    -- Python 2.6 okay, will build the Python bindings against .../include/python2.6
323
324If not, you can point cmake to correct Python executable using the
325``-D PYTHON=...`` cmake flag::
326
327    $ cmake -D PYTHON=/my/custom/python2.6 /source/ocio
328
329Same process with Nuke (although it less likely to be picked up
330automatically). Point cmake to your Nuke install directory by adding
331``-D NUKE_INSTALL_PATH``::
332
333    $ cmake -D PYTHON=/my/custom/python2.6 -D NUKE_INSTALL_PATH=/Applications/Nuke6.2v1/Nuke6.2v1.app/Contents/MacOS/ /source/ocio
334
335The ``NUKE_INSTALL_PATH`` directory should contain the Nuke executable
336(e.g Nuke6.2v1), and a ``include/`` directory containing ``DDImage/``
337and others.
338
339If set correctly, you will see something similar to::
340
341    -- Found Nuke: /Applications/Nuke6.2v1/Nuke6.2v1.app/Contents/MacOS/include
342    -- Nuke_API_VERSION: --6.2--
343
344The Nuke plugins are installed into ``lib/nuke$MAJOR.$MINOR/``, e.g
345``lib/nuke6.2/OCIODisdplay.so``
346
347
348.. note::
349
350    If you are using the Nuke plugins, you should compile the Python
351    bindings for the same version of Python that Nuke uses
352    internally. For Nuke 6.0 and 6.1 this is Python 2.5, and for 6.2
353    it is Python 2.6
354
355The applications included with OCIO have various dependencies - to
356determine these, look at the CMake output when first run::
357
358    -- Not building ocioconvert. Requirement(s) found: OIIO:FALSE
359
360
361.. _quick-env-config:
362
363Quick environment configuration
364*******************************
365
366The quickest way to set the required :ref:`environment-setup` is to
367source the ``share/ocio/setup_ocio.sh`` script installed with OCIO.
368
369For a simple single-user setup, add the following to ``~/.bashrc``
370(assuming you are using bash, and the example install directory of
371``/software/ocio``)::
372
373    source /software/ocio/share/ocio/setup_ocio.sh
374
375The only environment variable you must configure manually is
376:envvar:`OCIO`, which points to the configuration file you wish to
377use. For prebuilt config files, see the
378:ref:`downloads` section
379
380To do this, you would add a line to ``~/.bashrc`` (or a per-project
381configuration script etc), for example::
382
383    export OCIO="/path/to/my/config.ocio"
384
385
386.. _nuke-configuration:
387
388Nuke Configuration
389******************
390
391If you specified the ``NUKE_INSTALL_PATH`` option when running cmake,
392you should have a ``/software/ocio/lib/nuke6.2`` directory containing
393various files.
394
395If you have followed :ref:`quick-env-config`, the plugins should be
396functional. However, one common additional configuration step is to
397register an OCIODisplay node for each display device/view specified in
398the config.
399
400To do this, in a menu.py on :envvar:`NUKE_PATH` (e.g
401``~/.nuke/menu.py`` for a single user setup), add the following:
402
403.. code-block:: python
404
405    import ocionuke.viewer
406    ocionuke.viewer.populate_viewer(also_remove = "default")
407
408The ``also_remove`` argument can be set to either "default" to remove
409the default sRGB/rec709 options, "all" to remove everything, or "none"
410to leave existing viewer processes untouched.
411
412Alternatively, if your workflow has different requirements, you can
413copy the function and modify it as required, or use it as reference to
414write your own, better viewer setup function!
415
416.. literalinclude:: /share/nuke/ocionuke/viewer.py
417   :language: python
418
419
420.. _environment-setup:
421
422Environment variables
423*********************
424
425.. envvar:: OCIO
426
427   This variable needs to point to the global OCIO config file, e.g
428   ``config.ocio``
429
430.. envvar:: OCIO_LOGGING_LEVEL
431
432    Configures OCIO's internal logging level. Valid values are
433    ``none``, ``warning``, ``info``, or ``debug`` (or their respective
434    numeric values ``0``, ``1``, ``2``, or ``3`` can be used)
435
436    Logging output is sent to STDERR output.
437
438.. envvar:: OCIO_ACTIVE_DISPLAYS
439
440   Overrides the :ref:`active-displays` configuration value.
441   Colon-separated list of displays, e.g ``sRGB:P3``
442
443.. envvar:: OCIO_ACTIVE_VIEWS
444
445   Overrides the :ref:`active-views` configuration
446   item. Colon-separated list of view names, e.g
447   ``internal:client:DI``
448
449.. envvar:: DYLD_LIBRARY_PATH
450
451    The ``lib/`` folder (containing ``libOpenColorIO.dylib``) must be
452    on the ``DYLD_LIBRARY_PATH`` search path, or you will get an error
453    similar to::
454
455        dlopen(.../OCIOColorSpace.so, 2): Library not loaded: libOpenColorIO.dylib
456        Referenced from: .../OCIOColorSpace.so
457        Reason: image not found
458
459    This applies to anything that links against OCIO, including the
460    Nuke nodes, and the ``PyOpenColorIO`` Python bindings.
461
462.. envvar:: LD_LIBRARY_PATH
463
464    Equivalent to the ``DYLD_LIBRARY_PATH`` on Linux
465
466.. envvar:: PYTHONPATH
467
468    Python's module search path. If you are using the PyOpenColorIO
469    module, you must add ``lib/python2.x`` to this search path (e.g
470    ``python/2.5``), or importing the module will fail::
471
472        >>> import PyOpenColorIO
473        Traceback (most recent call last):
474          File "<stdin>", line 1, in <module>
475        ImportError: No module named PyOpenColorIO
476
477    Note that :envvar:`DYLD_LIBRARY_PATH` or :envvar:`LD_LIBRARY_PATH`
478    must be set correctly for the module to work.
479
480.. envvar:: NUKE_PATH
481
482    Nuke's customization search path, where it will look for plugins,
483    gizmos, init.py and menu.py scripts and other customizations.
484
485    This should point to both ``lib/nuke6.2/`` (or whatever version
486    the plugins are built against), and ``share/nuke/``