Merge branch 'master' into show-error-context-for-broken-include

modules/vstudio/tests/_tests.lua

@@ -14,6 +14,7 @@ return {
 	"cs2005/test_no_warn.lua",
 	"cs2005/test_debug_props.lua",
 	"cs2005/test_debug_props_2019.lua",
+	"cs2005/test_documentation_file.lua",
 	"cs2005/test_files.lua",
 	"cs2005/test_icon.lua",
 	"cs2005/test_netcore.lua",

modules/vstudio/tests/cs2005/test_documentation_file.lua

@@ -0,0 +1,85 @@
+--
+-- tests/actions/vstudio/cs2005/test_documentation_file.lua
+-- Test DocumentationFile feature Visual Studio 2005+ C# project.
+-- Copyright (c) 2012-2024 Jason Perkins and the Premake project
+--
+	local p = premake
+	local suite = test.declare("vstudio_cs2005_documentation_file")
+	local dn2005 = p.vstudio.dotnetbase
+--
+-- Setup
+--
+
+	local wks, prj
+
+--
+-- Setup and teardown
+--
+	function suite.setup()
+		p.action.set("vs2010")
+		wks = test.createWorkspace()
+	 	configurations { "Debug", "Release" }
+		language "C#"
+		targetdir("test/targetDir")
+	end
+
+	local function setConfig()
+		local cfg = test.getconfig(prj, "Debug")
+		dn2005.documentationfile(cfg);
+	end
+
+
+
+	local function prepare()
+		prj = test.getproject(wks, 1)
+	end
+
+function suite.documentationFilePath()
+	prepare()
+	documentationfile("test")
+	setConfig()
+	test.capture [[
+		<DocumentationFile>test\MyProject.xml</DocumentationFile>
+		]]
+end
+
+function suite.documentationFilePath_vs2017up()
+	p.action.set("vs2017")
+
+	prepare()
+	documentationfile("test")
+	setConfig()
+
+	test.capture [[
+		<DocumentationFile>test\MyProject.xml</DocumentationFile>
+		]]
+end
+
+function suite.documentationEmpty()
+	prepare()
+	documentationfile(true)
+	setConfig()
+
+	test.capture [[
+		<DocumentationFile>test\targetDir\MyProject.xml</DocumentationFile>
+		]]
+end
+
+function suite.documentationEmpty_vs2017up()
+	p.action.set("vs2017")
+
+	prepare()
+	documentationfile(true)
+	setConfig()
+
+	test.capture [[<GenerateDocumentationFile>true</GenerateDocumentationFile>]]
+end
+
+function suite.documentationNull()
+	wks = test.createWorkspace()
+	prepare()
+	setConfig()
+	test.isemptycapture()
+end
+
+

modules/vstudio/vs2005_csproj.lua

@@ -83,6 +83,7 @@
 			dotnetbase.compilerProps,
 			dotnetbase.additionalProps,
 			dotnetbase.NoWarn,
+			dotnetbase.documentationFile,
 		}
 	end
 

modules/vstudio/vs2005_dotnetbase.lua

@@ -778,6 +778,17 @@
 		end
 	end
 
+	function dotnetbase.documentationfile(cfg)
+		if cfg.documentationFile then
+			if _ACTION > "vs2015" and cfg.documentationFile == true then
+				_p(2,'<GenerateDocumentationFile>true</GenerateDocumentationFile>')
+			else
+				local documentationFile = iif(cfg.documentationFile ~= true, cfg.documentationFile, cfg.targetdir)
+				_p(2, string.format('<DocumentationFile>%s\\%s.xml</DocumentationFile>', vstudio.path(cfg, documentationFile),cfg.project.name))
+			end
+		end
+	end
+
 	function dotnetbase.isNewFormatProject(cfg)
 		local framework = cfg.dotnetframework
 		if not framework then

src/_premake_init.lua

@@ -766,6 +766,12 @@
 		}
 	}
 
