site/src/site/apt/developers/building.apt.vm - npanday - Git at Google

  ----
  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.
	----
	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.