Troubleshooting Guide

Solutions for common configuration issues encountered during tutorials on macOS and Windows environments.

• CMake 4.2.2
  Pedro provided CMakeLists.txt replaces create_{default_}target_launcher() by set_debugger_working_dir()
  (This CMakeLists.txt improves TUT/external/glfw-3.1.2).
  Mingyu provided CMakeLists.txt
  for Project 1 set up CMakeLists.txt
• macOS / iOS .cpp File Configuration

  Uncomment the following line to satisfy macOS requirements (not needed by other operating systems):

  glfwWindowHint(GLFW_OPENGL_FORWARD_COMPAT, GL_TRUE);

  Only if needed, change line 487 of LoadOGLCore.mm from:

  gl_dyld = dlopen("OpenGL", RTLD_LAZY);

  To:

  gl_dyld = dlopen("/System/Library/Frameworks/OpenGL.framework/OpenGL", RTLD_LAZY);

• Xcode Compiles but Does Not Start Automatically

  Set your execution target using the following path configuration:

  Product → Scheme → Edit Scheme → Executable dropdown → Select tutorial (e.g., tutorial02_red_triangle)

• "glfw3.h not found" Error

  Update your include path statement from:

  #include "glfw3.h"

  To:

  #include "GLFW/glfw3.h"

• AntTweakBar Errors (Upper Left Corner Box)

  Ignore errors or completely remove AntTweakBar code snippets across your project files:

  Line 22:

  #include <AntTweakBar.h>

  Lines ~160-165:

  TwInit(TW_OPENGL_CORE, NULL);
  TwWindowSize(window_width, window_height);
  TwBar * GUI = TwNewBar("Picking");
  TwSetParam(GUI, NULL, "refresh", TW_PARAM_CSTRING, 1, "0.1");
  TwAddVarRW(GUI, "Last picked object", TW_TYPE_STDSTRING, &gMessage, NULL);

  Line ~438:

  TwDraw();

  If you encounter an error with Vertices in CreateObjects() (occurs on specific versions of macOS), use Vertex SetCoords() and SetColor() instead:

  float position0[] = {1.0f, 1.0f, 0.0f, 1.0f};
  float color0[] = { 1.0f, 0.0f, 0.0f, 1.0f };
  Vertices[0].SetCoords(position0);
  Vertices[0].SetColor(color0);

• Missing C++ Toolchain in Xcode

  When installing Xcode, ensure you include the C++ library toolchain (often Clang). Missing compilers result in build errors. If you skipped this setup step during download, execute the following commands in your terminal:

  sudo xcode-select --install
  sudo xcode-select -s /Library/Developer/CommandLineTools
  sudo xcode-select --reset

• External Reference Solutions & Window Bugs
  Argument Outside Error Resolution Simulator Setup Tutorial

  Note on tutorial01_first_window: If the window fails to display text or artifacts on macOS, it may stay blank or close. macOS systems occasionally suppress empty window initialization loops when no graphic payloads are rendered.

Windows & System Troubleshooting

• Dual Graphics Cards: "OpenGL 3.3 Not Supported" Error

  This happens when your PC defaults to an energy-saving, low-end integrated card instead of your dedicated high-end GPU.

  Quick Hack: Right-click your compiled .exe file and manually select your high-end graphics card.

  Long-term Solution: Set your high-end graphics processor as system-wide default via your NVIDIA Control Panel or AMD Radeon Software interface.

• Intel GPU: "Failed to Open the GLFW Window"

  Legacy integrated Intel chipsets sometimes fail OpenGL 3.3 compliance.

  Important: Ignore old advice suggesting a rollback to version 2.1 of the tutorials. Do NOT switch down to version 2.1.

• OneDrive: "Network Problem" Execution Errors

  Compiled binaries run into file-lock conflicts inside automated cloud storage directories. Ensure your codebase workspace directory is stored natively locally on your primary device storage root, and do not run development projects straight from OneDrive.

• Visual Studio 15 Community: "C Compiler Not Found" Error

  You must explicitly include desktop C++ packages during installation for the target compiler pipelines to run. It is highly recommended to upgrade to a newer release. IDE setups utilizing Visual Studio 17 or Visual Studio 19 operate smoothly out-of-the-box.