Fix #1628 failing macOS os.findlib() test

src/base/os.lua

@@ -103,10 +103,26 @@
 		return path
 	end
 
-	function os.findlib(libname, libdirs)
-		-- libname: library name with or without prefix and suffix
-		-- libdirs: (array or string): A set of additional search paths
 
+---
+-- Attempt to locate and return the path to a shared library.
+--
+-- This function does not work to locate system libraries on macOS 11 or later; it may still
+-- be used to locate user libraries: _"New in macOS Big Sur 11.0.1, the system ships with
+-- a built-in dynamic linker cache of all system-provided libraries. As part of this change,
+-- copies of dynamic libraries are no longer present on the filesystem. Code that attempts to
+-- check for dynamic library presence by looking for a file at a path or enumerating a directory
+-- will fail."
+-- https://developer.apple.com/documentation/macos-release-notes/macos-big-sur-11_0_1-release-notes
+--
+-- @param libname
+--    The library name with or without prefix and suffix.
+-- @param libdirs
+--    An array of paths to be searched.
+-- @returns
+--    The full path to the library if found; `nil` otherwise.
+---
+	function os.findlib(libname, libdirs)
 		local path = get_library_search_path()
 		local formats
 
@@ -458,7 +474,7 @@
 --
 -- @param cmd Command to execute
 -- @param streams Standard stream(s) to output
--- 		Must be one of 
+-- 		Must be one of
 --		- "both" (default)
 --		- "output" Return standard output stream content only
 --		- "error" Return standard error stream content only

tests/base/test_os.lua

@@ -23,7 +23,10 @@
 --
 
 	function suite.findlib_FindSystemLib()
-		if os.istarget("windows") then
+		if os.istarget("macosx") then
+			-- macOS no longer stores system libraries on filesystem; see
+			-- https://developer.apple.com/documentation/macos-release-notes/macos-big-sur-11_0_1-release-notes
+		elseif os.istarget("windows") then
 			test.istrue(os.findlib("user32"))
 		elseif os.istarget("haiku") then
 			test.istrue(os.findlib("root"))
@@ -184,7 +187,7 @@
 			end
 		end
 	end
-	
+
 	-- Check outputof content
 	function suite.outputof_streams_output()
 		if (os.istarget("macosx")
@@ -198,12 +201,12 @@
 			test.isequal (oo, ob)
 			local s, e = string.find (oo, "test_os.lua")
 			test.istrue(s ~= nil)
-			
+
 			local o, e = os.outputof ("ls " .. cwd .. "/base", "error")
 			test.istrue(o == nil or #o == 0)
 		end
 	end
-	
+
 --
 -- os.translateCommand() tests
 --

website/docs/os.findlib.md

@@ -4,16 +4,21 @@ Scan the well-known system locations looking for a library file.
 p = os.findlib("libname" [, additionalpaths])
 ```
 
+This function does not work to locate system libraries on macOS 11 or later; it may still be used to locate user libraries. From [the release notes](https://developer.apple.com/documentation/macos-release-notes/macos-big-sur-11_0_1-release-notes):
+
+> New in macOS Big Sur 11.0.1, the system ships with a built-in dynamic linker cache of all system-provided libraries. As part of this change, copies of dynamic libraries are no longer present on the filesystem. Code that attempts to check for dynamic library presence by looking for a file at a path or enumerating a directory will fail.
+
 ### Parameters ###
 
-`libname` is name of the library to locate. It may be specified with (libX11.so) or without (X11) system-specific decorations.
+`libname` is name of the library to locate. It may be specified with (`libX11.so`) or without (`X11`) system-specific decorations.
+
+`additionalpaths` is a string or a table of one or more additional search path.
 
-`additionalpaths` is a string or a table of one or more additional search path
 ### Return Value ###
 
 The path containing the library file, if found. Otherwise, nil.
 
-
 ### Availability ###
 
-Premake 4.0 or later.
+Premake 4.0 or later. Non-macOS host systems only.
+