Updated Build Instructions (markdown)

Build-Instructions.md

@@ -10,14 +10,49 @@ Change into the newly checked out directory and initialize the Git submodules:
 
 `git submodule update --init --recursive`
 
-This will ensure you have a full checkout of both the OpenID Connect project and the SECOAUTH dependency.
+This will ensure you have a full checkout of both the OpenID Connect project and the SECOAUTH dependency. This command **must** be re-run whenever the reference to the upstream project changes.
+
+## A Note about Git Submodules
+
+A Git submodule stores not only a reference to a particular Git repository (which is bound to a directory through the .gitmodules file) but also a reference to a **specific revision** of that repository. Therefore, if the reference to the submodule is updated, this shows up as a change in the parent module. If there are any local changes checked in to the submodule, and this reference is pushed up to the repository, this will break the build for anyone pulling down updates since their local copy of the submodule will not have the revision now referenced by the parent project.
+
+# Project Layout
+
+The project has a hierarchical layout:
+
+    OpenID-Connect-Java-Spring-Server
+     +-- openid-connect-common
+     +-- openid-connect-client
+     +-- openid-connect-server
+     \-- spring-security-oauth
+         +-- spring-security-oauth2
+
+The root of the project contains a pom.xml file that references all sub-modules.
 
 # Building with Maven
 
-The project uses Maven to build. 
+The project uses the Maven "package" directive to build from the root of the project:
 
 `mvn package`
 
+By building in the root, Maven automatically builds all dependencies. Building directly in the submodules will likely fail as the cross-dependencies on other portions of the project (such as the server's dependency on common) will not have been built yet.
+
+This recursively builds the spring-security-oauth library as well as all portions of the project. The build process produces a .jar file for openid-connect-common and openid-connect-client and a .war file for openid-connect-server.
+
+## Common Maven Options
+
+To skip unit tests, add this option:
+
+`mvn -DskipTests package`
+
+To skip JavaDoc generation (which is triggered automatically in SECOAUTH):
+
+`mvn -Dmaven.javadoc.skip=true package`
+
+To configure an http and https proxy, add this option (especially because Maven on Linux doesn't always read the settings.xml file):
+
+`mvn -Dhttp.proxyHost=proxy -Dhttp.proxyPort=80 -Dhttps.proxyHost=proxy -Dhttps.proxyPort=80 package`
+
 # Deploying with Tomcat
 
 To deploy the Server, copy the generated .war file to the tomcat directory, such as: