Requireopt

src/base/globals.lua

@@ -74,19 +74,34 @@
 -- @param versions
 --    An optional version criteria string; see premake.checkVersion()
 --    for more information on the format.
+-- @param silent
+--		By default, the require function throws an error when the
+--		module could not be loaded.
+--		If silent is true, the function will just return false and the error message. 
 -- @return
 --    If successful, the loaded module, which is also stored into the
 --    global package.loaded table.
 ---
 
-	premake.override(_G, "require", function(base, modname, versions)
+	premake.override(_G, "require", function(base, modname, versions, silent)
 		local result, mod = pcall(base,modname)
 		if not result then
+			if silent then
+				return result, mod
+			end
 			error(mod, 3)
 		end
 		if mod and versions and not premake.checkVersion(mod._VERSION, versions) then
-			error(string.format("module %s %s does not meet version criteria %s",
-				modname, mod._VERSION or "(none)", versions), 3)
+			local message = string.format("module %s %s does not meet version criteria %s",
+				modname, mod._VERSION or "(none)", versions)
+			if silent then
+				return false, message
+			end 
+			error(message, 3)
 		end
 		return mod
 	end)
+
+	function requireopt(modname, versions)
+		return require(modname, versions, true)	
+	end

tests/_tests.lua

@@ -10,6 +10,7 @@ return {
 	"base/test_detoken.lua",
 	"base/test_include.lua",
 	"base/test_module_loader.lua",
+	"base/test_module_loader_silent.lua",
 	"base/test_option.lua",
 	"base/test_os.lua",
 	"base/test_override.lua",

tests/base/test_module_loader_silent.lua

@@ -0,0 +1,31 @@
+--
+-- tests/base/test_module_loader_silent.lua
+-- Test the custom module loader with silent option.
+-- Copyright (c) 2012-2022 Jason Perkins and the Premake project
+--
+
+	local p = premake
+	local suite = test.declare("module_loader_silent")
+
+--
+-- Setup
+--
+
+	function suite.setup()
+	end
+
+	function suite.teardown()
+	end
+
+--
+-- Check that premake's module loader will failed to
+-- load module silently
+--
+
+	function suite.silentLoadingFailure()
+		local result, msg = require("i-am-not-a-module", nil, true)
+		test.isfalse(result)
+		p.w(msg)
+		test.capture("module 'i-am-not-a-module' not found")
+	end
+

website/docs/globals/require.md

@@ -1,7 +1,7 @@
 An extension of [Lua's require() function](http://www.lua.org/pil/8.1.html) which adds support for Premake modules and version checking.
 
 ```lua
-require ("modname", "versions")
+require ("modname", "versions", silent)
 ```
 
 Premake will use its [extended set of module locations](Locating-Scripts.md) when locating the requested module.
@@ -12,10 +12,12 @@ Premake will use its [extended set of module locations](Locating-Scripts.md) whe
 
 `versions` is an optional string of a version requirements. See the examples below for more information on the format of the requirements string. If the requirements are not met, an error will be raised.
 
+`silent` is not set or set to false, the require function will raise an error if the module fails to load or the version does not meet the criteria set by versions. If silent is set to true, then require shall return a tuple of false and the error message.
+
 
 ### Returns ###
 
-The module object.
+The module object on success, `false, error_message` on error when `silent` is set.
 
 
 ### Availability ###
@@ -59,3 +61,4 @@ require("foo", ">=1.1")
 ### See Also ###
 
 * [_PREMAKE_VERSION](globals/premake_PREMAKE_VERSION.md)
+* [requireopt](globals/requireopt.md)

website/docs/globals/requireopt.md

@@ -0,0 +1,28 @@
+Require a module or return `false` if module could not be loaded.
+
+
+```lua
+requireopt ("modname", "versions")
+```
+
+`requireopt` is an alias of `require(modname, versions, true)`
+
+### Returns ###
+
+* The module on success
+* `false`, `error_message` on error
+
+### Examples ###
+
+```
+local optionalmodule, message = requireopt "not-mandatory-but-recommended"
+if not optionalmodule
+then
+	premake.warn ("You will not run this at full power: " .. message)
+end
+```
+
+### See Also ###
+
+* [require](require.md)
+* [dofileopt](dofileopt.md)