Getting Started

Sections

 * {{{getting-started.html#Building NMaven}Building NMaven}}

 * {{{getting-started.html#Assembly Info}Assembly Info}}

 * {{{getting-started.html#Unit Testing with NUnit}Unit Testing with NUnit}}

 * {{{getting-started.html#Building & Deploying Web Applications}Building & Deploying Web Applications}}

 * {{{getting-started.html#Building with .NET Modules}Building with .NET Modules}}

 * {{{getting-started.html#Installing Existing Assemblies in the Maven Repository}Installing Existing Assemblies in the Maven Repository}}

 * {{{getting-started.html#Generating Resources}Generating Resources}}

 * {{{getting-started.html#Signing Assemblies}Signing Assemblies}}

 * {{{getting-started.html#Using NMaven Settings File}Using NMaven Settings File}}

* {Building NMaven}

** Prerequisites

 Prior to building NMaven, make sure that you have the following installed on your system:

  [[1]] {{{ http://java.sun.com/javase/downloads/index_jdk5.jsp} JDK 5.0 Update x}}

  [[2]] {{{http://msdn2.microsoft.com/en-us/netframework/default.aspx} Microsoft .NET Framework}} (1.1+)
  OR {{{http://www.mono-project.com} Mono}} (1.1.13+ for Windows and 1.1.18+ for Linux)

  [[3]] Subversion client 1.3+ (although 1.4 will soon be required). Click here for
 {{{ http://subversion.tigris.org/servlets/ProjectDocumentView?documentID=35379&showInfo=true} Windows Subversion Client}}.

  [[4]] {{{http://nunit.org/index.php?p=download} NUnit 2.2+}}

** Bootstrap Build

  To build NMaven:

  [[1]] Do an SVN checkout: svn co https://svn.apache.org/repos/asf/incubator/nmaven/trunk nmaven.

  [[2]] If compiling on Windows:

   [[a]] the csc executable directory should be located on the system path. This is only needed for the initial bootstrap build
   and may be removed afterwards.

   [[b]] the directory path containing nunit-console should also be located on the system path. After the bootstrap build, you should leave
   the directory path containing the nunit-console executable within the system path. For other options, see:
   {{{getting-started.html#Unit Testing with NUnit}Unit Testing with NUnit}}

   [[c]] If using Mono on Windows, both the csc executable and the nunit-console executable are located within the same path:
   typically something like "C:\Program Files\Mono-1.1.18\bin"

  [[3]] Execute bootstrap-build.bat (or bootstrap-build.sh) from the nmaven directory.

 During step (1), you may receive an error similar to the following:

+----+

 svn: This client is too old to work with working copy 'nmaven-utility-resx\src\main\csharp'; please get a newer Subversion client
+----+

 In this case will need to upgrade to subversion 1.4 or higher.

** Linux Specific Setup

 Building on Linux, may take some extra steps. By default, on many Linux environments, the GNU Compiler for Java is already
 installed. The current GNU version will not work with NMaven. To check which version the system uses, type "java -version"
 on the command line. If you see something similar to the following, you will need to take additional steps to get the
 build setup:

+----+

java version "1.4.2"
gij (GNU libgcj) version 4.1.1 20060525 (Red Hat 4.1.1-1)
+----+

 Create a file "/etc/profile.d/java.sh" with the following entries:

+----+

 export JAVA_HOME=/usr/java/jdk1.5.0_09
 export PATH=$JAVA_HOME/bin:$PATH
+----+

 Type "mvn -version" from the command line. You should see the following:

+----+

java version "1.5.0_09"
Java(TM) 2 Runtime Environment, Standard Edition (build 1.5.0_09-b01)
Java HotSpot(TM) Client VM (build 1.5.0_09-b01, mixed mode, sharing)
+----+

 On Linux, you also need Mono version 1.1.18 or higher. Type "mono -V" on the command line to see what version you
 are running. If it is below 1.1.18, then download the latest mono version, unzip and run rpm from the commandline.
 Detailed instructions are located here:
 {{{ http://www.mono-project.com/Getting_Mono}Installing Mono}}

* {Assembly Info}

 Provided that you do not have your own AssemblyInfo class in your project, NMaven will automatically generate
 an AssemblyInfo.* for you. It does the following mapping:

*-------------------------+--------------------------------------------+
| AssemblyDescription | $\{project.description\} |
*-------------------------+--------------------------------------------+
| AssemblyVersion | $\{project.version\} |
*-------------------------+--------------------------------------------+
| AssemblyTitle | $\{project.name\} |
*-------------------------+--------------------------------------------+
| AssemblyCompany | $\{project.organization.name\} |
*-------------------------+--------------------------------------------+
| AssemblyProduct | $\{project.organization.name\}-$\{project.name\} |
*-------------------------+--------------------------------------------+
| AssemblyCopyright | place a COPYRIGHT.txt file in your module directory and NMaven will pick it up and put it in the assembly |
*-------------------------+--------------------------------------------+

 Since the pom version is mapped to the assembly manifest, you MUST follow the 0.0.0.0 version convention specified by
 Microsoft (or the build will fail).

* {Unit Testing with NUnit}

 Add the org.nunit dependency to your pom.xml (as shown below). You
 will only need to add the nmaven-test-plugin to the pom under the following circumstances:

  [[1]] If you do not add the nunit bin to your path;

  [[2]] If you have the mono bin in your path and you want to use another installation of NUnit ;

  [[3]] If you have both the mono bin and the NUnit bin in your path and you want to choose a specific one.

 Sample configuration of the test-plugin:

+----+

 <project>
....
    <dependencies>
        <dependency>
            <groupId>org.apache.maven.sample</groupId>
            <artifactId>csc1</artifactId>
	        <type>module</type>
            <version>2.0.0.0</version>
        </dependency>

        <dependency>
          <groupId>NUnit</groupId>
          <artifactId>nunit.framework</artifactId>
          <version>2.2.8.0</version>
          <type>library</type>
        </dependency>
    </dependencies>

    <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>
            <plugin>
                <groupId>org.apache.maven.plugins</groupId>
                <artifactId>maven-test-plugin</artifactId>
                <configuration>
                    <nunitHome>C:\Programs\nunit</nunitHome>
                </configuration>
            </plugin>
        </plugins>
    </build>
</project>

+----+

 On occasion, you may want to use one language for your main classes and another language for your test classes. In this
 case use the \<testLanguage/> tag as shown below. The \<language/> and \<vendor/> tags are for the main classes and the
 \<testLanguage/> and \<testVendor/> are for the test classes.

+----+

 <project>
....

    <build>
...
        <plugins>
            <plugin>
                <groupId>org.apache.maven.plugins</groupId>
                <artifactId>maven-compile-plugin</artifactId>
     	        <extensions>true</extensions>
     	        <configuration>
     	            <language>C_SHARP</language>
     	            <vendor>MONO</vendor>
     	            <testLanguage>VB</testLanguage>
     	            <testVendor>MICROSOFT</testVendor>
     	        </configuration>
            </plugin>
        </plugins>
    </build>
</project>

+----+

 NMaven defaults to the 2.0 Framework Version for compiling. To change this to 1.1 (for both the test compile and the
 main compile), do the following:

+----+

<plugins>
    <plugin>
        <groupId>org.apache.maven.plugins</groupId>
        <artifactId>maven-compile-plugin</artifactId>
        <extensions>true</extensions>
        <configuration>
            <language>C_SHARP</language>
            <vendor>MONO</vendor>
            <frameworkVersion>1.1.4322</frameworkVersion>
            <testLanguage>VB</testLanguage>
            <testVendor>MICROSOFT</testVendor>
            <testFrameworkVersion>1.1.4322</testFrameworkVersion>
        </configuration>
    </plugin>
</plugins>

+----+

 To disable the NUnit tests, add the system property -Dmaven.test.skip=true to the command line. You can also disable
 tests by adding \<skipTests>true\</skipTests> to the configuration above.

* {Building & Deploying Web Applications}

 To enable building of the Web application, specify the packaging as "nar" - .NET Archive. NMaven will compile
 classes in the source and test directories and then proceed to place the newly generated artifacts and its dependencies into
 the target/$\{project.build.finalname\}/bin directory. NMaven will also copy any files from the src/main/webapp directory
 into the target/$\{project.build.finalname\} directory, allowing you to add any additional resources such as Web.Config and
 ASPX files.

 You will only need to add the nmaven-webapp-plugin to the pom if you are planning on deploying the web application. In
 that case, add the deployPath pom configuration as shown below. Type "mvn deploy" from the command line and NMaven will
 copy the web application to the deployPath location.

+----+

<project>
    <modelVersion>4.0.0</modelVersion>
    <groupId>org.apache.maven.sample</groupId>
    <artifactId>webapp</artifactId>
    <packaging>nar</packaging>
    <version>2.0.0</version>
    <name>nar</name>
    <dependencies>
        <dependency>
            <groupId>org.apache.maven.sample</groupId>
            <artifactId>csc2</artifactId>
            <type>library</type>
            <version>2.0.0</version>
        </dependency>
    </dependencies>

    <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>
            <plugin>
                <groupId>org.apache.maven.plugins</groupId>
                <artifactId>maven-webapp-plugin</artifactId>
                <configuration>
                    <deployPath>${MYAPP_HOME}/apps</deployPath>
                </configuration>
            </plugin>
        </plugins>
    </build>
</project>

+----+

* {Building with .NET Modules}

 Linking all of your .NET libraries to all of the .NET module transitive dependencies is probably not want you want to do.
 NMaven will only link the modules that are directly specified within the project's pom. For the DotGNU compiler,
 you can create modules, but (as of yet) there is no way to add them to other libraries during the compile process.

* {Installing Existing Assemblies in the Maven Repository}

 Unlike typical artifacts generated by Maven, the NMaven artifacts in the Maven repository do not include versions
 in the file name. This has a number of advantages, including not needing to recompile all of your favorite open-source
 assemblies that you want use as dependencies in your build. To install an artifact, execute a commandline argument
 (directly or through a script) using the maven-install-plugin:

+----+
 mvn org.apache.maven.plugins:maven-install-plugin:install-file
        -Dfile=../imports/nunit-2.0/nunit.framework.dll
        -DgroupId=org.nunit
        -DartifactId=nunit.framework
        -Dpackaging=dll
        -Dversion=2.2.8.0
+----+

 After that, include the dependency in your pom.xml file and you are ready to go.

+----+
     <dependencies>
        <dependency>
            <groupId>org.nunit</groupId>
            <artifactId>nunit.framework</artifactId>
            <version>2.2.8.0</version>
            <type>library</type>
        </dependency>
    </dependencies>
+----+

 Note that there is no current support for the use of classifiers within NMaven.

* {Generating Resources}

 There are four types of resources to include within an assembly: linked resources, embedded resources,
 win32 resources and win32 icon. By placing your files in the appropriate directory, NMaven will pick them up
 and embed/link them during the compile phase.

*-------------------------+--------------------------------------------+
| src/main/resources/linkresource | Link all files in this directory to the assembly  |
*-------------------------+--------------------------------------------+
| src/main/resources/resource | Embed all files in this directory to the assembly|
*-------------------------+--------------------------------------------+
| src/main/resources/resgen | Generate a resx file from all files in this directory and embed the resource in the assembly |
*-------------------------+--------------------------------------------+
| src/main/resources/win32res | Embed the resources in the assembly |
*-------------------------+--------------------------------------------+
| src/main/resources/win32icon | Embed the icon within the assembly (icon will show up in file viewer) |
*-------------------------+--------------------------------------------+

* {Signing Assemblies}

 NMaven supports compile-time signing of assemblies. You can sign assemblies by using the keyfile field in the
 maven-compile-plugin.

+----+
  <build>
    <sourceDirectory>src/main/csharp</sourceDirectory>
    <plugins>
      <plugin>
        <groupId>org.apache.maven.dotnet.plugins</groupId>
        <artifactId>maven-compile-plugin</artifactId>
        <extensions>true</extensions>
        <configuration>
          <keyfile>sample.snk</keyfile>
        </configuration>
      </plugin>
    </plugins>
  </build>
</project>
+----+

 For both Mono framework versions 1.1/2.0 and Microsoft 2.0, NMaven uses the keyfile and keycontainer compiler
 parameters. For Microsoft 1.1, NMaven adds the KeyName and KeyFile entries into the project's AssemblyInfo.cs.
 Future NMaven features will include delayed-signing and post-compilation signing of assemblies.

* {Using NMaven Settings File}

 On Windows, NMaven will read the Windows Registry - regarding information about Mono, Microsoft and DotGNU
 installations -  and will then output the registry info into a ~/.m2/nmaven-settings.xml file. This file assists
 NMaven in determining the capabilities of the build platform and in choosing the correct compiler and vendor for the
 build. By going into the defaultSetup tag, you can change which vendor and framework version that NMaven will use
 without needing to specify this information within the various pom.xml files.

 In the case of Linux, there is no registry so the nmaven-settings.xml file is not automatically generated. You may,
 however, create one by hand, allowing you to specify the location of DotGNU and Mono implementations.

+----+
 <?xml version="1.0" encoding="utf-8"?>
<nmavenSettings xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
  <operatingSystem>Microsoft Windows NT 5.1.2600 Service Pack 2</operatingSystem>
  <defaultSetup>
    <vendorName>MICROSOFT</vendorName>
    <vendorVersion>2.0.50727</vendorVersion>
    <frameworkVersion>2.0.50727</frameworkVersion>
  </defaultSetup>
  <vendors>
    <vendor>
      <vendorName>MICROSOFT</vendorName>
      <vendorVersion>1.1.4322</vendorVersion>
      <frameworks>
        <framework>
          <frameworkVersion>1.1.4322</frameworkVersion>
          <installRoot>C:\WINDOWS\Microsoft.NET\Framework\v1.1.4322</installRoot>
        </framework>
      </frameworks>
    </vendor>
    <vendor>
      <vendorName>MICROSOFT</vendorName>
      <vendorVersion>2.0.50727</vendorVersion>
      <frameworks>
        <framework>
          <frameworkVersion>2.0.50727</frameworkVersion>
          <installRoot>C:\WINDOWS\Microsoft.NET\Framework\v2.0.50727</installRoot>
        </framework>
      </frameworks>
    </vendor>
    <vendor>
      <vendorName>MICROSOFT</vendorName>
      <vendorVersion>3.0</vendorVersion>
      <frameworks>
        <framework>
          <frameworkVersion>3.0</frameworkVersion>
          <installRoot>C:\WINDOWS\Microsoft.NET\Framework\v3.0</installRoot>
        </framework>
      </frameworks>
    </vendor>
    <vendor>
      <vendorName>MONO</vendorName>
      <vendorVersion>1.1.13.8</vendorVersion>
      <frameworks>
        <framework>
          <frameworkVersion>1.1.4322</frameworkVersion>
          <installRoot>C:\Program Files\Mono-1.1.13.8\bin</installRoot>
        </framework>
        <framework>
          <frameworkVersion>2.0.50727</frameworkVersion>
          <installRoot>C:\Program Files\Mono-1.1.13.8\bin</installRoot>
        </framework>
      </frameworks>
    </vendor>
    <vendor>
      <vendorName>MONO</vendorName>
      <vendorVersion>1.1.18</vendorVersion>
      <isDefault>true</isDefault>
      <frameworks>
        <framework>
          <frameworkVersion>1.1.4322</frameworkVersion>
          <installRoot>C:\Program Files\Mono-1.1.18\bin</installRoot>
        </framework>
        <framework>
          <frameworkVersion>2.0.50727</frameworkVersion>
          <installRoot>C:\Program Files\Mono-1.1.18\bin</installRoot>
        </framework>
      </frameworks>
    </vendor>
    <vendor>
      <vendorName>DotGNU</vendorName>
      <vendorVersion>0.7.2</vendorVersion>
      <frameworks>
        <framework>
          <frameworkVersion>2.0.50727</frameworkVersion>
          <installRoot>C:\Program Files\Portable.NET\0.7.2\bin</installRoot>
        </framework>
      </frameworks>
    </vendor>
  </vendors>
</nmavenSettings>
+----+