1..
2     Copyright 2013 Pixar
3
4     Licensed under the Apache License, Version 2.0 (the "Apache License")
5     with the following modification; you may not use this file except in
6     compliance with the Apache License and the following modification to it:
7     Section 6. Trademarks. is deleted and replaced with:
8
9     6. Trademarks. This License does not grant permission to use the trade
10        names, trademarks, service marks, or product names of the Licensor
11        and its affiliates, except as required to comply with Section 4(c) of
12        the License and to reproduce the content of the NOTICE file.
13
14     You may obtain a copy of the Apache License at
15
16         http://www.apache.org/licenses/LICENSE-2.0
17
18     Unless required by applicable law or agreed to in writing, software
19     distributed under the Apache License with the above modification is
20     distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
21     KIND, either express or implied. See the Apache License for the specific
22     language governing permissions and limitations under the Apache License.
23
24
25Building with CMake
26-------------------
27
28.. contents::
29   :local:
30   :backlinks: none
31
32
33----
34
35Overview
36========
37
38Assuming that you have `cloned <getting_started.html>`__ the source repository
39and selected an appropriate release branch, the following instructions will
40walk you through the CMake and configuration and build process.
41
42CMake is a cross-platform, open-source build system. CMake controls the compilation
43process using platform independent configuration files in order to generate
44Makefiles and workspaces that are native to the platform of choice.
45
46The process involves the following steps:
47
48    #. Locate & build the requisite dependencies
49    #. Configure & run CMake to generate Makefiles / MSVC solution / XCode project
50    #. Run the build from make / MSVC / XCode
51
52----
53
54Step 1: Dependencies
55====================
56
57CMake will adapt the build based on which dependencies have been successfully
58discovered and will disable certain features and code examples accordingly.
59
60Please refer to the documentation of each of the dependency packages for specific
61build and installation instructions.
62
63Required
64________
65    - `CMake <http://www.cmake.org/>`__ version 2.8
66
67Optional
68________
69
70    - `Ptex <http://ptex.us/>`__ (support features for ptex textures and the
71      ptexViewer example)
72    - `Zlib <http://www.zlib.net/>`__ (required for Ptex under Windows)
73    - `CUDA <http://www.nvidia.com/object/cuda_home_new.html>`__
74    - `TBB <http://www.threadingbuildingblocks.org/>`__
75    - `OpenCL <http://www.khronos.org/opencl/>`__
76    - `DX11 SDK <http://www.microsoft.com/>`__
77    - `GLFW <https://github.com/glfw/glfw>`__ (required for standalone examples
78      and some regression tests)
79    - `Docutils <http://docutils.sourceforge.net/>`__ (required for reST-based documentation)
80    - `Python Pygments <http://pygments.org/>`__ (required for Docutils reST styling)
81    - `Doxygen <http://www.doxygen.org/>`__
82
83----
84
85Step 2: Configuring CMake
86=========================
87
88One way to configure CMake is to use the `CMake GUI <http://www.cmake.org/cmake/help/runningcmake.html>`__.
89In many cases CMake can fall back on default standard paths in order to find the
90packages that OpenSubdiv depends on. For non-standard installations however, a
91complete set of override variables is available. The following sub-section lists
92some of these variables. For more specific details, please consult the source of
93the custom CMake modules in the OpenSubdiv/cmake/ folder.
94
95Useful Build Options
96____________________
97
98The following configuration arguments can be passed to the CMake command line.
99
100.. code:: c++
101
102   -DCMAKE_BUILD_TYPE=[Debug|Release]
103
104   -DCMAKE_INSTALL_PREFIX=[base path to install OpenSubdiv (default: Current directory)]
105   -DCMAKE_LIBDIR_BASE=[library directory basename (default: lib)]
106
107   -DCUDA_TOOLKIT_ROOT_DIR=[path to CUDA]
108   -DPTEX_LOCATION=[path to Ptex]
109   -DGLFW_LOCATION=[path to GLFW]
110   -DTBB_LOCATION=[path to Intel's TBB]
111   -DICC_LOCATION=[path to Intel's C++ Studio XE]
112
113   -DNO_LIB=1        // disable the opensubdiv libs build (caveat emptor)
114   -DNO_EXAMPLES=1   // disable examples build
115   -DNO_TUTORIALS=1  // disable tutorials build
116   -DNO_REGRESSION=1 // disable regression tests build
117   -DNO_PTEX=1       // disable PTex support
118   -DNO_DOC=1        // disable documentation build
119   -DNO_OMP=1        // disable OpenMP
120   -DNO_TBB=1        // disable TBB
121   -DNO_CUDA=1       // disable CUDA
122   -DNO_OPENCL=1     // disable OpenCL
123   -DNO_OPENGL=1     // disable OpenGL
124   -DNO_CLEW=1       // disable CLEW wrapper library
125
126Environment Variables
127_____________________
128
129The paths to Ptex, GLFW, other dependencies can also be specified
130through the following environment variables:
131
132.. code:: c++
133
134   PTEX_LOCATION, GLFW_LOCATION
135
136Automated Script
137________________
138
139The GUI solution will probably become a burden for active developpers who tend to
140re-run the configuration step fairly often. A scripted solution can save a lot of
141time. Here is a typical workflow:
142
143.. code:: c++
144
145    git clone https://github.com/PixarAnimationStudios/OpenSubdiv.git <folder>
146    cd <folder>
147    mkdir build
148    cd build
149    source ../../cmake_setup
150
151
152Where *cmake_setup* is a configuration script.
153
154Here is an example CMake configuration script for a full typical windows-based
155build that can be run in GitShell :
156
157.. code:: c++
158
159    #/bin/tcsh
160
161    # Replace the ".." with a full path to the root of the OpenSubdiv source tree if necessary
162    "c:/Program Files (x86)/CMake 2.8/bin/cmake.exe" \
163        -G "Visual Studio 15 2017 Win64" \
164        -D "GLFW_LOCATION:string=c:/Program Files/glfw-2.7.7.bin.WIN64" \
165        -D "OPENCL_INCLUDE_DIRS:string=c:/ProgramData/NVIDIA Corporation/NVIDIA GPU Computing SDK 4.2/OpenCL/common/inc" \
166        -D "_OPENCL_CPP_INCLUDE_DIRS:string=c:/ProgramData/NVIDIA Corporation/NVIDIA GPU Computing SDK 4.2/OpenCL/common/inc" \
167        -D "OPENCL_LIBRARIES:string=c:/ProgramData/NVIDIA Corporation/NVIDIA GPU Computing SDK 4.2/OpenCL/common/lib/x64/OpenCL.lib" \
168        -D "PTEX_LOCATION:string=c:/Users/opensubdiv/demo/src/ptex/x64" \
169        ..
170
171    # copy Ptex dependencies (Windows only)
172    mkdir -p bin/{Debug,Release}
173    \cp -f c:/Users/opensubdiv/demo/src/zlib-1.2.7/contrib/vstudio/vc10/x64/ZlibDllRelease/zlibwapi.dll bin/Debug/
174    \cp -f c:/Users/opensubdiv/demo/src/zlib-1.2.7/contrib/vstudio/vc10/x64/ZlibDllRelease/zlibwapi.dll bin/Release/
175    \cp -f c:/Users/opensubdiv/demo/src/ptex/x64/lib/Ptex.dll bin/Debug/
176    \cp -f c:/Users/opensubdiv/demo/src/ptex/x64/lib/Ptex.dll bin/Release/
177
178.. container:: impnotip
179
180   **Important**
181
182      Notice that the following scripts start by **recursively removing** the *../build/* and
183      *../inst/* directories. Make sure you modify them to suit your build workflow.
184
185Here is a similar script for \*Nix-based platforms:
186
187.. code:: c++
188
189    echo "*** Removing build"
190    cd ..; rm -rf build/ inst/; mkdir build; cd build;
191    echo "*** Running cmake"
192    cmake -DPTEX_LOCATION=/home/opensubdiv/dev/opensource/ptex/install \
193          -DGLFW_LOCATION=/home/opensubdiv/dev/opensource/glfw/build \
194          -DDOXYGEN_EXECUTABLE=/home/opensubdiv/dev/opensource/doxygen/inst/bin/doxygen \
195          -DCMAKE_INSTALL_PREFIX=../inst \
196          -DCMAKE_BUILD_TYPE=Debug \
197          ..
198
199Here is a similar script for macOS:
200
201.. code:: c++
202
203    echo "*** Removing build"
204    cd ..; rm -rf build/ inst/; mkdir build; cd build;
205    echo "*** Running cmake"
206    cmake -DOPENGL_INCLUDE_DIR=/Applications/Xcode.app/Contents/Developer/Platforms/MacOSX.platform/Developer/SDKs/MacOSX10.9.sdk/System/Library/Frameworks/OpenGL.framework/Headers \
207          -DGLFW_LOCATION=/Users/opensubdiv/dev/opensource/glfw/inst \
208          -DNO_OMP=1 -DNO_REGRESSION=0 \
209          -DCMAKE_INSTALL_PREFIX=../inst \
210          -DCMAKE_BUILD_TYPE=Debug \
211           .."
212
213Using Intel's C++ Studio XE
214___________________________
215
216OpenSubdiv can be also be built with `Intel's C++ compiler <http://software.intel.com/en-us/intel-compilers>`__
217(icc). The default compiler can be overriden in CMake with the following configuration options:
218
219.. code:: c++
220
221    -DCMAKE_CXX_COMPILER=[path to icc executable]
222    -DCMAKE_C_COMPILER=[path to icc executable]
223
224The installation location of the C++ Studio XE can be overriden with:
225
226.. code:: c++
227
228    -DICC_LOCATION=[path to Intel's C++ Studio XE]
229
230
231Using Clang
232___________
233
234CMake can also be overriden to use the `clang <http://clang.llvm.org/>`__ compilers by configuring the following options:
235
236.. code:: c++
237
238    -DCMAKE_CXX_COMPILER=clang++ \
239    -DCMAKE_C_COMPILER=clang \
240
241
242----
243
244Step 3: Building
245================
246
247CMake provides a cross-platform command-line build:
248
249.. code:: c++
250
251    cmake --build . --target install --config Release
252
253Alternatively, you can use native toolkits to launch the build. The steps differ for each OS:
254
255    * *Windows* :
256        launch VC++ with the solution generated by CMake in your build directory.
257
258    * *macOS* :
259        launch Xcode with the xcodeproj generated by CMake in your build directory
260
261    * *\*Nix* :
262        | run *make* in your build directory
263        | - use the *clean* target to remove previous build results
264        | - use *VERBOSE=1* for verbose build output
265
266----
267
268Build Targets
269_____________
270
271Makefile-based builds allow the use of named target. Here are some of the more
272useful target names:
273
274   *osd_\<static\|dynamic\>_\<CPU\|GPU\>*
275      | The core components of the OpenSubdiv libraries
276      |
277
278   *\<example_name\>*
279      | Builds specific code examples by name (glViewer, ptexViewer...)
280      |
281
282   *doc*
283      | Builds ReST and doxygen documentation
284      |
285
286   *doc_html*
287      | Builds ReST documentation
288      |
289
290   *doc_doxy*
291      | Builds Doxygen documentation
292      |
293
294
295----
296
297Compiling & Linking an OpenSubdiv Application
298=============================================
299
300Here are example commands for building an OpenSubdiv application on several architectures:
301
302**Linux**
303::
304
305  g++ -I$OPENSUBDIV/include -c myapp.cpp
306  g++ myapp.o -L$OPENSUBDIV/lib -losdGPU -losdCPU -o myapp
307
308**macOS**
309::
310
311  g++ -I$OPENSUBDIV/include -c myapp.cpp
312  g++ myapp.o -L$OPENSUBDIV/lib -losdGPU -losdCPU -o myapp
313  install_name_tool -add_rpath $OPENSUBDIV/lib myapp
314
315(On 64-bit OS-X: add ``-m64`` after each ``g++``.)
316
317**Windows**
318::
319
320  cl /nologo /MT /TP /DWIN32 /I"%OPENSUBDIV%\include" -c myapp.cpp
321  link /nologo /out:myapp.exe /LIBPATH:"%OPENSUBDIV%\lib" libosdGPU.lib libosdCPU.lib myapp.obj
322
323
324.. container:: impnotip
325
326    **Note:**
327
328    HBR uses the offsetof macro on a templated struct, which appears to spurriously set off a
329    warning in both gcc and Clang. It is recommended to turn the warning off with the
330    *-Wno-invalid-offsetof* flag.
331