Author: brett
Date: Wed Aug 6 10:00:40 2014
New Revision: 1616142
URL: http://svn.apache.org/r1616142
Log:
update build instructions and requirements
Document latest versions available, and changes now that PATH and settings
are not required
Modified:
incubator/npanday/trunk/site/src/site/apt/developers/building.apt.vm
incubator/npanday/trunk/site/src/site/apt/developers/publishing-docs.apt
incubator/npanday/trunk/site/src/site/apt/developers/releasing.apt
incubator/npanday/trunk/site/src/site/apt/faqs.apt
incubator/npanday/trunk/site/src/site/apt/features.apt
incubator/npanday/trunk/site/src/site/apt/guide/installation/index.apt.vm
incubator/npanday/trunk/site/src/site/apt/guide/vs/quickstart.apt
Modified: incubator/npanday/trunk/site/src/site/apt/developers/building.apt.vm
URL:
http://svn.apache.org/viewvc/incubator/npanday/trunk/site/src/site/apt/developers/building.apt.vm?rev=1616142&r1=1616141&r2=1616142&view=diff
==============================================================================
--- incubator/npanday/trunk/site/src/site/apt/developers/building.apt.vm
(original)
+++ incubator/npanday/trunk/site/src/site/apt/developers/building.apt.vm Wed
Aug 6 10:00:40 2014
@@ -25,42 +25,90 @@ Building NPanday
* Pre-requisites
- Since NPanday is built using NPanday, you must fulfil all the prerequisites
documented in the
- {{{../guide/installation/index.html} Installation Guide}}. NPanday trunk
usually builds against one
- of the latest releases. If you want
-
- <<NPanday builds using .NET 2.0.>> So, if you do not have Visual Studio 2005
installed, you must install
- .NET SDK 2.0 or Windows SDK 6.1 (includes .NET SDK 2.0) manually. This is,
because neither VS 2008 or VS 2010
- include the SDK for .NET 2.0. Find the download locations in the
Installation Guide.
+ 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
- NUnit-Binaries must be on the PATH environment variable.
-
* 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 from check
it out from the subdirectory of
+ 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
- Everything in the distribution, including the Visual Studio add-in, is built
using the following command:
+ To build the default modules for the current platform, run Maven:
-----
++----+
mvn clean install
-----
++----+
- <Note:> On Windows Vista and Windows 7, this presently needs to be run as an
administrator to build successfully,
- as it installs 3 libraries into the GAC.
+ Once this command has completed, you can proceed to use the Maven plugins
+ immediately.
- Once this command has completed, you can proceed to use the Maven plugins
immediately. To install the Visual Studio
- Add-in, you will need to still run the <<<mvn
npanday.plugin:maven-vsinstaller-plugin:install>>> command as described
- in the {{{../guide/installation/index.html} Installation Guide}}.
+ 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
+
+ * <<<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
@@ -75,19 +123,16 @@ mvn clean install
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
-----
-
- NOTE: In order to successfully run the integration tests, <<<ildasm>>> needs
to be on the PATH.
- (this is to be fixed {{{https://issues.apache.org/jira/browse/NPANDAY-393}
NPANDAY-393}})
++----+
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,
@@ -96,9 +141,9 @@ mvn test -Prun-its
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
@@ -107,18 +152,22 @@ mvn test -Prun-its -Dnpanday.version=${p
* 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:
+ 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
@@ -128,12 +177,11 @@ mvn clean install -Prun-its
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-deploy -P local-docs
-----
-
- Open <<<file:///c:/Program Files/NPanday/docs/index.html>>> in your browser
to view the documentation.
++----+
+mvn site
++----+
- You may also override the default local deployment through an additional
argument <<<-Dlocaldocs.folder=file:///...>>>.
+ 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.
\ No newline at end of file
+ It is recommended to add <<<-o>>> for speeding up the generation after the
first successful build.
Modified:
incubator/npanday/trunk/site/src/site/apt/developers/publishing-docs.apt
URL:
http://svn.apache.org/viewvc/incubator/npanday/trunk/site/src/site/apt/developers/publishing-docs.apt?rev=1616142&r1=1616141&r2=1616142&view=diff
==============================================================================
--- incubator/npanday/trunk/site/src/site/apt/developers/publishing-docs.apt
(original)
+++ incubator/npanday/trunk/site/src/site/apt/developers/publishing-docs.apt
Wed Aug 6 10:00:40 2014
@@ -31,9 +31,9 @@ Publishing the Documentation
This is done with the following command within the release checkout, first
from the <<<plugins>>> subdirectory, then
the <<<site>>> subdirectory:
-----
-mvn site-deploy -P apache-docs
-----
++----+
+mvn site-deploy
++----+
<Note:> It's important to do them in this order so that the generic plugins
index page will get overwritten by the
correct one in the docs for this version.
Modified: incubator/npanday/trunk/site/src/site/apt/developers/releasing.apt
URL:
http://svn.apache.org/viewvc/incubator/npanday/trunk/site/src/site/apt/developers/releasing.apt?rev=1616142&r1=1616141&r2=1616142&view=diff
==============================================================================
--- incubator/npanday/trunk/site/src/site/apt/developers/releasing.apt
(original)
+++ incubator/npanday/trunk/site/src/site/apt/developers/releasing.apt Wed Aug
6 10:00:40 2014
@@ -86,9 +86,9 @@ mvn release:prepare
[[5]] After successful release:prepare, run the following command:
-----
-mvn release:perform -Dtag=url_tag
-----
++----+
+mvn release:perform
++----+
* Steps in releasing NPanday:
Modified: incubator/npanday/trunk/site/src/site/apt/faqs.apt
URL:
http://svn.apache.org/viewvc/incubator/npanday/trunk/site/src/site/apt/faqs.apt?rev=1616142&r1=1616141&r2=1616142&view=diff
==============================================================================
--- incubator/npanday/trunk/site/src/site/apt/faqs.apt (original)
+++ incubator/npanday/trunk/site/src/site/apt/faqs.apt Wed Aug 6 10:00:40 2014
@@ -37,7 +37,7 @@ NPanday Frequently Asked Questions
You would need to install the following:
- * Java 1.5 or higher
+ * Java 1.6 or higher
* Apache Maven 2.0.9 or higher
Modified: incubator/npanday/trunk/site/src/site/apt/features.apt
URL:
http://svn.apache.org/viewvc/incubator/npanday/trunk/site/src/site/apt/features.apt?rev=1616142&r1=1616141&r2=1616142&view=diff
==============================================================================
--- incubator/npanday/trunk/site/src/site/apt/features.apt (original)
+++ incubator/npanday/trunk/site/src/site/apt/features.apt Wed Aug 6 10:00:40
2014
@@ -85,6 +85,10 @@ Features
* .NET 4.0 / Visual Studio 2010
+ * .NET 4.5 / Visual Studio 2012
+
+ * .NET 4.5.1 / Visual Studio 2013
+
[]
<<Note:>> There is partial support for Mono, .NET 1.1 and other vendors, but
these are currently untested.
Modified:
incubator/npanday/trunk/site/src/site/apt/guide/installation/index.apt.vm
URL:
http://svn.apache.org/viewvc/incubator/npanday/trunk/site/src/site/apt/guide/installation/index.apt.vm?rev=1616142&r1=1616141&r2=1616142&view=diff
==============================================================================
--- incubator/npanday/trunk/site/src/site/apt/guide/installation/index.apt.vm
(original)
+++ incubator/npanday/trunk/site/src/site/apt/guide/installation/index.apt.vm
Wed Aug 6 10:00:40 2014
@@ -31,20 +31,44 @@ Pre-requisites
must be set to the directory where the JDK is installed, for example,
<<<C:\\Program Files\\Java\\jdk1.6.0>>>.
The <<<java>>> executable must also be available on your path.
- * Visual Studio 2005 (SP1) or the .NET 2.0 SDK for developing .NET 2.0
applications and libraries (.NET 2.0 SDK:
{{{http://www.microsoft.com/downloads/details.aspx?FamilyID=fe6f2099-b7b4-4f47-a244-c96d69c35dec&displaylang=en}
x86}},
{{{http://www.microsoft.com/downloads/en/details.aspx?FamilyID=1AEF6FCE-6E06-4B66-AFE4-9AAD3C835D3D}
x64}})
+ * A suitable SDK for .NET:
- * Visual Studio 2008 (SP1) or the
{{{http://www.microsoft.com/downloads/en/details.aspx?FamilyID=c17ba869-9671-4330-a63e-1fd44e0e2505&displaylang=en}
Microsoft Windows SDK for Windows 7 and .NET 3.5 SP1 }} for developing .NET
3.5 applications and
- libraries. Note: The SDK can be installed on XP or Vista, too.
+ * Visual Studio 2005 (SP1) or the .NET 2.0 SDK for developing .NET 2.0
applications and libraries (.NET 2.0 SDK:
{{{http://www.microsoft.com/downloads/details.aspx?FamilyID=fe6f2099-b7b4-4f47-a244-c96d69c35dec&displaylang=en}
x86}},
{{{http://www.microsoft.com/downloads/en/details.aspx?FamilyID=1AEF6FCE-6E06-4B66-AFE4-9AAD3C835D3D}
x64}})
- * Visual Studio 2010 (SP1) or the {{{
http://www.microsoft.com/downloads/en/details.aspx?FamilyID=6b6c21d2-2006-4afa-9702-529fa782d63b&displaylang=en}
Microsoft Windows SDK for Windows 7 and .NET 4 SP1 }} for developing .NET 4
applications and
- libraries. Note: The SDK can be installed on XP or Vista, too.
+ * Visual Studio 2008 (SP1) or the
{{{http://www.microsoft.com/downloads/en/details.aspx?FamilyID=c17ba869-9671-4330-a63e-1fd44e0e2505&displaylang=en}
Microsoft Windows SDK for Windows 7 and .NET 3.5 SP1}} for developing .NET 3.5
applications and
+ libraries.
- * {{{http://www.nunit.org/?p=download} NUnit}} in order to run unit tests
with NPanday. Make sure the <<<bin>>> directory is on the PATH.
+ * Visual Studio 2010 (SP1) or the
{{{http://www.microsoft.com/downloads/en/details.aspx?FamilyID=6b6c21d2-2006-4afa-9702-529fa782d63b&displaylang=en}
Microsoft Windows SDK for Windows 7 and .NET 4}} for developing .NET 4
applications and
+ libraries.
+
+ * Visual Studio 2012 or the
+ {{{http://msdn.microsoft.com/en-US/windows/desktop/hh852363.aspx}
Microsoft Windows SDK for Windows 8 and .NET 4.5}}
+ and {{{http://www.microsoft.com/en-us/download/details.aspx?id=40760}
Microsoft Build Tools}}
+ for developing .NET 4.5 applications and libraries.
+
+ * Visual Studio 2013 or the
+ {{{http://msdn.microsoft.com/en-gb/windows/desktop/bg162891} Microsoft
Windows SDK for Windows 8.1}}
+ and {{{http://www.microsoft.com/en-us/download/details.aspx?id=40760}
Microsoft Build Tools}}
+ for developing .NET 4.5.1 applications and libraries.
+
+ * Mono for developing .NET applications and libraries across multiple
+ supported platforms
+
+ []
+
+ * {{{http://www.nunit.org/?p=download} NUnit}} in order to run unit tests
+ with NPanday. Make sure the <<<bin>>> directory is on the PATH. NUnit
+ is already installed with Mono.
+
+ Note that on Windows, NPanday requires the "NETFX Tools" made available
+ through the Windows SDK, in addition to framework tools such as <<<csc>>>,
+ <<<vbc>>> and <<<msbuild>>>. It is not required to have multiple versions
+ of the NETFX Tools to target different framework versions, however.
If you later have problems relating to being unable to find the SDK, refer
to the
{{{../reference/troubleshooting.html} Troubleshooting}} section.
-Removing a Previous Version
+Removing a Previous Version of NPanday
While it is generally safe to install the new version without uninstalling
the previous version, to ensure a clean
system you may want to follow the {{{./uninstall.html} Uninstalling
NPanday}} instructions.
@@ -52,19 +76,11 @@ Removing a Previous Version
Obtaining NPanday
- NPanday releases are made available in two locations:
-
- * {{{http://www.apache.org/dist/incubator/npanday/} NPanday Download
page}} - for downloading a full
- repository to install locally (once releases have been made from Apache)
-
- * {{{http://npanday.codeplex.com/Release/ProjectReleases.aspx} Codeplex
NPanday Download page}} - for downloading a full
- repository to install locally (releases before entering the Apache
Incubator)
-
- * Alternatively, you can obtain them directory using Maven.
-
- In NPanday 1.1, the release is only made available as a Maven binary
repository, or a source distribution.
- For information on how to build the project from source, see
{{{../../developers/building.html} Building from Source}}
- in the Developer's Guide. NPanday 1.2 and above include a Windows installer
as an option.
+ NPanday releases are made available at the
+ {{{http://www.apache.org/dist/incubator/npanday/} NPanday Download page}}.
+ From there you can download either an installable MSI, a repository of the
+ required Maven artifacts, or a source archive. The Maven plugins may also be
+ downloaded using the default Maven repositories.
~~TODO: additional guides for using the existing repositories
@@ -86,64 +102,22 @@ Installing Using the Downloaded Binary R
has not been modified in Maven's <<<settings.xml>>>.
For example, you may end up with a structure containing
- <<<C:\\Documents and
Settings\\User\\.m2\\repository\\npanday\\apache-npanday\\\\${project.version}\\apache-npanday-${project.version}.pom>>>.
+
<<<C:\\Users\\[username]\\.m2\\repository\\npanday\\apache-npanday\\\\${project.version}\\apache-npanday-${project.version}.pom>>>.
To confirm your installation, run the following command, replacing
<<<${project.version}>>> with the version you are installing:
----
-mvn help:describe -DgroupId=org.apache.npanday.plugins
-DartifactId=maven-vsinstaller-plugin -Dversion=${project.version}
-----
-
- If successful, you should receive the following output:
-
-----
-Name: NPanday :: Visual Studio Addin Installer Maven Plugin
-Description: Maven Plugin for .NET: Installs the Visual Studio Addin
-Group Id: org.apache.npanday.plugins
-Artifact Id: maven-vsinstaller-plugin
-Version: ${project.version}
-Goal Prefix: vsinstaller
-
-This plugin has 1 goal:
-
-vsinstaller:install
- Description: Installs Visual Studio 2005 addin.
+mvn help:describe -DgroupId=org.apache.npanday.plugins
-DartifactId=maven-compile-plugin -Dversion=${project.version}
----
~~TODO: add a troubleshooting guide and reference here in case it all goes
wrong
If you don't intend to use the Visual Studio Add-in, you can now
{{{../advanced/index.html} get started using NPanday's Maven extensions}}.
-* Installing the Visual Studio Add-in
-
- To install the Add-in, first ensure that Visual Studio is not running.
-
- Next, from a command prompt with the path set as indicated above, run the
following command. This command will generate the addin and copies the
necessary libraries needed to
- run the addin to a default location <<C:\\[PROGRAMFILES]\\NPanday>>>.
-
-----
-mvn org.apache.npanday.plugins:maven-vsinstaller-plugin:[version]:install
-----
-
- You can also specify the location where you want the libraries to be copied
by running the following command:
-
-----
-mvn org.apache.npanday.plugins:maven-vsinstaller-plugin:[version]:install
-DinstallationLocation=url
-----
-
- <<Note:>> On Windows Vista, Windows 7 and above, you will need to run the
command as an administrator. This can be
- done by starting the command prompt using the <Run as
administrator> option.
-
- After running the <<<maven-vsinstaller-plugin>>> the add-in will be located
here:
- <<<C:\\Documents and Settings\\[user_home]\\My Documents\\Visual Studio
2005\\Addins\\NPanday.VisualStudio.AddIn>>>
- (or equivalent for Visual Studio 2008 or Visual Studio 2010).
-
- More information on how to verify the Add-in installation are located at the
end of this guide.
-
Installing the Visual Studio Add-in using the NPanday Installer
NPanday Installer allows user to use NPanday automatically without the
hassle of downloading the repository and running commands to install it. It
will
- generate the repository and the add-ins for both VS2005 and VS2008.
+ generate the repository and the add-ins for all versions of Visual Studio.
To launch the NPanday Setup, click the installer twice,
Modified: incubator/npanday/trunk/site/src/site/apt/guide/vs/quickstart.apt
URL:
http://svn.apache.org/viewvc/incubator/npanday/trunk/site/src/site/apt/guide/vs/quickstart.apt?rev=1616142&r1=1616141&r2=1616142&view=diff
==============================================================================
--- incubator/npanday/trunk/site/src/site/apt/guide/vs/quickstart.apt (original)
+++ incubator/npanday/trunk/site/src/site/apt/guide/vs/quickstart.apt Wed Aug
6 10:00:40 2014
@@ -28,9 +28,7 @@ Quick Start Guide
* Starting the Add-in
- Start Visual Studio ensuring that your PATH is set correctly, as described
in the installation guide.
-
- Next, in Visual Studio start the NPanday Build System from Tools>NPanday
Build System. You will see NPanday starting
+ In Visual Studio start the NPanday Build System from Tools>NPanday Build
System. You will see NPanday starting
in the Visual Studio Output pane.
<Note:> After you start the NPanday Build System and it is running, it no
longer appears as an option on the Tools
