Enable msbuild batching for custom rules (#2141)

* Enable msbuild batching for custom rules

add `rule.inputs` and `rule.outputs` pathVars
add test cases
add documentation

* renaming token to `file.ruleinputs`, excluding outputs for now.

Author: cathei

modules/vstudio/tests/vc2010/test_rule_props.lua

@@ -38,6 +38,10 @@
 				'%{output_path}%{file.basename}.example.cc',
 				'%{output_path}%{file.basename}.example.h'
 			}
+			builddependencies {
+				'dependency_1.lib',
+				'dependency_2.lib',
+			}
 	end
 
 
@@ -68,3 +72,16 @@
 		]]
 	end
 
+
+--
+-- additionalDependencies
+--
+
+	function suite.additionalDependencies()
+		local r = test.getRule("example")
+		m.additionalDependencies(r)
+
+		test.capture [[
+<AdditionalDependencies>dependency_1.lib;dependency_2.lib</AdditionalDependencies>
+		]]
+	end

modules/vstudio/tests/vc2010/test_rule_targets.lua

@@ -95,3 +95,55 @@
 </UsingTask>
 		]]
 	end
+
+
+
+--
+-- ruleTask
+--
+
+	function suite.ruleTask()
+		local r = test.getRule("example")
+		m.rule(r)
+
+		test.capture [[
+<example
+	Condition="'@(example)' != '' and '%(example.ExcludedFromBuild)' != 'true'"
+	CommandLineTemplate="%(example.CommandLineTemplate)"
+	output_path="%(example.output_path)"
+	AdditionalOptions="%(example.AdditionalOptions)"
+	Inputs="@(example)"
+	StandardOutputImportance="High"
+	StandardErrorImportance="High" />
+		]]
+	end
+
+
+
+--
+-- targetInputs
+--
+
+	function suite.targetInputs()
+		local r = test.getRule("example")
+		m.targetInputs(r)
+
+		test.capture [[
+Inputs="@(example);%(example.AdditionalDependencies);$(MSBuildProjectFile)"
+		]]
+	end
+
+
+
+--
+-- targetOutputs
+--
+
+	function suite.targetOutputs()
+		local r = test.getRule("example")
+		m.targetOutputs(r)
+
+		test.capture [[
+Outputs="@(example->'%(Outputs)')"
+		]]
+	end

modules/vstudio/vs2010.lua

@@ -36,6 +36,7 @@
 		["file.reldirectory"]           = { absolute = false, token = "%(RelativeDir)" },
 		["file.extension"]              = { absolute = false, token = "%(Extension)" },
 		["file.name"]                   = { absolute = false, token = "%(Filename)%(Extension)" },
+		["file.ruleinputs"]            	= { absolute = false, token = "[Inputs]" },
 	}
 
 

modules/vstudio/vs2010_rules_targets.lua

@@ -294,7 +294,7 @@
 
 
 	function m.inputs(r)
-		p.w('Inputs="%%(%s.Identity)"', r.name)
+		p.w('Inputs="@(%s)"', r.name)
 	end
 
 
@@ -410,7 +410,7 @@
 			end
 		end
 		extra = table.concat(extra)
-		p.w('Inputs="%%(%s.Identity);%%(%s.AdditionalDependencies);%s$(MSBuildProjectFile)"', r.name, r.name, extra)
+		p.w('Inputs="@(%s);%%(%s.AdditionalDependencies);%s$(MSBuildProjectFile)"', r.name, r.name, extra)
 	end
 
 
@@ -422,7 +422,7 @@
 
 
 	function m.targetOutputs(r)
-		p.w('Outputs="%%(%s.Outputs)"', r.name)
+		p.w('Outputs="@(%s->\'%%(Outputs)\')"', r.name)
 	end
 
 

src/base/fileconfig.lua

@@ -298,3 +298,11 @@
 	function fcfg_mt.extension(fcfg)
 		return path.getextension(fcfg.abspath)
 	end
+
+
+	function fcfg_mt.ruleinputs(fcfg)
+		-- fallback for batch rule inputs
+		return fcfg.relpath
+	end
+
+

website/docs/Custom-Rules.md

@@ -72,3 +72,14 @@ project "MyProject"
       StripDebugInfo = true
     }
 ```
+
+## Rule Batching
+
+With MSBuild, custom rules can be batched if same properties are used. To enable this, use `file.ruleinputs` tokens in `buildcommands`. If corresponding `buildoutputs` is up-to-date to the input, then the input will be omitted. This token falls back to `file.relpath` on unsupported environment.
+
+```lua
+rule "BatchRule"
+  fileextension ".xyz"
+  buildcommands "MyProcessor.exe %{file.ruleinputs}"
+```
+

website/docs/Tokens.md

@@ -54,6 +54,7 @@ file.reldirectory
 file.name
 file.basename -- (file part without extension)
 file.extension -- (including '.'; eg ".cpp")
+file.ruleinputs -- (see custom rules)
 
 -- These values are available on build and link targets
 -- Replace [target] with one of "cfg.buildtarget" or "cfg.linktarget"