Add toolsetpath API for specifying tool executable paths

Introduces a new API function `toolsetpath(toolsetName, toolName,
toolPath)` that allows users to specify custom paths for tool
executables within their Premake scripts.

This provides a mechanism to override the default tool lookup behavior
for specific toolsets and tools, offering greater flexibility in build
configurations.

Changes include:
- Registering the `toolsetpaths` field in `_premake_init.lua` to store
the custom paths.
- Implementing the `toolsetpath` function in `base/api.lua` to process
and store the provided paths.
- Modifying the `gettoolname` functions in the GCC, Clang, MSVC, SNC,
.NET, and Emscripten toolset modules to check for and use paths defined
via `toolsetpaths` before falling back to default lookup logic.
- Adding tests in the corresponding toolset test files (`tests/tools/`)
to verify that the `toolsetpath` setting correctly overrides the default
behavior.
- Creating a new documentation page (`website/docs/toolsetpath.md`)
detailing the API function, its parameters, and usage.
- Adding an entry for the new documentation page in the website sidebar
(`website/sidebars.js`).

Author: tritao

src/_premake_init.lua

@@ -923,6 +923,14 @@
 		end,
 	}
 
+	api.register {
+		name = "toolsetpaths",
+		scope = "config",
+		kind = "keyed:keyed:path", -- { toolset_name = { tool_name = path } }
+		tokens = true,
+		pathVars = true,
+	}
+
 	api.register {
 		name = "undefines",
 		scope = "config",

src/base/api.lua

@@ -1205,3 +1205,40 @@
 	function newoption(opt)
 		p.option.add(opt)
 	end
+
+
+---
+-- Set the path for a specific tool within a toolset.
+--
+-- @param toolsetName
+--    The name of the toolset (e.g., "gcc", "clang").
+-- @param toolName
+--    The name of the tool (e.g., "cc", "cxx", "ld").
+-- @param toolPath
+--    The path to the tool executable.
+---
+function toolsetpath(toolsetName, toolName, toolPath)
+	local cfg = api.scope.current
+	if not cfg then
+		error("toolsetpath must be called within a configuration block", 2)
+	end
+
+	-- Get the toolsetpaths field definition
+	local field = p.field.get("toolsetpaths")
+	if not field then
+		error("toolsetpaths field not registered", 2)
+	end
+
+	-- Construct the data table
+	local data = {
+		[toolsetName] = {
+			[toolName] = toolPath
+		}
+	}
+
+	-- Store the data using configset.store
+	local status, err = configset.store(cfg, field, data)
+	if err then
+		error(err, 2)
+	end
+end

src/tools/clang.lua

@@ -350,6 +350,11 @@
 	}
 
 	function clang.gettoolname(cfg, tool)
+		-- Check toolsetpaths first
+		if cfg.toolsetpaths and cfg.toolsetpaths[cfg.toolset] and cfg.toolsetpaths[cfg.toolset][tool] then
+			return cfg.toolsetpaths[cfg.toolset][tool]
+		end
+
 		local toolset, version = p.tools.canonical(cfg.toolset or p.CLANG)
 		local value = clang.tools[tool]
 		if type(value) == "function" then

src/tools/cosmocc.lua

@@ -23,5 +23,10 @@ cosmocc.tools = {
 }
 
 function cosmocc.gettoolname(cfg, tool)
+	-- Check toolsetpaths first
+	if cfg.toolsetpaths and cfg.toolsetpaths[cfg.toolset] and cfg.toolsetpaths[cfg.toolset][tool] then
+		return cfg.toolsetpaths[cfg.toolset][tool]
+	end
+
     return cosmocc.tools[tool]
 end

src/tools/dotnet.lua

@@ -255,6 +255,11 @@
 --
 
 	function dotnet.gettoolname(cfg, tool)
+		-- Check toolsetpaths first
+		if cfg.toolsetpaths and cfg.toolsetpaths[cfg.toolset] and cfg.toolsetpaths[cfg.toolset][tool] then
+			return cfg.toolsetpaths[cfg.toolset][tool]
+		end
+
 		local compilers = {
 			msnet = "csc",
 			mono = "mcs",

src/tools/emcc.lua

@@ -22,7 +22,13 @@ emcc.tools = {
 -- flags correctly to emcc builds.
 emcc.shared.profile = nil
 emcc.ldflags.profile = nil
+emcc.getsharedlibarg = function(cfg) return "" end
 
 function emcc.gettoolname(cfg, tool)
+	-- Check toolsetpaths first
+	if cfg.toolsetpaths and cfg.toolsetpaths[cfg.toolset] and cfg.toolsetpaths[cfg.toolset][tool] then
+		return cfg.toolsetpaths[cfg.toolset][tool]
+	end
+
 	return emcc.tools[tool]
 end

src/tools/gcc.lua

@@ -706,6 +706,11 @@
 	}
 
 	function gcc.gettoolname(cfg, tool)
+		-- Check toolsetpaths first
+		if cfg.toolsetpaths and cfg.toolsetpaths[cfg.toolset] and cfg.toolsetpaths[cfg.toolset][tool] then
+			return cfg.toolsetpaths[cfg.toolset][tool]
+		end
+
 		local toolset, version = p.tools.canonical(cfg.toolset or p.GCC)
 		if toolset == p.tools.gcc and version ~= nil then
 			version = "-" .. version

src/tools/msc.lua

@@ -479,6 +479,11 @@
 --
 
 	function msc.gettoolname(cfg, tool)
+		-- Check toolsetpaths first
+		if cfg.toolsetpaths and cfg.toolsetpaths[cfg.toolset] and cfg.toolsetpaths[cfg.toolset][tool] then
+			return cfg.toolsetpaths[cfg.toolset][tool]
+		end
+
 		return nil
 	end
 

src/tools/snc.lua

@@ -139,6 +139,11 @@
 	}
 
 	function snc.gettoolname(cfg, tool)
