NMaven -

Getting Started

Sections

Building NMaven

Prerequisites

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

JDK 5.0 Update x
For Microsoft builds you will need both Microsoft .NET Framework (2.0+) AND NET Framework 2.0 SDK. For Mono builds, you will need Mono (1.2.3.1+). Note that the 2.0+ framework (either MONO or Microsoft) is required to run NMaven, but you can still target 1.1 for your builds provided that the 1.1 version is also installed.
Subversion client 1.3+ (although 1.4 will soon be required). Click here for Windows Subversion Client.
NUnit 2.2+.
Maven 2.0.4 or higher

Optional programs that need to be downloaded separately (and are not required for the build) include:

FxCop 1.35 (Windows Only). FxCop is a code analysis tool that checks .NET managed code assemblies for conformance to the Microsoft .NET Framework Design Guidelines.
Visual Studio 2005 Standard or higher is needed to use the NMaven Addin (Visual Studio Express Edition will not work)

Bootstrap Build

To build NMaven:

Do an SVN checkout

For the latest, unstable version:

svn co https://svn.apache.org/repos/asf/incubator/nmaven/trunk nmaven

For a stable version:

svn ls https://svn.apache.org/repos/asf/incubator/nmaven/tags

You will see something like:

STABLE-2007-05-18/
STABLE-2007-05-20/

Choose the latest stable date, which in this case is:

svn co https://svn.apache.org/repos/asf/incubator/nmaven/tags/STABLE-2007-05-20 nmaven

If compiling on Windows with either Microsoft or Mono:
1. the csc (or gmcs) executable directory AND the .NET SDK install root (containing xsd, wsdl) should be located on the system path. For Mono the executable directory and the SDK install root are the same. This configuration is only needed for the initial bootstrap build and may be removed afterwards.
2. 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: Unit Testing with NUnit
3. 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.2.3.1\bin"
Execute bootstrap-build.bat (or bootstrap-build.sh) from the nmaven directory. If you want to compile with Visual Studio 2005 support (Windows only) execute: bootstrap-build.bat -DVisualStudio2005

During step (1), if you receive an error similar to the following, will need to upgrade to subversion 1.4 or higher:

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

During step (3) if you can't build, the most common reason is that the paths are not set correctly (see 2(a) above). To verify try,

xsd

If you see the error message below, make sure that Mono or the SDK for Microsoft is installed on the classpath.

'xsd' is not recognized as an internal or external command

or

xsd: command not found

Also try commands for: "nunit-console" and "csc". If either of these gives a command not found, then you need to add them to the system path. If you still can't build, you will need to capture the debug output. Type

bootstrap-build.bat -X > out.log

and report the error to either

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 2.1.3.1 or higher. Type "mono -V" on the command line to see what version you are running. If it is below 2.1.3.1, then download the latest mono version, unzip and run rpm from the commandline. Detailed instructions are located here: Installing Mono. Make sure that su to root before installing with these instructions!

Using NMaven Without Building

NOTE: Remote downloading is not currently working with snapshots. You will need to build NMaven.

Prerequisites

JDK 5.0 Update x
Both Microsoft .NET Framework (2.0+) AND NET Framework 2.0 SDK or Mono (1.2.3.1+).
NUnit 2.2+ (only if using unit tests).
Maven 2.0.4 or higher

For the initial use only, you will also need to make sure that you have both the SDK and the .NET framework locations within your path. On Linux distributions, this should already be in your path. Typical locations for Microsoft include:

install root: C:\WINDOWS\Microsoft.NET\Framework\v2.0.50727
SDK root: C:\Program Files\Microsoft.NET\SDK\v2.0\

On Windows, Mono looks something like:

install/sdk path: C:\Program Files\Mono-1.1.13.8\bin

Usage

Configure your settings.xml file to point to the Maven snapshot repository.

  <profiles>
    <profile>
      <id>apache.snapshots</id>
      <activation>
        <activeByDefault>true</activeByDefault>
      </activation>
      <repositories>
        <repository>
          <id>org.apache</id>
          <name>Maven Snapshots</name>
          <url>http://people.apache.org/repo/m2-snapshot-repository</url>
          <releases>
            <enabled>true</enabled>
          </releases>
          <snapshots>
            <enabled>true</enabled>
          </snapshots>
        </repository>
      </repositories>
      <pluginRepositories>
        <pluginRepository>
          <id>org.apache</id>
          <name>Maven Plugin Snapshots</name>
          <url>http://people.apache.org/repo/m2-snapshot-repository</url>
          <releases>
            <enabled>false</enabled>
          </releases>
          <snapshots>
            <enabled>true</enabled>
          </snapshots>
        </pluginRepository>
      </pluginRepositories>
    </profile>
  </profiles>

