Prior to building NMaven, make sure that you have the following installed on your system:
Optional programs that need to be downloaded separately (and are not required for the build) include:
To build NMaven:
svn co https://svn.apache.org/repos/asf/incubator/nmaven/trunk nmaven
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
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
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!
NOTE: Remote downloading is not currently working with snapshots. You will need to build NMaven.
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:
On Windows, Mono looks something like:
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.
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
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.
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
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:
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.
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>
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.
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>
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) |
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.
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
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>
Make sure that FxCopCmd is installed and located within your path.
Then:
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