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