Sections

 * {{{environment-configuration.html#Configuring the Environment}Configuring the Environment}}

 * {{{environment-configuration.html#Sample Configuration Files}Sample Configuration Files}}

{Configuring the Environment}

* Introduction

 NMaven is based on the concept of platform capabilities and platform requirements. Examples of platform capabilities include:

  [[1]] Linux (or Windows OS)

  [[2]] Mono 1.1.18 installed, Microsoft 2.0 installed

  [[3]] PHP .NET compiler (from 3rd party)

 Platform requirements are those build requirements specified by the developer. Typically, the requirements are given
 either within the pom.xml or the nmaven-settings.xml file. Examples of platform requirements include:

  [[1]] C# target language

  [[2]] Microsoft SDK

  [[3]] Framework version 2.0

  [[3]] Compact Profile

 It is up to NMaven to understand what the developer is asking for (platform requirements) and to determine whether the
 build machine can support the requirements (with its platform capabilities). If the capabilities match the requirements, NMaven
 will return an executable (or compiler) that satifies the requirements.

* Capability/Requirement Matching

[./images/matching_diagram.png]

 Consider the sequence diagram above.
 The developer provides the compiler requirements - vendor, vendor version, framework version, language and profile - within the pom.xml build file.

+----+
<plugin>
    <groupId>org.apache.maven.plugins</groupId>
    <artifactId>maven-compile-plugin</artifactId>
    <extensions>true</extensions>
    <configuration>
        <vendor>MICROSOFT</vendor>
        <language>C_SHARP</language>
        <frameworkVersion>1.1.4322</frameworkVersion>
        <profile>COMPACT</profile>
    </configuration>
</plugin>

+----+

 Next, the <<<CompilerMojo>>> class instance creates a <<<CompilerConfig>>> object (2), which contains artifact type (library, module) and key info.
 The compiler needs the configuration information during execution, but the information is not necessary for NMaven to match the correct compiler.

 The <<<CompilerMojo>>> object invokes the <<<NetExecutableFactory.getCompilerExecutableFor>>> method, passing in the <<<CompilerConfig>>>
 and <<<CompilerRequirement>>> objects as parameters (3). In step (18), the <<<getCompilerExecutableFor>>> method returns a fully initialized
 <<<CompilerExecutable>>> object. From the <<<CompilerMojo>>> class instance perspective, it simply constructs <<<CompilerConfig>>>
 and <<<CompilerRequirement>>> objects based on parameters within the pom and gets back a fully initialized <<<CompilerExecutable>>> object from the <<<NetExecutableFactory>>>.

 Now let’s dig a little deeper and see what’s going on underneath. The <<<NetExecutableFactory>>> object creates a <<<VendorInfo>>> object
 (4) and populates the <<<VendorInfo>>> object with information – vendor, vendor version and framework version – from the
 <<<CompilerRequirement>>> object (5). In short, we have a transfer of specific vendor information from the <<<CompilerRequirement>>> object
  to the <<<VendorInfo>>> object because the <<<StateMachineProcessor>>> is only concerned with the vendor information, which
  is the only required information for making a capability match (others are optionally used, if specified, but no attempt
  is made to infer them if they don't exist).

  The <<<StateMachineProcessor>>> fills in the missing vendor info (6, 7) based on a set of rules. Vendor-info may
   be missing for any number of reasons. For example, a project may compile across multiple vendors (Microsoft/Novell)
   or framework versions. In this case, the developer may choose to leave say the \<vendor/> and \<frameworkVersion/> tags
   within the pom.xml blank. The <<<StateMachineProcessor>>> object uses the ~/.m2/nmaven-settings.xml file (if it exists)
   to assist in infering the vendor information for the specific build machine. As you can see below, within the nmaven-settings.xml file
   there is a default setup (which the developer can change).

+----+
<nmavenSettings>
  <defaultSetup>
    <vendorName>MICROSOFT</vendorName>
    <vendorVersion>2.0.50727</vendorVersion>
    <frameworkVersion>2.0.50727</frameworkVersion>
  </defaultSetup>
  ...
</nmavenSettings>
+----+

  There are 23 states of vendor-info and both a start and stop state (for a total of 25 states).
  The notation is \{Vendor, Vendor Version, Framework Version}. For Vendor, M denotes
  Microsoft, N denotes Novell, G denotes DotGNU and F denotes false (unknown vendor).
  For Vendor Version and Framework Version, T denotes true (it exists),  while F denotes false (does not exist). So
  NFT means that the NMaven knows that it needs to choose a Novell (MONO) compiler and knows the framework version but
  not the vendor version.

  The 23 vendor-info states are defined below. They are divided between general states, states that can be determined through an
  nmaven-settings file and states that can be determined without an nmaven-settings file.

*-----------------------------------------------------------------------------------+----------------------------------+
| <<STATE>>                                       | <<Description>>
*-----------------------------------------------------------------------------------+----------------------------------+
|  <<General States>>
*-----------------------------------------------------------------------------------+----------------------------------+
| MTT      | Vendor is Microsoft, vendor version exists, framework version exists
*-----------------------------------------------------------------------------------+----------------------------------+
| MTF      | Vendor is Microsoft, vendor version does not exist, framework version exists
*-----------------------------------------------------------------------------------+----------------------------------+
| MFT      | Vendor is Microsoft, vendor version does not exist, framework version does not exist
*-----------------------------------------------------------------------------------+----------------------------------+
| NTT      | Vendor is Novell, vendor version exists, framework version exists
*-----------------------------------------------------------------------------------+----------------------------------+
| <<Settings File States>>
*-----------------------------------------------------------------------------------+----------------------------------+
| MFF       | Vendor is Microsoft, vendor version does not exist, framework version does not exist
*-----------------------------------------------------------------------------------+----------------------------------+
| FTF       | Vendor is unknown, vendor version exists, framework version does not exist
*-----------------------------------------------------------------------------------+----------------------------------+
| FFT       | Vendor is unknown, vendor version does not exist, framework version exists
*-----------------------------------------------------------------------------------+----------------------------------+
| FTT       | Vendor is unknown, vendor version exists, framework version exists
*-----------------------------------------------------------------------------------+----------------------------------+
| FFF       | Vendor is unknown, vendor version does not exist, framework version does not exist
*-----------------------------------------------------------------------------------+----------------------------------+
| NFT       | Vendor is Novell, vendor version does not exist, framework version exists
*-----------------------------------------------------------------------------------+----------------------------------+
| NTF       | Vendor is Novell, vendor version exists, framework version does not exist
*-----------------------------------------------------------------------------------+----------------------------------+
| NTT       | Vendor is Novell, vendor version exists, framework version exist
*-----------------------------------------------------------------------------------+----------------------------------+
| NFF       | Vendor is Novell, vendor version does not exist, framework version does not exist
*-----------------------------------------------------------------------------------+----------------------------------+
| GFF       | Vendor is GNU vendor version does not exist, framework version does not exist
*-----------------------------------------------------------------------------------+----------------------------------+
| <<No Settings File States>>
*-----------------------------------------------------------------------------------+----------------------------------+
| MFF_NoSettings  | Vendor is Microsoft, vendor version does not exist, framework version does not exist
*-----------------------------------------------------------------------------------+----------------------------------+
| NFT_NoSettings  | Vendor is Novell, vendor version exists, framework version does not exist
*-----------------------------------------------------------------------------------+----------------------------------+
| NTF_NoSettings  | Vendor is Novell, vendor version exists, framework version does not exist
*-----------------------------------------------------------------------------------+----------------------------------+
| FTF_NoSettings  | Vendor is unknown, vendor version exists, framework version does not exist
*-----------------------------------------------------------------------------------+----------------------------------+
| FFT_NoSettings  | Vendor is unknown, vendor version does not exist, framework version exists
*-----------------------------------------------------------------------------------+----------------------------------+
| FTT_NoSettings  | Vendor is unknown, vendor version exists, framework version exists
*-----------------------------------------------------------------------------------+----------------------------------+
| FFF_NoSettings  | Vendor is unknown, vendor version does not exist, framework version does not exist
*-----------------------------------------------------------------------------------+----------------------------------+
| NFF_NoSettings  | Vendor is Novell, vendor version does not exist, framework version does not exist
*-----------------------------------------------------------------------------------+----------------------------------+
| GFF_NoSettings  | Vendor is GNU vendor version does not exist, framework version does not exist
*-----------------------------------------------------------------------------------+----------------------------------+

 Going back to the sequence diagram, the <<<NetExecutableFactory>>> object fills in the missing vendor information into
 the <<<CompilerRequirement>>> object (8): we now have a
 complete <<<CompilerRequirement>>> to use for matching. The <<<NetExecutableFactory>>> object initializes the <<<CompilerContext>>>,
 passing in the <<<CompilerRequirement>>> and <<<CompilerConfig>>> objects. During initialization, the <<<CompilerContext>>> object invokes
 <<<CompilerMatcher.matchCompilerCapabilitiesFor(requirement)>>> (10). The <<<CompilerMatcher>>> class instance creates a list of platform
 capabilities (11) and matches <<<CompilerCapability>>> properties to the <<<CompilerRequirement>>> properties (12). The
 <<<CompilerMatcher>>> gets the class name of the <<<CompilerExecutable>>> by invoking <<<CompilerRequirement.getPluginClassName()>>> (13).
 The <<<CompilerMatcher>>> dynamically instatiates and initializes the <<<CompilerExecutable>>> (14).

 The <<<CompilerExecutable>>> is returned to the <<<CompilerMojo>>> (16, 17, 18), which then executes the Compiler (19).

{Sample Configuration Files}

* CSharp2.0:exe:Microsoft

+----+

<project>
    <modelVersion>4.0.0</modelVersion>
    <groupId>org.apache.maven.ms.csharp</groupId>
    <artifactId>it-0001</artifactId>
    <packaging>exe</packaging>
    <version>0.1.0.0</version>
    <name>csharp: it-0001</name>

    <build>
	<sourceDirectory>src/main/csharp</sourceDirectory>
	<testSourceDirectory>src/test/csharp</testSourceDirectory>
        <plugins>
            <plugin>
                <groupId>org.apache.maven.plugins</groupId>
                <artifactId>maven-compile-plugin</artifactId>
     	        <extensions>true</extensions>
            </plugin>
        </plugins>
    </build>
</project>

+----+

* CSharp3.0:exe:Microsoft (on Windows)

+----+

<project>
    <modelVersion>4.0.0</modelVersion>
    <groupId>org.apache.maven.ms.csharp</groupId>
    <artifactId>it-0001</artifactId>
    <packaging>exe</packaging>
    <version>0.1.0.0</version>
    <name>csharp: it-0001</name>

    <build>
	<sourceDirectory>src/main/csharp</sourceDirectory>
	<testSourceDirectory>src/test/csharp</testSourceDirectory>
        <plugins>
            <plugin>
                <groupId>org.apache.maven.plugins</groupId>
                <artifactId>maven-compile-plugin</artifactId>
     	        <extensions>true</extensions>
                <configuration>
                    <frameworkVersion>3.0</frameworkVersion>
                </configuration>
            </plugin>
        </plugins>
    </build>
</project>

+----+

* CSharp1.1:exe:Microsoft (on Windows)

+----+

<project>
    <modelVersion>4.0.0</modelVersion>
    <groupId>org.apache.maven.ms.csharp</groupId>
    <artifactId>it-0001</artifactId>
    <packaging>exe</packaging>
    <version>0.1.0.0</version>
    <name>csharp: it-0001</name>

    <build>
	<sourceDirectory>src/main/csharp</sourceDirectory>
	<testSourceDirectory>src/test/csharp</testSourceDirectory>
        <plugins>
            <plugin>
                <groupId>org.apache.maven.plugins</groupId>
                <artifactId>maven-compile-plugin</artifactId>
     	        <extensions>true</extensions>
                <configuration>
                    <frameworkVersion>1.1.4322</frameworkVersion>
                </configuration>
            </plugin>
        </plugins>
    </build>
</project>

+----+

* CSharp1.1:exe:Mono (on Linux)

+----+

<project>
    <modelVersion>4.0.0</modelVersion>
    <groupId>org.apache.maven.ms.csharp</groupId>
    <artifactId>it-0001</artifactId>
    <packaging>exe</packaging>
    <version>0.1.0.0</version>
    <name>csharp: it-0001</name>

    <build>
	<sourceDirectory>src/main/csharp</sourceDirectory>
	<testSourceDirectory>src/test/csharp</testSourceDirectory>
        <plugins>
            <plugin>
                <groupId>org.apache.maven.plugins</groupId>
                <artifactId>maven-compile-plugin</artifactId>
     	        <extensions>true</extensions>
                <configuration>
                    <frameworkVersion>1.1.4322</frameworkVersion>
                </configuration>
            </plugin>
        </plugins>
    </build>
</project>

+----+


* VB2.0: library:MS

+----+

<project>
    <modelVersion>4.0.0</modelVersion>
    <groupId>org.apache.maven.ms.csharp</groupId>
    <artifactId>it-0001</artifactId>
    <packaging>library</packaging>
    <version>0.1.0.0</version>
    <name>vb:it-0001</name>

    <build>
	<sourceDirectory>src/main/vb</sourceDirectory>
	<testSourceDirectory>src/test/vb</testSourceDirectory>
        <plugins>
            <plugin>
                <groupId>org.apache.maven.plugins</groupId>
                <artifactId>maven-compile-plugin</artifactId>
     	        <extensions>true</extensions>
                <configuration>
			        <language>VB</language>
                </configuration>
            </plugin>

        </plugins>
    </build>
</project>

+----+

* CSharp1.1:module:Mono (on Windows)

 You will only need to use the MONO vendor field if you want to build MONO on windows: MONO is the default vendor for
 other OS's.

+----+

<project>
    <modelVersion>4.0.0</modelVersion>
    <groupId>org.apache.maven.mono.csharp</groupId>
    <artifactId>it-0001</artifactId>
    <packaging>module</packaging>
    <version>0.1.0.0</version>
    <name>csharp: it-0001</name>

    <build>
	<sourceDirectory>src/main/csharp</sourceDirectory>
	<testSourceDirectory>src/test/csharp</testSourceDirectory>
        <plugins>
            <plugin>
                <groupId>org.apache.maven.plugins</groupId>
                <artifactId>maven-compile-plugin</artifactId>
     	        <extensions>true</extensions>
                <configuration>
                    <vendor>MONO</vendor>
                    <frameworkVersion>1.1.4322</frameworkVersion>
                </configuration>
            </plugin>
        </plugins>
    </build>
</project>

+----+

* CSharp2.0:library:Mono

+----+

<project>
    <modelVersion>4.0.0</modelVersion>
    <groupId>org.apache.maven.mono.csharp</groupId>
    <artifactId>it-0001</artifactId>
    <packaging>library</packaging>
    <version>0.1.0.0</version>
    <name>csharp: it-0001</name>

    <build>
	<sourceDirectory>src/main/csharp</sourceDirectory>
	<testSourceDirectory>src/test/csharp</testSourceDirectory>
        <plugins>
            <plugin>
                <groupId>org.apache.maven.plugins</groupId>
                <artifactId>maven-compile-plugin</artifactId>
     	        <extensions>true</extensions>
                <configuration>
                    <vendor>MONO</vendor>
                </configuration>
            </plugin>
        </plugins>
    </build>
</project>

+----+

* CSharp:library:DotGNU

+----+

<project>
    <modelVersion>4.0.0</modelVersion>
    <groupId>org.apache.maven.mono.csharp</groupId>
    <artifactId>it-0001</artifactId>
    <packaging>library</packaging>
    <version>0.1.0.0</version>
    <name>csharp: it-0001</name>

    <build>
	<sourceDirectory>src/main/csharp</sourceDirectory>
	<testSourceDirectory>src/test/csharp</testSourceDirectory>
        <plugins>
            <plugin>
                <groupId>org.apache.maven.plugins</groupId>
                <artifactId>maven-compile-plugin</artifactId>
     	        <extensions>true</extensions>
                <configuration>
                    <vendor>DotGNU</vendor>
                </configuration>
            </plugin>
        </plugins>
    </build>
</project>

+----+

* Nemerle:library:Mono

+----+

<project>
    <modelVersion>4.0.0</modelVersion>
    <groupId>org.apache.maven.mono.nemerle</groupId>
    <artifactId>it-0001</artifactId>
    <packaging>library</packaging>
    <version>0.1.0.0</version>
    <name>nemerle: it-0001</name>

    <build>
	<sourceDirectory>src/main/nemerle</sourceDirectory>
	<testSourceDirectory>src/test/nemerle</testSourceDirectory>
        <plugins>
            <plugin>
                <groupId>org.apache.maven.plugins</groupId>
                <artifactId>maven-compile-plugin</artifactId>
     	        <extensions>true</extensions>
                <configuration>
                    <language>NEMERLE</language>
                    <vendor>MONO</vendor>
                </configuration>
            </plugin>
        </plugins>
    </build>
</project>

+----+

* PHP:library:Mono

 To get PHP to run with NMaven, you will need to include mPHPRuntime.dll under each module directory. This is a work
 around until I create a mavenizer-plugin that will handle non-nmaven generated assemblies.

+----+

<project>
    <modelVersion>4.0.0</modelVersion>
    <groupId>org.apache.maven.mono.php</groupId>
    <artifactId>it-0001</artifactId>
    <packaging>library</packaging>
    <version>0.1.0.0</version>
    <name>php: it-0001</name>

    <build>
	<sourceDirectory>src/main/php</sourceDirectory>
	<testSourceDirectory>src/test/php</testSourceDirectory>
        <plugins>
            <plugin>
                <groupId>org.apache.maven.plugins</groupId>
                <artifactId>maven-compile-plugin</artifactId>
     	        <extensions>true</extensions>
                <configuration>
                    <language>PHP</language>
                    <vendor>MONO</vendor>
                </configuration>
            </plugin>
        </plugins>
    </build>
</project>

+----+