Add glfwInitHint

This allows setting hints that control how the library is initialized,
transforming more compile-time options into run-time ones.

docs/compile.dox

@@ -219,17 +219,6 @@ __GLFW_VULKAN_STATIC__ determines whether to use the Vulkan loader linked
 statically into the application.
 
 
-@subsubsection compile_options_osx macOS specific CMake options
-
-@anchor GLFW_USE_CHDIR
-__GLFW_USE_CHDIR__ determines whether @ref glfwInit changes the current
-directory of bundled applications to the `Contents/Resources` directory.
-
-@anchor GLFW_USE_MENUBAR
-__GLFW_USE_MENUBAR__ determines whether the first call to @ref glfwCreateWindow
-sets up a minimal menu bar.
-
-
 @subsubsection compile_options_win32 Windows specific CMake options
 
 @anchor USE_MSVC_RUNTIME_LIBRARY_DLL
@@ -281,14 +270,6 @@ For the EGL context creation API, the following options are available:
  - @b _GLFW_USE_EGLPLATFORM_H to use `EGL/eglplatform.h` for native handle
    definitions (fallback)
 
-If you are using the Cocoa window creation API, the following options are
-available:
-
- - @b _GLFW_USE_CHDIR to `chdir` to the `Resources` subdirectory of the
-   application bundle during @ref glfwInit (recommended)
- - @b _GLFW_USE_MENUBAR to create and populate the menu bar when the first window
-   is created (recommended)
-
 @note None of the @ref build_macros may be defined during the compilation of
 GLFW.  If you define any of these in your build files, make sure they are not
 applied to the GLFW sources.

docs/context.dox

@@ -84,10 +84,9 @@ objects are recommended for rendering with such contexts.
 You should still [process events](@ref events) as long as you have at least one
 window, even if none of them are visible.
 
-@macos The first time a window is created the menu bar is populated with
-common commands like Hide, Quit and About.  This is not desirable for example
-when writing a command-line only application.  The menu bar setup can be
-disabled with a [compile-time option](@ref compile_options_osx).
+@macos The first time a window is created the menu bar is created.  This is not
+desirable for example when writing a command-line only application.  Menu bar
+creation can be disabled with the @ref GLFW_COCOA_MENUBAR init hint.
 
 
 @subsection context_less Windows without contexts

docs/intro.dox

@@ -31,6 +31,7 @@ successfully initialized, and only from the main thread.
  - @ref glfwGetVersion
  - @ref glfwGetVersionString
  - @ref glfwSetErrorCallback
+ - @ref glfwInitHint
  - @ref glfwInit
  - @ref glfwTerminate
 
@@ -61,6 +62,42 @@ allocated by programs that simply exit, but GLFW sometimes has to change global
 system settings and these might not be restored without termination.
 
 
+@subsection init_hints Initialization hints
+
+There are a number of hints that can be set before initialization, that affect
+how the library behaves.
+
+The values you set are not affected by initialization or termination, but they
+are only read during initialization.  Once GLFW has been initialized, setting
+new hint values will not affect behavior until the next time it is terminated
+and initialized.
+
+Some hints are platform specific.  These are always valid to set on any
+platform but they will only affect their specific platform.  Other platforms
+will simply ignore them.  Setting these hints requires no platform specific
+headers or calls.
+
+
+@subsubsection init_hints_osx macOS specific hints
+
+@anchor GLFW_COCOA_CHDIR_RESOURCES
+__GLFW_COCOA_CHDIR_RESOURCES__ specifies whether to set the current directory to
+the application to the `Contents/Resources` subdirectory of the application's
+bundle, if present. 
+
+@anchor GLFW_COCOA_MENUBAR
+__GLFW_COCOA_MENUBAR__ specifies whether to create a basic menu bar when the
+first window is created, which is when AppKit is initialized.
+
+
+@subsubsection init_hints_values Supported and default values
+
+Init hint                       | Default value | Supported values
+------------------------------- | ------------- | ----------------
+@ref GLFW_COCOA_CHDIR_RESOURCES | `GLFW_TRUE`   | `GLFW_TRUE` or `GLFW_FALSE`
+@ref GLFW_COCOA_MENUBAR         | `GLFW_TRUE`   | `GLFW_TRUE` or `GLFW_FALSE`
+
+
 @subsection intro_init_terminate Terminating GLFW
 
 Before your application exits, you should terminate the GLFW library if it has

docs/news.dox

@@ -25,6 +25,14 @@ GLFW now supports changing the [GLFW_DECORATED](@ref GLFW_DECORATED_attrib),
 windows with @ref glfwSetWindowAttrib.
 
 
+@subsection news_33_inithint Support for initialization hints
+
+GLFW now supports setting library initialization hints with @ref glfwInitHint.
+Currently the macOS specific @ref
+GLFW_COCOA_CHDIR_RESOURCES and @ref GLFW_COCOA_MENUBAR init hints are supported,
+replacing the corresponding compile-time options.
+
+
 @subsection news_33_centercursor Cursor centering window hint
 
 GLFW now supports controlling whether the cursor is centered over newly created