Updated build documentation

Replaced Travis-CI and AppVeyor continuous integration badges with badges for Azure Pipelines. Also, improved some out-of-date documentation and updated build notes regarding GLEW.
2024-09-19 14:20:00 +00:00 · 2020-03-20 10:25:23 -07:00 · 2020-03-20 10:25:23 -07:00 · 9a3df44eac
commit 9a3df44eac
parent 04cdd7cc59
2 changed files with 32 additions and 51 deletions
--- a/README.md
+++ b/README.md
@ -8,10 +8,10 @@ Feel free to use it and let us know what you think.

 For more details about OpenSubdiv, see [Pixar Graphics Technologies](http://graphics.pixar.com).

-|        |  Linux and OSX |  Windows  |
-|:------:|:-------:|:---------:|
-| master | [![Linux and OSX Build Status](https://travis-ci.org/PixarAnimationStudios/OpenSubdiv.svg?branch=master)](https://travis-ci.org/PixarAnimationStudios/OpenSubdiv) | [![Windows Build Status](https://ci.appveyor.com/api/projects/status/mcmwg4q9m8kgi9im/branch/master?svg=true)](https://ci.appveyor.com/project/c64kernal/opensubdiv-ddr8q) |
-| dev | [![Linux Build Status](https://travis-ci.org/PixarAnimationStudios/OpenSubdiv.svg?branch=dev)](https://travis-ci.org/PixarAnimationStudios/OpenSubdiv) | [![Windows Build Status](https://ci.appveyor.com/api/projects/status/mcmwg4q9m8kgi9im/branch/dev?svg=true)](https://ci.appveyor.com/project/c64kernal/opensubdiv-ddr8q) |
+|         |   Linux   |  Windows  |   macOS   |
+|:-------:|:---------:|:---------:|:---------:|
+|   dev   | [![Build Status](https://dev.azure.com/PixarAnimationStudios/OpenSubdiv/_apis/build/status/PixarAnimationStudios.OpenSubdiv?branchName=dev&amp;jobName=Linux)](https://dev.azure.com/PixarAnimationStudios/OpenSubdiv/_build/latest?definitionId=2&branchName=dev) | [![Build Status](https://dev.azure.com/PixarAnimationStudios/OpenSubdiv/_apis/build/status/PixarAnimationStudios.OpenSubdiv?branchName=dev&amp;jobName=Windows)](https://dev.azure.com/PixarAnimationStudios/OpenSubdiv/_build/latest?definitionId=2&branchName=dev) | [![Build Status](https://dev.azure.com/PixarAnimationStudios/OpenSubdiv/_apis/build/status/PixarAnimationStudios.OpenSubdiv?branchName=dev&amp;jobName=macOS)](https://dev.azure.com/PixarAnimationStudios/OpenSubdiv/_build/latest?definitionId=2&branchName=dev) |
+|  master | [![Build Status](https://dev.azure.com/PixarAnimationStudios/OpenSubdiv/_apis/build/status/PixarAnimationStudios.OpenSubdiv?branchName=master&amp;jobName=Linux)](https://dev.azure.com/PixarAnimationStudios/OpenSubdiv/_build/latest?definitionId=2&branchName=master) | [![Build Status](https://dev.azure.com/PixarAnimationStudios/OpenSubdiv/_apis/build/status/PixarAnimationStudios.OpenSubdiv?branchName=master&amp;jobName=Windows)](https://dev.azure.com/PixarAnimationStudios/OpenSubdiv/_build/latest?definitionId=2&branchName=master) | [![Build Status](https://dev.azure.com/PixarAnimationStudios/OpenSubdiv/_apis/build/status/PixarAnimationStudios.OpenSubdiv?branchName=master&amp;jobName=macOS)](https://dev.azure.com/PixarAnimationStudios/OpenSubdiv/_build/latest?definitionId=2&branchName=master) |

 ## Documents
 * [User Documents](http://graphics.pixar.com/opensubdiv/docs/intro.html)
@ -35,7 +35,6 @@ For more details about OpenSubdiv, see [Pixar Graphics Technologies](http://grap

 | Lib                                                                | Min Version | Note                        |
 | ------------------------------------------------------------------ | ----------- | ----------------------------|
-| [GLEW](http://glew.sourceforge.net)                                | 1.9.0       | GL backend (Win/Linux only) |
 | [CUDA](http://developer.nvidia.com/cuda-toolkit)                   | 4.0         | cuda backend                |
 | [TBB](https://www.threadingbuildingblocks.org)                     | 4.0         | TBB backend                 |
 | [OpenCL](http://www.khronos.org/opencl)                            | 1.1         | CL backend                  |
@ -63,15 +62,11 @@ For more details about OpenSubdiv, see [Pixar Graphics Technologies](http://grap

 ### All platforms:

-  * Install cmake, GLFW and GLEW (GLEW is not required on OSX)
+  * Install cmake and GLFW

-   make sure GLEW and GLFW install directories configured as follows:
+   make sure GLFW install directories are configured as follows:

 ```
-   ${GLEW_LOCATION}/include/GL/glew.h
-   ${GLEW_LOCATION}/lib/libGLEW.a (linux)
-   ${GLEW_LOCATION}/lib/glew32.lib (windows)
-
   ${GLFW_LOCATION}/include/GLFW/glfw3.h
   ${GLFW_LOCATION}/lib/libglfw3.a (linux)
   ${GLFW_LOCATION}/lib/glfw3.lib (windows)
@ -86,27 +81,26 @@ For more details about OpenSubdiv, see [Pixar Graphics Technologies](http://grap

 ### Windows (Visual Studio)

-  * run cmake:
 ```
-"c:/Program Files (x86)/CMake/bin/cmake.exe" ^
-    -G "Visual Studio 12 Win64" ^
+cmake ^
+    -G "Visual Studio 15 2017 Win64" ^
    -D NO_PTEX=1 -D NO_DOC=1 ^
    -D NO_OMP=1 -D NO_TBB=1 -D NO_CUDA=1 -D NO_OPENCL=1 -D NO_CLEW=1 ^
-    -D "GLEW_LOCATION=*YOUR GLEW INSTALL LOCATION*" ^
    -D "GLFW_LOCATION=*YOUR GLFW INSTALL LOCATION*" ^
    ..
+
+cmake --build . --config Release --target install
 ```
-  * Open OpenSubdiv.sln in VisualStudio and build.

 ### Linux

 ```
 cmake -D NO_PTEX=1 -D NO_DOC=1 \
      -D NO_OMP=1 -D NO_TBB=1 -D NO_CUDA=1 -D NO_OPENCL=1 -D NO_CLEW=1 \
-      -D GLEW_LOCATION="*YOUR GLEW INSTALL LOCATION*" \
      -D GLFW_LOCATION="*YOUR GLFW INSTALL LOCATION*" \
      ..
-make
+
+cmake --build . --config Release --target install
 ```

 ### macOS
@ -116,7 +110,8 @@ cmake -G Xcode -D NO_PTEX=1 -D NO_DOC=1 \
      -D NO_OMP=1 -D NO_TBB=1 -D NO_CUDA=1 -D NO_OPENCL=1 -D NO_CLEW=1 \
      -D GLFW_LOCATION="*YOUR GLFW INSTALL LOCATION*" \
      ..
-make
+
+cmake --build . --config Release --target install
 ```

 ### iOS
@ -144,7 +139,6 @@ SDKROOT=$(xcrun --sdk iphoneos --show-sdk-path) cmake -D NO_PTEX=1 -D NO_DOC=1 \

 -DCUDA_TOOLKIT_ROOT_DIR=[path to CUDA Toolkit]
 -DPTEX_LOCATION=[path to Ptex]
-DGLEW_LOCATION=[path to GLEW]
 -DGLFW_LOCATION=[path to GLFW]
 -DSTRINGIFY_LOCATION=[path to stringify utility]

--- a/documentation/cmake_build.rst
+++ b/documentation/cmake_build.rst
@ -70,7 +70,6 @@ ________
    - `Ptex <http://ptex.us/>`__ (support features for ptex textures and the
      ptexViewer example)
    - `Zlib <http://www.zlib.net/>`__ (required for Ptex under Windows)
-    - `GLEW <http://glew.sourceforge.net/>`__
    - `CUDA <http://www.nvidia.com/object/cuda_home_new.html>`__
    - `TBB <http://www.threadingbuildingblocks.org/>`__
    - `OpenCL <http://www.khronos.org/opencl/>`__
@ -107,7 +106,6 @@ The following configuration arguments can be passed to the CMake command line.

   -DCUDA_TOOLKIT_ROOT_DIR=[path to CUDA]
   -DPTEX_LOCATION=[path to Ptex]
-   -DGLEW_LOCATION=[path to GLEW]
   -DGLFW_LOCATION=[path to GLFW]
   -DTBB_LOCATION=[path to Intel's TBB]
   -DICC_LOCATION=[path to Intel's C++ Studio XE]
@ -128,12 +126,12 @@ The following configuration arguments can be passed to the CMake command line.
 Environment Variables
 _____________________

-The paths to Ptex, GLFW, GLEW and other dependencies can also be specified
+The paths to Ptex, GLFW, other dependencies can also be specified
 through the following environment variables:

 .. code:: c++

-   PTEX_LOCATION, GLFW_LOCATION, GLEW_LOCATION
+   PTEX_LOCATION, GLFW_LOCATION

 Automated Script
 ________________
@ -162,8 +160,7 @@ build that can be run in GitShell :

    # Replace the ".." with a full path to the root of the OpenSubdiv source tree if necessary
    "c:/Program Files (x86)/CMake 2.8/bin/cmake.exe" \
-        -G "Visual Studio 10 Win64" \
-        -D "GLEW_LOCATION:string=c:/Program Files/glew-1.9.0" \
+        -G "Visual Studio 15 2017 Win64" \
        -D "GLFW_LOCATION:string=c:/Program Files/glfw-2.7.7.bin.WIN64" \
        -D "OPENCL_INCLUDE_DIRS:string=c:/ProgramData/NVIDIA Corporation/NVIDIA GPU Computing SDK 4.2/OpenCL/common/inc" \
        -D "_OPENCL_CPP_INCLUDE_DIRS:string=c:/ProgramData/NVIDIA Corporation/NVIDIA GPU Computing SDK 4.2/OpenCL/common/inc" \
@ -193,14 +190,13 @@ Here is a similar script for \*Nix-based platforms:
    cd ..; rm -rf build/ inst/; mkdir build; cd build;
    echo "*** Running cmake"
    cmake -DPTEX_LOCATION=/home/opensubdiv/dev/opensource/ptex/install \
-          -DGLEW_LOCATION=/home/opensubdiv/dev/opensource/glew/glew-1.9.0 \
          -DGLFW_LOCATION=/home/opensubdiv/dev/opensource/glfw/build \
          -DDOXYGEN_EXECUTABLE=/home/opensubdiv/dev/opensource/doxygen/inst/bin/doxygen \
          -DCMAKE_INSTALL_PREFIX=../inst \
          -DCMAKE_BUILD_TYPE=Debug \
          ..

-Here is a similar script for OSX:
+Here is a similar script for macOS:

 .. code:: c++

@ -259,23 +255,14 @@ Alternatively, you can use native toolkits to launch the build. The steps differ
    * *Windows* :
        launch VC++ with the solution generated by CMake in your build directory.

-    * *OSX* :
-        run *make* in the build directory
+    * *macOS* :
+        launch Xcode with the xcodeproj generated by CMake in your build directory

    * *\*Nix* :
        | run *make* in your build directory
        | - use the *clean* target to remove previous build results
        | - use *VERBOSE=1* for verbose build output

-.. container:: notebox
-
-   **Note**
-       We recommend against using CMake's Xcode project generator (-G "Xcode") on OSX, as it seems to
-       generate some dependencies incorrectly. We recommend instead reverting to Makefiles on OSX, and
-       launching *make*, instead of *xcodebuild* to execute the build (make sure to install the command
-       line tools in Xcode)
-
-
 ----

 Build Targets
@ -313,31 +300,31 @@ Compiling & Linking an OpenSubdiv Application
 Here are example commands for building an OpenSubdiv application on several architectures:

 **Linux**
-:: 
-  
-  g++ -I$OPENSUBDIV/include -c myapp.cpp
-  g++ myapp.o -L$OPENSUBDIV/lib -losdCPU -losdGPU -o myapp
-
-**Mac OS-X**   
 ::
-  
+
  g++ -I$OPENSUBDIV/include -c myapp.cpp
-  g++ myapp.o -L$OPENSUBDIV/lib -losdCPU -losdGPU -o myapp
+  g++ myapp.o -L$OPENSUBDIV/lib -losdGPU -losdCPU -o myapp
+
+**macOS**
+::
+
+  g++ -I$OPENSUBDIV/include -c myapp.cpp
+  g++ myapp.o -L$OPENSUBDIV/lib -losdGPU -losdCPU -o myapp
  install_name_tool -add_rpath $OPENSUBDIV/lib myapp

 (On 64-bit OS-X: add ``-m64`` after each ``g++``.)

 **Windows**
 ::
-  
+
  cl /nologo /MT /TP /DWIN32 /I"%OPENSUBDIV%\include" -c myapp.cpp
-  link /nologo /out:myapp.exe /LIBPATH:"%OPENSUBDIV%\lib" libosdCPU.lib libosdGPU.lib myapp.obj 
+  link /nologo /out:myapp.exe /LIBPATH:"%OPENSUBDIV%\lib" libosdGPU.lib libosdCPU.lib myapp.obj


 .. container:: impnotip

    **Note:**
-    
-    HBR uses the offsetof macro on a templated struct, which appears to spurriously set off a 
+
+    HBR uses the offsetof macro on a templated struct, which appears to spurriously set off a
    warning in both gcc and Clang. It is recommended to turn the warning off with the
    *-Wno-invalid-offsetof* flag.