From b2d480b2b9de6091a8e7c135dac5dd2c0f653c6b Mon Sep 17 00:00:00 2001
From: Olivier Mélois <baccata64@gmail.com>
Date: Thu, 25 Apr 2019 13:59:29 +0200
Subject: Beginning of Bloop integration  (#595)

* Sync with latest versions, started bloop connection

* BloopModule back to the bare minimum

* Added first Bloop related unit-tests

* More tests

* Fixed global module usage.

* Added resolution in bloop config

* More tests, using correct repository list

* revert dev change

* Changed moduleSourceMap implementation

* Using path-dependant trait for the module

This facilitates testing by preventing the trait from referencing
a global module.

* Added semanticDB to bloopConfig

* Added documentation

* Install returns pathRefs instead of paths

* bumped semanticDB

* Better use of mill's cache, avoid duplication of work

* addressing comments
---
 docs/pages/9 - Contrib Modules.md | 59 +++++++++++++++++++++++++++++++++++++++
 1 file changed, 59 insertions(+)

(limited to 'docs')

diff --git a/docs/pages/9 - Contrib Modules.md b/docs/pages/9 - Contrib Modules.md
index 1b9b55fa..0d65512b 100644
--- a/docs/pages/9 - Contrib Modules.md	
+++ b/docs/pages/9 - Contrib Modules.md	
@@ -912,3 +912,62 @@ Publishing to custom local Maven repository
 [40/40] project.publishM2Local
 Publishing to /tmp/m2repo
 ```
+
+### Bloop
+
+This plugin generates [bloop](https://scalacenter.github.io/bloop/) configuration 
+from your build file, which lets you use the bloop CLI for compiling, and makes 
+your scala code editable in [Metals](https://scalameta.org/metals/)   
+
+
+#### Quickstart:
+```scala
+// build.sc (or any other .sc file it depends on, including predef) 
+// Don't forget to replace VERSION
+import $ivy.`com.lihaoyi::mill-contrib-bloop:VERSION`
+```
+
+Then in your terminal : 
+
+```
+> mill mill.contrib.Bloop/install 
+```
+
+#### Mix-in
+
+You can mix-in the `Bloop.Module` trait with any JavaModule to quickly access 
+the deserialised configuration for that particular module: 
+
+```scala
+// build.sc 
+import mill._ 
+import mill.scalalib._
+import mill.contrib.Bloop
+
+object MyModule extends ScalaModule with Bloop.Module {
+  def myTask = T { bloop.config() }
+}
+``` 
+
+#### Note regarding metals: 
+
+Generating the bloop config should be enough for metals to pick it up and for 
+features to start working in vscode (or the bunch of other editors metals supports). 
+However, note that this applies only to your project sources. Your mill/ammonite related
+`.sc` files are not yet supported by metals. 
+
+The generated bloop config references the semanticDB compiler plugin required by
+metals to function. If need be, the version of semanticDB can be overriden by 
+extending `mill.contrib.bloop.BloopImpl` in your own space. 
+
+#### Note regarding current mill support in bloop 
+
+The mill-bloop integration currently present in the [bloop codebase](https://github.com/scalacenter/bloop/blob/master/integrations/mill-bloop/src/main/scala/bloop/integrations/mill/MillBloop.scala#L10)
+will be deprecated in favour of this implementation. 
+
+#### Caveats: 
+
+At this time, only Java/ScalaModule are processed correctly. ScalaJS/ScalaNative integration will 
+be added in a near future. 
+
+
-- 
cgit v1.2.3