Update BUILDING.txt

BUILDING.txt

@@ -3,6 +3,15 @@ Building NUnit 3.0
 NUnit 3.0 consists of three separate layers: the Framework, the Engine and the Console Runner. 
 The source code is kept in a single GitHub repository at http://github.com/nunit/nunit.git.
 
+Note that assemblies in one layer must not reference those in any other layer, except as follows:
+ * The console runner references the nunit.engine.api assembly, but not the nunit.engine assembly.
+ * Tests in any layer reference nunit.framework.
+Developers should make sure not to introduce any other references.
+
+There are two ways to build NUnit: using the solution file in an IDE or through the build script.
+
+SOLUTION BUILD
+
 All three layers are built together using a single Visual Studio solution (nunit.sln on Windows 
 and nunit.linux.sln on Linux), which may be built with Visual Studio 2012+, SharpDevelop.
 or MonoDevelop.
@@ -15,28 +24,56 @@ components are placed directly in the bin directory while framework components e
 subdirectories net-2.0, net4.0, sl-5.0, portable and netcf-3.5. Future platform
 builds will cause new subdirectories to be created.
 
-The build shell script and build.cmd script are provided as an easy way to locate and
-run msbuild / xbuild. They pass their arguments directly to msbuild / xbuild.
+BUILD SCRIPT
 
-Note that assemblies in one layer must not reference those in any other layer, except as follows:
- * The console runner references the nunit.engine.api assembly, but not the nunit.engine assembly.
- * Tests in any layer reference nunit.framework.
-Developers should make sure not to introduce any other references.
+We use Cake (http://cake-build.net) to build NUnit for distribution. The primary script that controls
+building, running tests and packaging is build.cake. We modify build.cake when we need to add new 
+targets or change the way the build is done. Normally build.cake is not invoked directly but through
+a build.ps1 (on Windows) or build.sh (on Linux). These two scripts are provided by the Cake project
+and ensure that Cake is properly installed before trying to run the cake script. This helps the
+build to work on CI servers using newly created agents to run the build and we generally run it
+the same way on our own machines.
 
-There is an MsBuild script (NUnit.proj) that can do builds as well as running tests
-and packaging releases. It can be run under MsBuild or XBuild. The most important 
-targets are CleanAll, BuildAll, TestAll and Package. For other targets, please
-refer to the script itself.
+The build shell script and build.cmd script are provided as an easy way to run the above commands.
+In addition to passing their arguments through to build.cake, they can supply added arguments
+through the CAKE_ARGS environment variable. The rest of this document will assume use of these commands.
 
-To create a new release:
- * Update CHANGES.txt with the latest changes.
- * Update NUnit.proj to specify the release version and suffix using property definitions 
-   near the start of the script.
- * Use Visual Studio 2012 or higher to rebuild everything for the Release configuration.
-   (The NUnit.proj script currently does not build everything due to a bug.)
- * Retest the build using 'build NUnit.proj /t:TestAll /p:Configuration=Release'
- * Use Visual Studio 2008 to rebuild the nunitCF solution and test manually using an emulator.
- * Run 'build NUnit.proj /t:Package /p:Configuration=Release' to create packages
- * Create the release on GitHub and upload the binary zip, source zip and three NuGet packages.
- * Upload the three NuGet packages to NuGet.org.
+There is one case in which use of the CAKE_ARGS environment variable will be essential, if not necessary.
+If you are running builds on a 32-bit Windows system, you must always supply the -Experimental argument
+to the build. Use set CAKE_ARGS=-Experimental to ensure this is always done and avoid having to type
+it out each time.
 
+Key arguments to build.cmd / build:
+ * -Target, -t <task>              The task to run - see below.
+ * -Configuration|-c [Release|Debug] The configuration to use (default is Release)
+ * -Experimental|-e                  Use the experimental build of Roslyn
+
+The build.cake script contains a large number of interdependent tasks. The most 
+important top-level tasks to use are listed here:
+ * Build               Builds everything. This is the default if no target is given.
+ * Rebuild             Cleans the output directory and builds everything
+ * Test                Runs all tests. Dependent on Build. (These tasks currently do the
+ * TestAll             Runs all tests. Dependent on Build.  same thing. This may change.
+ * TestAllFrameworks   Runs all framework tests. Dependent on Build.
+ * Test45              Tests the 4.5 framework without building first.
+ * Test40              Tests the 4.0 framework without building first.
+ * Test20              Tests the 2.0 framework without building first.
+ * TestPortable        Tests the portable framework without building first.
+ * TestSL              Tests the Silverlight framework without building first.
+ * TestCF              Tests the compact framework without building first.
+ * TestEngine          Runs all engine tests. Dependent on Build.
+ * TestConsole         Runs the console tests. Dependent on Build.
+ * Package             Creates all packages without building first. See Note below.
+
+NOTES:
+ 1. By design, the Package target does not depend on Build. This is to allow re-packaging
+    when necessary without changing the binaries themselves. Of course, this means that
+    you have to be very careful that the build is up to date before packaging.
+
+ 2. If the compact framework is not installed on a machine, building and testing tasks
+    for CF are skipped and a warning is issued.
+
+ 3. Currently, Silverlight must be installed or an error occurs when trying to build or
+    test it. We will be changing this soon to match the strategy for CF.
+
+ 4. For additional targets, refer to the build.cake script itself.