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