Make builds able to depend on external projects (#291)

* Make builds able to depend on external projects

Builds are now able to load external projects and depend on them
as if they were local submodules.

`import $file.external.path.build`

* Disambiguate "dest" for foreign modules.

* Calling modules loaded from external directories "Foreign" to avoid
conflicting with the already existing concept of "ExternalModule".
* Amended the way `dest` is computed for foreign modules
* Added tests to check that the source paths and dest are as expected
* Added a test to show that local modules do not conflict with foreign
modules when they are named the same

* WIP windows build fail

* Added bootstrapping step in CYGWIN CI job

* * Revert externalOutPath deletion
* Add documentation for foreign-modules

* reverting appveyor changes

* Disabling Foreign modules tests against Java9

See https://github.com/lihaoyi/mill/issues/302

1 files changed, 38 insertions, 1 deletions

diff --git a/docs/pages/5 - Modules.md b/docs/pages/5 - Modules.md
index 9b35af5f..1d8f3d87 100644
--- a/docs/pages/5 - Modules.md
+++ b/docs/pages/5 - Modules.md
@@ -155,4 +155,41 @@ that is shared by the entire build: for example,
 `mill.scalalib.ScalaWorkerApi/scalaWorker` provides a shared Scala compilation
 service & cache that is shared between all `ScalaModule`s, and
 `mill.scalalib.GenIdea/idea` lets you generate IntelliJ projects without
-needing to define your own `T.command` in your `build.sc` file
\ No newline at end of file
+needing to define your own `T.command` in your `build.sc` file
+
+## Foreign Modules 
+
+Mill can load other mill projects from external (or sub) directories, 
+using Ammonite's `$file` magic import, allowing to depend on foreign modules. 
+This allows, for instance, to depend on other projects' sources, or split 
+your build logic into smaller files.
+     
+
+For instance, assuming the following stucture : 
+
+```text
+foo/
+    build.sc
+    bar/
+        build.sc 
+baz/
+    build.sc     
+```
+
+you can write the following in `foo/build.sc` : 
+
+```scala
+
+import $file.bar.build
+import $file.^.baz.build
+import mill._ 
+
+def someFoo = T {
+
+    ^.baz.build.someBaz(...)
+    bar.build.someBar(...) 
+    ...
+}
+```
+
+The output of the foreign tasks will be cached under `foo/out/foreign-modules/`.