+		-- Check toolsetpaths first
+		if cfg.toolsetpaths and cfg.toolsetpaths[cfg.toolset] and cfg.toolsetpaths[cfg.toolset][tool] then
+			return cfg.toolsetpaths[cfg.toolset][tool]
+		end
+
 		local names = snc.tools[cfg.architecture] or snc.tools[cfg.system] or {}
 		return names[tool]
 	end

tests/tools/test_clang.lua

@@ -48,6 +48,16 @@
 		test.isequal("windres-16", clang.gettoolname(cfg, "rc"))
 	end
 
+--
+-- Verify that toolsetpath overrides the default tool name.
+--
+function suite.toolsetpathOverridesDefault()
+	toolset "clang"
+	toolsetpath("clang", "cc", "/path/to/my/custom/clang")
+	prepare()
+	test.isequal("/path/to/my/custom/clang", clang.gettoolname(cfg, "cc"))
+end
+
 --
 -- Check Mac OS X deployment target flags
 --

tests/tools/test_dotnet.lua

@@ -45,6 +45,16 @@
 		test.isequal("csc", dotnet.gettoolname(cfg, "csc"))
 	end
 
+--
+-- Verify that toolsetpath overrides the default tool name.
+--
+function suite.toolsetpathOverridesDefault()
+	toolset "dotnet"
+	toolsetpath("dotnet", "csc", "/path/to/my/custom/csc")
+	prepare()
+	test.isequal("/path/to/my/custom/csc", dotnet.gettoolname(cfg, "csc"))
+end
+
 
 --
 -- Check support for the `csversion` API

tests/tools/test_emcc.lua

@@ -46,3 +46,13 @@ function suite.tools_onWASM64()
 	test.isequal("wasm64", cfg.architecture)
 end
 
+--
+-- Verify that toolsetpath overrides the default tool name.
+--
+function suite.toolsetpathOverridesDefault()
+	toolset "emcc"
+	toolsetpath("emcc", "cc", "/path/to/my/custom/emcc")
+	prepare()
+	test.isequal("/path/to/my/custom/emcc", emcc.gettoolname(cfg, "cc"))
+end
+

tests/tools/test_gcc.lua

@@ -66,6 +66,16 @@
 		test.isequal("windres-16", gcc.gettoolname(cfg, "rc"))
 	end
 
+--
+-- Verify that toolsetpath overrides the default tool name.
+--
+function suite.toolsetpathOverridesDefault()
+	toolset "gcc"
+	toolsetpath("gcc", "cc", "/path/to/my/custom/gcc")
+	prepare()
+	test.isequal("/path/to/my/custom/gcc", gcc.gettoolname(cfg, "cc"))
+end
+
 --
 -- By default, the -MMD -MP are used to generate dependencies.
 --

tests/tools/test_msc.lua

@@ -26,6 +26,16 @@
 	end
 
 
+--
+-- Verify that toolsetpath overrides the default tool name.
+--
+function suite.toolsetpathOverridesDefault()
+	toolset "msc"
+	toolsetpath("msc", "cc", "C:/path/to/my/custom/cl.exe")
+	prepare()
+	test.isequal("C:/path/to/my/custom/cl.exe", msc.gettoolname(cfg, "cc"))
+end
+
 --
 -- Check the optimization flags.
 --

tests/tools/test_snc.lua

@@ -45,6 +45,16 @@
 		test.isnil(snc.gettoolname(cfg, "ar"))
 	end
 
+--
+-- Verify that toolsetpath overrides the default tool name.
+--
+function suite.toolsetpathOverridesDefault()
+	toolset "snc"
+	toolsetpath("snc", "cc", "/path/to/my/custom/snc_cc")
+	prepare()
+	test.isequal("/path/to/my/custom/snc_cc", snc.gettoolname(cfg, "cc"))
+end
+
 
 --
 -- By default, the -MMD -MP are used to generate dependencies.

website/docs/toolsetpath.md

@@ -0,0 +1,41 @@
+Specifies the path to a specific tool executable for a given toolset. This allows overriding the default tool lookup behavior of Premake.
+
+```lua
+toolsetpath(toolsetName, toolName, toolPath)
+```
+
+### Parameters
+
+`toolsetName`
+:   The name of the toolset (e.g., `"gcc"`, `"clang"`, `"msc"`).
+
+`toolName`
+:   The name of the tool within the toolset (e.g., `"cc"` for C compiler, `"cxx"` for C++ compiler, `"ld"` for linker, `"ar"` for archiver).
+
+`toolPath`
+:   The absolute or relative path to the tool executable.
+
+### Applies To
+
+Project configurations.
+
+### Example
+
+```lua
+project "MyProject"
+	kind "ConsoleApp"
+	language "C++"
+	system "Linux"
+
+	configuration "Release"
+		toolset "gcc"
+		-- Specify a custom path for the GCC C++ compiler
+		toolsetpath("gcc", "cxx", "/opt/my_custom_gcc/bin/g++")
+
+	configuration "Debug"
+		toolset "clang"
+		-- Specify a custom path for the Clang C compiler
+		toolsetpath("clang", "cc", "/usr/local/clang-15/bin/clang")
+```
+
+In this example, the `toolsetpath` function is used to specify custom paths for the C++ compiler in the "Release" configuration (using GCC) and the C compiler in the "Debug" configuration (using Clang).

website/sidebars.js

@@ -271,6 +271,7 @@ module.exports = {
 						'thumbmode',
 						'toolchainversion',
 						'toolset',
+						'toolsetpath',
 						'toolsversion',
 						'undefines',
 						'usage',