Fall back to the NULL platform when no display is available

Project.toml

@@ -1,7 +1,7 @@
 author = ["Jay Petacat <jay@jayschwa.net>", "Simon Danisch <sdanisch@gmail.com>"]
 name = "GLFW"
 uuid = "f7f18e0c-5ee9-5ccd-a5bf-e8befd85ed98"
-version = "3.4.6"
+version = "3.4.7"
 
 [deps]
 GLFW_jll = "0656b61e-2033-5cc2-a64a-77c0f6c09b89"

README.md

@@ -44,6 +44,8 @@ Read the [GLFW documentation][docs] for detailed instructions on how to use the
 
 * Clipboard (`glfwGetClipboard`, `glfwSetClipboard`) and time (`glfwGetTime`, `glfwSetTime`) functions have been omitted because Julia's standard library already supports similar functionality.
 * `glfwInit` and `glfwTerminate` are called automatically using the `__init__` and `atexit` functions. While it is okay to still call them explicitly, it is redundant and not required.
+* If no display is available (headless CI, cluster or batch nodes), loading the package warns and falls back to GLFW's NULL platform instead of throwing, so packages that depend on GLFW still load. Windows cannot be created or shown in that state; check for it with `GLFW.GetPlatform() == GLFW.PLATFORM_NULL`.
+* The `JULIA_GLFW_PLATFORM` environment variable (`"win32"`, `"cocoa"`, `"wayland"`, `"x11"`, `"null"`, or `"any"`) forces a specific platform. An explicitly requested platform is honored as stated: if it cannot be initialized, loading the package fails rather than falling back.
 * Thread restrictions are explicitly checked and throw errors when they are not respected. This can be turned off by setting `GLFW.ENABLE_THREAD_ASSERTIONS[] = false` or by setting an environment variable of the same name.
 
 [docs]: https://www.glfw.org/docs/latest/

src/GLFW.jl

@@ -56,10 +56,30 @@ function __init__()
 		Init()
 	catch err
 		push!(errors, err)
-	finally
-		SetErrorCallback(throw)
 	end
 
+	# Without a display server (headless CI, cluster nodes, batch jobs) the
+	# default platform fails and loading the package would throw. Fall back
+	# to the NULL platform so the package still loads; windows cannot be
+	# created there, and `GetPlatform() == PLATFORM_NULL` lets downstream
+	# code detect that it is headless. An explicitly requested platform is
+	# honored as stated: if JULIA_GLFW_PLATFORM is set and does not work,
+	# loading fails rather than being second-guessed.
+	if !is_initialized() && !haskey(ENV, "JULIA_GLFW_PLATFORM") && PlatformSupported(PLATFORM_NULL)
+		try
+			Init(platform = PLATFORM_NULL)
+			@warn "GLFW could not connect to a display and fell back to its NULL platform: " *
+			      "the package is usable, but windows cannot be created or shown. Detect this " *
+			      "with `GLFW.GetPlatform() == GLFW.PLATFORM_NULL`. To make a missing display " *
+			      "fatal again, set the JULIA_GLFW_PLATFORM environment variable to the " *
+			      "required platform (e.g. \"x11\")."
+		catch err
+			push!(errors, err)
+		end
+	end
+
+	SetErrorCallback(throw)
+
 	if is_initialized()
 		atexit(Terminate)
 		for err in errors

test/runtests.jl

@@ -15,6 +15,24 @@ println(GLFW.GetVersionString())
 @test GLFW.RELEASE == false
 @test false == GLFW.RELEASE
 
+if Sys.islinux()
+	# Loading with no display must not throw: __init__ falls back to the
+	# NULL platform (#169, #200, #253). Checked in a subprocess so this
+	# process's initialized GLFW is not disturbed.
+	base = `$(Base.julia_cmd()) --project=$(Base.active_project()) --startup-file=no`
+	env = copy(ENV)
+	delete!(env, "DISPLAY")
+	delete!(env, "WAYLAND_DISPLAY")
+	delete!(env, "JULIA_GLFW_PLATFORM")
+	check = "using GLFW; print(GLFW.is_initialized() && GLFW.GetPlatform() == GLFW.PLATFORM_NULL)"
+	@test read(setenv(`$base -e $check`, env), String) == "true"
+
+	# An explicitly requested platform that cannot work must still fail.
+	env["JULIA_GLFW_PLATFORM"] = "x11"
+	failing = setenv(`$base -e "using GLFW"`, env)
+	@test !success(pipeline(failing, stdout = devnull, stderr = devnull))
+end
+
 if !haskey(ENV, "CI")  # AppVeyor and Travis CI don't support OpenGL
 	include("windowclose.jl")
 end