wx.Build.IBuildActionProvider Interface Reference

Inheritance diagram for wx.Build.IBuildActionProvider:

List of all members.

Public Member Functions
void	AppendToBooPreamble (BuildToolFamilyEnv env, List< string > importModules, List< string > booDeclarations, List< string > booDefinitions)
< paramname="env"> An opportunity for actions of the same family to share parameters.</param > < paramname="prerequisites"> This is a collection of maybe irrelevant build products that can be used by the action to create the target.</param > < paramname="target"> The target that shall be achieved by the action.</param > *IBuildAction	Create (BuildToolFamilyEnv env, IBuildProduct target, ICollection< IBuildProduct > prerequisites)
bool	MayContentFilePrerequisitesSuffice (ContentType target, ICollection< ContentType > prerequisites)
Properties
ICollection < OperatingSystem >	ApplicableOSs [get]
ICollection < ContentType >	ContentFileTargets [get]
string	Description [get]
bool	IsAvailable [get]
string	Name [get]
string	ToolFamily [get]
IDictionary< string, EnvironmentVarInfo >	UsedVars [get]

---

Detailed Description

Classes of build actions create objects that achieve certain build objects. Classes of build actions describe actions in term of symbolic targets and prerequisites as well as required content types and produced content types. These classes enable the runtime environment to investigate first, which actions are available to achieve content of a certain type.

The runtime will in fact implement a mixed fact/goal-oriented inference for the achievable goals. First, driven by the declared prerequisites, the runtime will infer the targets that are in principle achievable. The, for each of these targets, the runtime will generate a plan containing concrete build actions.

Please implement a default constructor, so that the activator is able to create instances.

These classes contain a Create() method that will create the build action for particular content files. Often, IBuildAction and IBuildActionClass will be implemented by the same class.

---

Member Function Documentation

void wx.Build.IBuildActionProvider.AppendToBooPreamble	(	BuildToolFamilyEnv	env,
		List< string >	importModules,
		List< string >	booDeclarations,
		List< string >	booDefinitions
	)

This will be called for any action provider before IBuildAction.AppendBooCode() is called. This provides action providers with the opportunity to import modules and create variables for global options.

Parameters:

	env	Environment containing status that can be shared among tools of the same family.
	importModules	List of modules that shall be imported. Add required modules here. Each module will be imported exactly once (even if it occurs more than once in the list).
	booDeclarations	Lines of code that will be added to the preamble of the BOO code. Please note, that each line may only appear once. All subsequent additions of this line of code will be ignored. These lines shall contain declarations of variables etc.
	booDefinitions	Lines of code that that will be added before the code provided by the actions to build the system. Typically, this will contain the definition of functions that are used on building. Lines starting with "import" will only be added once to the final code.

A typical use is the import of modules that will be used in the later BOO code that builds the project. Please take care on possible side effects on the BOO code of other action providers when declaring BOO variables.

            void AppendToBooPreamble(BuildToolFamilyEnv env, List<string> importModules, List<string> booDeclarations, List<string> booDefinitions)
            {
                booDeclarations.Add("# This option refers to tool XY. Supported values are 1, 2, and 3.");
                booDeclarations.Add("# However, this option actually does not have any effect. So you");
                booDeclarations.Add("# may fill in here whatever you like.")
                booDeclarations.Add("uselessOption = 1 # 1, 2, or 3")
            
                importModules.Add("System.Diagnostics");
                booDefinitions.Add("def RunThisSampleTool(targetName as string, sourceName as string):");
                booDefinitions.Add("  p=System.Diagnostics.Start(\"tool.exe\", \"-o targetName -i sourceName --option uselessOption\")");
                booDefinitions.Add("  p.WaitforExit()");
                boodefinitions.Add("");
            }

