Merge pull request #88 in G/mx from fix/document-urlrewrites to master

* commit '0fd0122ff3119a9c401348a2919a0828b7e8e91a':
  add documentation for URL rewriting

README.md

@@ -16,9 +16,34 @@ mx [global options] [command] [command-specific options]
 
 If no options or command is specified, `mx` prints information on the available options and commands, which will include any suite-specfic options and commands. Help for a specific command is obtained via `mx help <command>`. Global options are expected to have wide applicability to many commands and as such precede the command to be executed.
 
-For an example of `mx` usage, you can read the [Instructions][1] for the Graal project. 
+For an example of `mx` usage, you can read the [Instructions][1] for the Graal project.
 
-### mx environment variable processing ###
+### URL rewriting ###
+
+Mx includes support for the primary suite to be able to override the source URLs of imported suites.
+The suite level `urlrewrites` attribute allows regular expression URL rewriting. For example:
+```
+  "urlrewrites" : [
+    {
+      "https://git.acme.com/(.*).git" : {
+        "replacement" : r”https://my.company.com/foo-git-cache/\1.git",
+      }
+    },
+    {
+      "https://hg.acme.com/(.*)" : {
+        "replacement" : r”https://my.company.com/foo-hg-cache/\1",
+      }
+    }
+  ],
+```
+The rules are applied in definition order. Only rewrite rules from the primary suite are used meaning a suite may have to replicate the rewrite rules of its suite dependencies.
+This allows the primary suite to retain full control over where its dependencies are sourced from.
+
+Rewrite rules can also be specified by the `MX_URLREWRITES` environment variable.
+The value of this variable must either be a JSON object describing a single rewrite rule, a JSON array describing a list of rewrite rules or a file containing one of these JSON values.
+Rewrites rules specified by `MX_URLREWRITES` are applied after rules specified by the primary suite.
+
+### Environment variable processing ###
 
 Suites might require various environment variables to be defined for
 the suite to work and mx provides `env` files to cache this

mx_urlrewrites.py

@@ -32,7 +32,7 @@
 
 def register_urlrewrite(urlrewrite, onError=None):
     """
-    Appends a list of URL rewrite rules to the current rewrite rules.
+    Appends a URL rewrite rule to the current rewrite rules.
     A URL rewrite rule is a dict where the key is a regex for matching a URL and the value describes
     how to rewrite.