Now Create a Simple Project. To build,

mvn install -DinstallGacDependencies=true

You only need the -DinstallGacDependencies=true option the first time you use NMaven.

Creating a Simple Project

To create a simple project:

 mvn archetype:create -DgroupId=<<myGroupid>>                               \
                      -DartifactId=<<myArtifactId>>                         \
                      -DarchetypeArtifactId=maven-archetype-dotnet-simple \
                      -DarchetypeGroupId=org.apache.maven.dotnet          \
                      -DarchetypeVersion=0.14-SNAPSHOT

You will see the following project generated:

.
 |-- src
 |   `-- main
 |       `-- csharp
 |           `-- Sample
 |               `-- MyApp.cs
  `-- pom.xml

Note that due to a limitation of the existing maven archetype plugin, the generated project does not follow the recommended conventions. See here: Conventions

Generating VS2005 Solution Files

To generate the solution and project files (csharp only) for a project with a prexisting pom, go to the directory containing the pom and type

mvn NMaven.Plugins:NMaven.Plugin.Solution.JavaBinding:Solution

This plugin generates a solution file and project file for each project that exists within the project.modules.module tag of the pom (or just the parent pom if no project.modules.module entry exists). The solution generator will add all of the dependencies that exist within pom into the cs project file. The generator will also look through the class files, attempting to locate and add any references that exist within the gac.

The latest solution generator runs as a .NET Maven plugin. Unfortunately due to a bug in Mono, .NET Maven plugins don't work with Mono. This is a high priority item, so expect a working solution to be offered in the near feature.

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). You may, however, optionally add -SNAPSHOT to the version. Valid versions would include 1.3.4 or 1.2-SNAPSHOT. 1.2-RC1 is invalid because NMaven would not recognize the RC1 identifier. The SNAPSHOT within the version will not be included within the file name, but rather is contained both within the InformationalVersion attribute of the AssemblyInfo class and within the pom.xml file.

Due to a bug, SNAPSHOTS are only supported for C#: NMAVEN-62

Unit Testing with NUnit

Add the 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:

If you do not add the nunit bin to your path;
If you have the mono bin in your path and you want to use another installation of NUnit ;
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>
            <frameworkVersion>1.1.4322</frameworkVersion>
            <testFrameworkVersion>1.1.4322</testFrameworkVersion>
        </configuration>
    </plugin>
</plugins>

You also have the option of changing the framework version by modifying the default setup within the nmaven-settings.xml file. See Using NMaven Settings File.

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.dotnet.plugins:maven-install-plugin:install-file
        -Dfile=../imports/nunit-2.0/nunit.framework.dll
        -DgroupId=NUnit
        -DartifactId=NUnit.Framework
        -Dpackaging=library
        -DartifactVersion=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>

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.

The nmaven-settings default values will be ignored if they are specified either through the command line of the pom file. The values that NMaven uses for building and testing, in order of priority, are

commandline: -Dvendor, -DframeworkVersion, -DvendorVersion
pom.xml file configuration of the compiler
nmaven-settings.xml file

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>

FxCop Maven Plugin

Make sure that FxCopCmd is installed and located within your path.

Then:

Go to your directory containing the pom (it may be a parent pom containing multiple modules).
Install the project: mvn install
Type one of the following commands

For a single module install or a multi-module, non-aggregated reports, type:

mvn org.apache.maven.dotnet.plugins:maven-fxcop-plugin:fxcop

For a mult-module, aggregated report, type:

mvn org.apache.maven.dotnet.plugins:maven-fxcop-plugin:aggregate

General Info

IDE Integration

Developer Documentation

Project Documentation

Getting Started

Sections

Building NMaven

Prerequisites

Bootstrap Build

Linux Specific Setup

Using NMaven Without Building

Prerequisites

Usage

Creating a Simple Project

Generating VS2005 Solution Files

Assembly Info

Unit Testing with NUnit

Building & Deploying Web Applications

Building with .NET Modules

Installing Existing Assemblies in the Maven Repository

Generating Resources

Signing Assemblies

Using NMaven Settings File

FxCop Maven Plugin