diff --git a/src/base/globals.lua b/src/base/globals.lua index 90ab65c926..6ad91a0d05 100644 --- a/src/base/globals.lua +++ b/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 \ No newline at end of file diff --git a/tests/_tests.lua b/tests/_tests.lua index 0ceb983728..5f45ef14ad 100644 --- a/tests/_tests.lua +++ b/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", diff --git a/tests/base/test_module_loader_silent.lua b/tests/base/test_module_loader_silent.lua new file mode 100644 index 0000000000..f0bdfb2bad --- /dev/null +++ b/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 + \ No newline at end of file diff --git a/website/docs/globals/require.md b/website/docs/globals/require.md index 15d0be373a..f2235e8e6e 100644 --- a/website/docs/globals/require.md +++ b/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) diff --git a/website/docs/globals/requireopt.md b/website/docs/globals/requireopt.md new file mode 100644 index 0000000000..a89fc9b35b --- /dev/null +++ b/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)