Update documention for Xcode builds

README.md

@@ -117,13 +117,18 @@ mkdir -p bin/{Debug,Release}
 
 Alternatively, you can use the cmake GUI or run the commands from the CLI.
 
-Note : the OSX builder in cmake for Xcode is -G "Xcode"
+Note : the OSX generator in cmake for Xcode is -G "Xcode". However we recommend against using it, as we have noticed problems with dependency tracking.
 
 __Build the project:__
 
+CMake provides a cross-platform command-line build:
+````
+cmake --build . --target install --config Release
+````
+
 Windows : launch VC++ with the solution generated by cmake in your build directory.
 
-OSX : run xcodebuild in your build directory
+OSX : with the Xcode generator, run xcodebuild in your build directory, otherwise make.
 
 *Nix : run make in your build directory
 

documentation/cmake_build.rst

@@ -71,7 +71,7 @@ ________
     - `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/>`__ (Windows/Linux only)
+    - `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/>`__
@@ -135,7 +135,7 @@ following environment variables:
    MAYA_LOCATION
    PTEX_LOCATION
    GLFW_LOCATION
-   GLEW_LOCATION.
+   GLEW_LOCATION
    
 Automated Script
 ________________
@@ -181,6 +181,12 @@ build that can be run in GitShell :
     \cp -f c:/Users/opensubdiv/demo/src/ptex/x64/lib/Ptex.dll bin/Debug/
     \cp -f c:/Users/opensubdiv/demo/src/ptex/x64/lib/Ptex.dll bin/Release/
     
+.. container:: impnotip
+
+   * **Important**
+
+      Notice that the following scripts start by **recursively removing** the *../build/* and 
+      *../inst/* directories. Make sure you modify them to suit your build workflow.
 
 Here is a similar script for \*Nix-based platforms:
 
@@ -197,13 +203,19 @@ Here is a similar script for \*Nix-based platforms:
           -DCMAKE_BUILD_TYPE=Debug \
           ..
 
-.. container:: impnotip
+Here is a similar script for OSX:
 
-   * **Important**
+.. code:: c++
 
-      Notice that this script starts by **recursively removing** the *../build/* and 
-      *../inst/* directories. Make sure you modify this script to suit your build
-      workflow.
+    echo "*** Removing build"
+    cd ..; rm -rf build/ inst/; mkdir build; cd build;
+    echo "*** Running cmake"
+    cmake -DOPENGL_INCLUDE_DIR=/Applications/Xcode.app/Contents/Developer/Platforms/MacOSX.platform/Developer/SDKs/MacOSX10.9.sdk/System/Library/Frameworks/OpenGL.framework/Headers \
+          -DGLFW_LOCATION=/Users/opensubdiv/dev/opensource/glfw/inst \
+          -DNO_OMP=1 -DNO_REGRESSION=0 \
+          -DCMAKE_INSTALL_PREFIX=../inst \
+          -DCMAKE_BUILD_TYPE=Debug \
+           .."
 
 Using Intel's C++ Studio XE
 ___________________________
@@ -223,24 +235,50 @@ The installation location of the C++ Studio XE can be overriden with:
     -DICC_LOCATION=[path to Intel's C++ Studio XE]
 
 
+Using Clang
+___________
+
+CMake can also be overriden to use the `clang <http://clang.llvm.org/>`__ compilers by configuring the following options:
+
+.. code:: c++
+
+    -DCMAKE_CXX_COMPILER=clang++ \
+    -DCMAKE_C_COMPILER=clang \
+
+
 ----
 
 Step 3: Building
 ================
 
-The steps differ for different OS'es:
+CMake provides a cross-platform command-line build:
+
+.. code:: c++
+
+    cmake --build . --target install --config Release
+
+Alternatively, you can native toolkits to launch the build. The steps differ for each OS:
 
     * *Windows* : 
         launch VC++ with the solution generated by cmake in your build directory.
 
     * *OSX* : 
-        run xcodebuild in your build directory
+        run *make* in the 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