 ----
 Building NPanday
 ----
 ----
~~Licensed to the Apache Software Foundation (ASF) under one
~~or more contributor license agreements.  See the NOTICE file
~~distributed with this work for additional information
~~regarding copyright ownership.  The ASF licenses this file
~~to you under the Apache License, Version 2.0 (the
~~"License"); you may not use this file except in compliance
~~with the License.  You may obtain a copy of the License at
~~
~~    http://www.apache.org/licenses/LICENSE-2.0
~~
~~Unless required by applicable law or agreed to in writing,
~~software distributed under the License is distributed on an
~~"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
~~KIND, either express or implied.  See the License for the
~~specific language governing permissions and limitations
~~under the License.

Building NPanday

  Building NPanday is quite simple and follows the typical convention for a Maven project.

* Pre-requisites

  You must fulfil the same prerequisites that are documented in the
  {{{../guide/installation/index.html} Installation Guide}}.

  If you already have Visual Studio 2005 or later installed, then the
  environment will already be sufficient.

  If you are building with just the Windows SDK, then the Add-in will be
  skipped. To build that as well, either install Visual Studio, or the freely
  available {{{http://www.microsoft.com/download/details.aspx?id=1366} Visual
  Studio 2010 Shell Integration}} package.

  If you are building using Mono, no additional requirements are needed, and
  Windows-specific modules such as the Add-in will be skipped.

  Depending on the other software you have installed, several integration
  tests may be skipped. If you'd like to ensure maximum compatibility of your
  changes, you should have the following installed:

    * Windows Azure SDK 1.6 (November 2011)

    * Windows Azure SDK 1.7 (June 2012)

    * WiX Toolset 3.x

    * Microsoft Web Deploy 2.1

    * .NET Framework 2.0

    * .NET Framework 3.5

    * .NET Framework 4.0

    * ASP.NET MVC 2

* Checking out the Source Code

  You can check out the latest source code from
  {{https://svn.apache.org/repos/asf/incubator/npanday/trunk}}. You can also
  download a previous version as an archive from the web site, or check it
  out from the subdirectory of
  {{https://svn.apache.org/repos/asf/incubator/npanday/tags}}.

  For example:

+----+
svn co https://svn.apache.org/repos/asf/incubator/npanday/trunk npanday
+----+

* Building All with Maven

  To build the default modules for the current platform, run Maven:

+----+
mvn clean install
+----+

  Once this command has completed, you can proceed to use the Maven plugins
  immediately.

  This build assumes that a suitable version of NPanday is available to build
  itself. If necessary, you may need to first run this:

+----+
bootstrap
+----+

  After that, you may simply use <<<mvn clean install>>> each time.

  Several profiles are available for more extensive support or tests:

    * <<<net40>>> - run additional .NET 4.0 tests for the project importer

    * <<<run-its>>> - run the integration tests for plugins and the overall
      NPanday suite (requires <<<mvn clean install>>> to have been run once
      first)

    * <<<dist>>> - build the distribution files including the MSI

  Therefore, a complete build might be:

+----+
mvn clean install -Pnet40,run-its,dist
+----+

  More information on these options can be found in the following sections.

* Building the Visual Studio Add-in with Visual Studio / MSBuild

  If you just wish to work on the Visual Studio Add-in, it can be loaded into Visual Studio and built there. More
  information is available in {{{./debugging-addin.html} Debugging the Visual Studio Add-in}}.

* Running Integration Tests

  The Maven command line plugins feature a series of integration tests to ensure that everything is working as
  expected. They can be obtained by checking out the source code at
  {{https://svn.apache.org/repos/asf/incubator/npanday/npanday-its/trunk}}.

  For example:

+----+
svn co https://svn.apache.org/repos/asf/incubator/npanday/npanday-its/trunk npanday-its
+----+

  From within that directory, you can run it against the latest available version of NPanday (likely the one you have
  just built above) using the following command:

+----+
mvn test -Prun-its
+----+

  The command will indicate which version of NPanday is being used, and which tests pass and fail. It will also
  indicate which version of .NET SDK is installed and used by the tests - for example, if .NET 3.5 SDK is not available,
  tests that depend on it will be skipped.

  You can also run them against a specific previous version of NPanday (which will be downloaded from the repository
  if needed):

+----+
mvn test -Prun-its -Dnpanday.version=${project.version}
+----+

  When contributing fixes for issues in the Maven plugins, it is appropriate to write an integration test along with it.
  They are written in Java, using JUnit, and contain a sample project against which <<<mvn>>> is run against, and the
  the expected results are then verified. Existing integration tests can be used as a guide.

* Building NPanday and executing the ITs

  You can also build the source code and execute the ITs in one command. But first you have to install the ITs in your
  local repository using the following command from the npanday-its checkout:

+----+
mvn clean install
+----+

  After you have installed the ITs locally, you can now build the source code and execute the ITs by
  using the following command:

+----+
mvn clean install -Prun-its
+----+

  Note that in addition to running the suite of integration tests for
  NPanday, this also enables integration tests for certain plugins that use the
  Maven invoker framework.

* Generating NPanday's documentation locally

  NPanday documentation is generated from {{{http://maven.apache.org/doxia/references/apt-format.html} APT-files}}
  using the {{{http://maven.apache.org/doxia/index.html} Maven Doxia Tools}}.

  The documentation site and PDF can be generated using the following command within the <<<site>>> and the
  <<<plugins>>> directory of the NPanday trunk:

+----+
mvn site
+----+

  Open <<<target/site/index.html>>> in your browser to view the
  documentation for each module.

  It is recommended to add <<<-o>>> for speeding up the generation after the first successful build.