+	api.register {
+		name = "documentationfile",
+		scope = "project",
+		kind = "string",
+	}
+
 	api.register {
 		name = "cdialect",
 		scope = "config",

src/base/tools.lua

@@ -59,3 +59,14 @@
 		local parts = identifier:explode("-", true, 1)
 		return p.tools[parts[1]], parts[2]
 	end
+
+
+--
+-- Returns the relative path to passed value for the given project.
+-- This can be overriden by actions to allow for more customized relative
+-- path behaviors.
+--
+
+	function p.tools.getrelative(prj, value)
+		return p.project.getrelative(prj, value)
+	end

src/tools/dotnet.lua

@@ -286,7 +286,7 @@
 		table.insert(flags, '/noconfig')
 
 		if cfg.project.icon then
-			local fn = project.getrelative(cfg.project, cfg.project.icon)
+			local fn = p.tools.getrelative(cfg.project, cfg.project.icon)
 			table.insert(flags, string.format('/win32icon:"%s"', fn))
 		end
 

src/tools/gcc.lua

@@ -289,7 +289,7 @@
 		local result = {}
 
 		table.foreachi(cfg.forceincludes, function(value)
-			local fn = project.getrelative(cfg.project, value)
+			local fn = p.tools.getrelative(cfg.project, value)
 			table.insert(result, string.format('-include %s', p.quoted(fn)))
 		end)
 
@@ -322,24 +322,24 @@
 	function gcc.getincludedirs(cfg, dirs, extdirs, frameworkdirs, includedirsafter)
 		local result = {}
 		for _, dir in ipairs(dirs) do
-			dir = project.getrelative(cfg.project, dir)
+			dir = p.tools.getrelative(cfg.project, dir)
 			table.insert(result, '-I' .. p.quoted(dir))
 		end
 
 		if table.contains(os.getSystemTags(cfg.system), "darwin") then
 			for _, dir in ipairs(frameworkdirs or {}) do
-				dir = project.getrelative(cfg.project, dir)
+				dir = p.tools.getrelative(cfg.project, dir)
 				table.insert(result, '-F' .. p.quoted(dir))
 			end
 		end
 
 		for _, dir in ipairs(extdirs or {}) do
-			dir = project.getrelative(cfg.project, dir)
+			dir = p.tools.getrelative(cfg.project, dir)
 			table.insert(result, '-isystem ' .. p.quoted(dir))
 		end
 
 		for _, dir in ipairs(includedirsafter or {}) do
-			dir = project.getrelative(cfg.project, dir)
+			dir = p.tools.getrelative(cfg.project, dir)
 			table.insert(result, '-idirafter ' .. p.quoted(dir))
 		end
 
@@ -370,18 +370,18 @@
 		-- test locally in the project folder first (this is the most likely location)
 		local testname = path.join(cfg.project.basedir, pch)
 		if os.isfile(testname) then
-			return project.getrelative(cfg.project, testname)
+			return p.tools.getrelative(cfg.project, testname)
 		else
 			-- else scan in all include dirs.
 			for _, incdir in ipairs(cfg.includedirs) do
 				testname = path.join(incdir, pch)
 				if os.isfile(testname) then
-					return project.getrelative(cfg.project, testname)
+					return p.tools.getrelative(cfg.project, testname)
 				end
 			end
 		end
 
-		return project.getrelative(cfg.project, path.getabsolute(pch))
+		return p.tools.getrelative(cfg.project, path.getabsolute(pch))
 	end
 
 --
@@ -535,14 +535,14 @@
 
 		if table.contains(os.getSystemTags(cfg.system), "darwin") then
 			for _, dir in ipairs(cfg.frameworkdirs) do
-				dir = project.getrelative(cfg.project, dir)
+				dir = p.tools.getrelative(cfg.project, dir)
 				table.insert(flags, '-F' .. p.quoted(dir))
 			end
 		end
 
 		if cfg.flags.RelativeLinks then
 			for _, dir in ipairs(config.getlinks(cfg, "siblings", "directory")) do
-				local libFlag = "-L" .. p.project.getrelative(cfg.project, dir)
+				local libFlag = "-L" .. p.tools.getrelative(cfg.project, dir)
 				if not table.contains(flags, libFlag) then
 					table.insert(flags, libFlag)
 				end

src/tools/msc.lua

@@ -280,7 +280,7 @@
 		local result = {}
 
 		table.foreachi(cfg.forceincludes, function(value)
-			local fn = project.getrelative(cfg.project, value)
+			local fn = p.tools.getrelative(cfg.project, value)
 			table.insert(result, "/FI" .. p.quoted(fn))
 		end)
 
@@ -298,12 +298,12 @@
 	function msc.getincludedirs(cfg, dirs, extdirs, frameworkdirs, includedirsafter)
 		local result = {}
 		for _, dir in ipairs(dirs) do
-			dir = project.getrelative(cfg.project, dir)
+			dir = p.tools.getrelative(cfg.project, dir)
 			table.insert(result, '-I' ..  p.quoted(dir))
 		end
 
 		for _, dir in ipairs(extdirs or {}) do
-			dir = project.getrelative(cfg.project, dir)
+			dir = p.tools.getrelative(cfg.project, dir)
 			if isVersionGreaterOrEqualTo(cfg.toolset, "msc-v142") then
 				table.insert(result, '/external:I' ..  p.quoted(dir))
 			else
@@ -312,7 +312,7 @@
 		end
 
 		for _, dir in ipairs(includedirsafter or {}) do
-			dir = project.getrelative(cfg.project, dir)
+			dir = p.tools.getrelative(cfg.project, dir)
 			if isVersionGreaterOrEqualTo(cfg.toolset, "msc-v142") then
 				table.insert(result, '/external:I' ..  p.quoted(dir))
 			else
@@ -394,7 +394,7 @@
 		local flags = {}
 		local dirs = table.join(cfg.libdirs, cfg.syslibdirs)
 		for i, dir in ipairs(dirs) do
-			dir = project.getrelative(cfg.project, dir)
+			dir = p.tools.getrelative(cfg.project, dir)
 			table.insert(flags, '/LIBPATH:"' .. dir .. '"')
 		end
 		return flags

website/docs/documentationfile.md

@@ -0,0 +1,46 @@
+Enables C# xmlDocumentationFile
+
+The `xmlDocumentationFile` option is used to include [XML comments](https://learn.microsoft.com/en-us/dotnet/csharp/language-reference/xmldoc/) in a DLL that has been included in a .NET framework or another C# project. These XML comments can then be referenced by other projects when placed alongside the corresponding SharedLib.
+
+This feature sets the [documentationfile](https://learn.microsoft.com/en-us/dotnet/csharp/language-reference/compiler-options/output#documentationfile) option in a C# project's .csproj file for each respective [configuration](https://premake.github.io/docs/configurations/)
+
+## Usage ##
+To use xmlDocumentationFile, add the following line to your project configuration in your premake script:
+
+```lua
+documentationfile("targetdir")
+```
+### Parameters ###
+`targetdir` is the directory where the documentation file should be placed after building the project using visual studio.
+
+### Examples ###
+
+When you set documentationFile to true, the following filepath will be generated:
+```%{targetdir}/%{prj.name}.xml```
+```lua
+documentationfile(true)
+```
+If you specify a custom target directory like this:
+```lua
+documentationfile("%{prj.location}/bin/test")
+```
+the following filepath will be generated:
+```bin\test\%{prj.name}.xml```
+### Applies To ###
+
+Project configurations.
+
+### Availability ###
+
+Premake 5.0 beta3 or later.
+
+Visual studio is the only toolset currently supported.
+
+### Warning ###
+It's recommended to use `documentationfile(true)` because Visual Studio's intellisense will not detect the XML file if its name is not the same as the SharedLib.
+
+### See Also ###
+For more information on XML documentation in C#, refer to:
+1) [xml comments](https://learn.microsoft.com/en-us/dotnet/csharp/language-reference/xmldoc/)
+2) [documentation file](https://learn.microsoft.com/en-us/dotnet/csharp/language-reference/compiler-options/output#documentationfile)
+3) [configuration](https://premake.github.io/docs/configurations/)

website/sidebars.js

@@ -133,6 +133,7 @@ module.exports = {
 						'display',
 						'docdir',
 						'docname',
+						'documentationfile',
 						'dofileopt',
 						'dotnetframework',
 						'dpiawareness',