Now, imagine, that the action created by this provider implements the following BOO code creation (cf. IBuildAction.AppendBooCode()).

            void AppendBooCode(List<string> booCodeLines, BuildToolFamilyEnv env)
            {
                booCodeLines.Add(string.Format(\"RunThisSampleTool(\\\"0\\\", \\\"1\\\")\", this.Target.FileName, this.Source.FileName));
            }

This will result into the following code. Dots represent fragments that will be inserted by other action providers and actions. Declarations to be managed by the user of the resulting build program will be placed on top. The implementation of the build follows below.

                # This option refers to tool XY. Supported values are 1, 2, and 3.
                # However, this option actually does not have any effect. So you
                # may fill in here whatever you like.
                uselessOption = 1 # 1, 2, or 3
                ...
                booDefinitions.Add("import System.Diagnostics"); // I do not yet trust BOOs builtins
                def RunThisSampleTool(targetName as string, sourceName as string):
                  p=System.Diagnostics.Start("tool.exe", "-o {targetName} -i {sourceName} --option uselessOption")
                  p.WaitforExit()
                
                ...
                RunThisSampleTool("ATargetFile.obj", "ASourceFile.src")

Implemented in wx.Build.Cxx.GCC.GccAsCompiler, wx.Build.Cxx.GCC.GccAsLinker, wx.Build.Cxx.GCC.WindRes, wx.Build.Mono.Gmcs, wx.Build.MS.Cl, wx.Build.MS.Link, wx.Build.MS.RC, and wx.Build.MS.Csc.

<paramname="env"> An opportunity for actions of the same family to share parameters.</param><paramname="prerequisites"> This is a collection of maybe irrelevant build products that can be used by the action to create the target.</param><paramname="target"> The target that shall be achieved by the action.</param> * IBuildAction wx.Build.IBuildActionProvider.Create	(	BuildToolFamilyEnv	env,
		IBuildProduct	target,
		ICollection< IBuildProduct >	prerequisites
	)

Creates a particular build action achieving the provided targets provided that the specified prerequisites are known. This shall throw an System.ArgumentException if either targets or prerequisites do are not compatible with the declarations of this class or this class does not implement an actions providing the specified targets for some other reason. However, callers shall not rely on this.

If this action provider is only able to create specific instances of the fiel types as declared in ContentFileTargets , this method will return a null . In that case, this provider will be ignored silently.

The build environment will pass an occasionally empty instance of class BuildToolFamilyEnv where this may retrieve or store information that other tools of the same family have created before or other tools of the same family may use later. Actions MUST ALSO WORK when started with an empty environment.

Implemented in wx.Build.Net.CSharpCodeProvider, wx.Build.Cxx.GCC.GccAsCompiler, wx.Build.Cxx.GCC.GccAsLinker, wx.Build.Cxx.GCC.WindRes, wx.Build.Mono.Gmcs, wx.Build.MS.Cl, wx.Build.MS.Link, wx.Build.MS.RC, wx.Build.MS.Csc, and wx.Build.MS.Al.

bool wx.Build.IBuildActionProvider.MayContentFilePrerequisitesSuffice	(	ContentType	target,
		ICollection< ContentType >	prerequisites
	)

This returns true iff the described action is likely to produce the specified target provided that the specified prerequisites are available.

Implemented in wx.Build.Net.CSharpCodeProvider, wx.Build.Cxx.GCC.GccAsCompiler, wx.Build.Cxx.GCC.GccAsLinker, wx.Build.Cxx.GCC.WindRes, wx.Build.Mono.Gmcs, wx.Build.MS.Cl, wx.Build.MS.Link, wx.Build.MS.RC, wx.Build.MS.Csc, and wx.Build.MS.Al.

---

Property Documentation

ICollection<OperatingSystem> wx.Build.IBuildActionProvider.ApplicableOSs [get]

Implemented in wx.Build.Net.CSharpCodeProvider, wx.Build.Cxx.GCC.GccAsCompiler, wx.Build.Cxx.GCC.GccAsLinker, wx.Build.Cxx.GCC.WindRes, wx.Build.Mono.Gmcs, wx.Build.MS.Cl, wx.Build.MS.Link, wx.Build.MS.RC, wx.Build.MS.Csc, and wx.Build.MS.Al.

ICollection<ContentType> wx.Build.IBuildActionProvider.ContentFileTargets [get]

Content files that may be created by an action of this kind. This may be null or empty.

Implemented in wx.Build.Net.CSharpCodeProvider, wx.Build.Cxx.GCC.GccAsCompiler, wx.Build.Cxx.GCC.GccAsLinker, wx.Build.Cxx.GCC.WindRes, wx.Build.Mono.Gmcs, wx.Build.MS.Cl, wx.Build.MS.Link, wx.Build.MS.RC, wx.Build.MS.Csc, and wx.Build.MS.Al.

string wx.Build.IBuildActionProvider.Description [get]

A textual description of this class.

Implemented in wx.Build.Net.CSharpCodeProvider, wx.Build.Cxx.GCC.GccAsCompiler, wx.Build.Cxx.GCC.GccAsLinker, wx.Build.Cxx.GCC.WindRes, wx.Build.Mono.Gmcs, wx.Build.MS.Cl, wx.Build.MS.Link, wx.Build.MS.RC, wx.Build.MS.Csc, and wx.Build.MS.Al.

bool wx.Build.IBuildActionProvider.IsAvailable [get]

This may be false if actions of this class are note available (for some reasons that are not related to targets).

Implemented in wx.Build.Net.CSharpCodeProvider, wx.Build.Cxx.GCC.GccAsCompiler, wx.Build.Cxx.GCC.GccAsLinker, wx.Build.Cxx.GCC.WindRes, wx.Build.Mono.Gmcs, wx.Build.MS.Cl, wx.Build.MS.Link, wx.Build.MS.RC, wx.Build.MS.Csc, and wx.Build.MS.Al.

string wx.Build.IBuildActionProvider.Name [get]

The name of the action provider. This will be used in messages to the user. Please use exclusively alpha-numerical characters, the dot '.', or the underscore here.

Implemented in wx.Build.Net.CSharpCodeProvider, wx.Build.Cxx.GCC.GccAsCompiler, wx.Build.Cxx.GCC.GccAsLinker, wx.Build.Cxx.GCC.WindRes, wx.Build.Mono.Gmcs, wx.Build.MS.Cl, wx.Build.MS.Link, wx.Build.MS.RC, wx.Build.MS.Csc, and wx.Build.MS.Al.

string wx.Build.IBuildActionProvider.ToolFamily [get]

A name that some tools may share. This will be treated like Name when processing user input.

Tools belonging to the same family may share informations using the BuildToolFamilyEnv.

Implemented in wx.Build.Net.CSharpCodeProvider, wx.Build.Cxx.GCC.GccAsCompiler, wx.Build.Cxx.GCC.GccAsLinker, wx.Build.Cxx.GCC.WindRes, wx.Build.Mono.Gmcs, wx.Build.MS.Cl, wx.Build.MS.Link, wx.Build.MS.RC, wx.Build.MS.Csc, and wx.Build.MS.Al.

IDictionary<string, EnvironmentVarInfo> wx.Build.IBuildActionProvider.UsedVars [get]

This returns a description of the used shell variables or a null. The key is the variable name. The value is a remark. So, the following sample provides the declaration of using shell variable path.

            { "path" :
              "This is a list of the directories containing executables that will be found without "
             +"using the absolute path name. This tool will search these directories for ..."

Implemented in wx.Build.Cxx.GCC.GccAsCompiler, wx.Build.Cxx.GCC.WindRes, wx.Build.MS.Cl, wx.Build.MS.Link, and wx.Build.MS.RC.

---