Flesh out support for shading third party libraries library and add example docs (500USD Bounty)

[lihaoyi]

---

From the maintainer Li Haoyi: I'm putting a 500USD bounty on this issue, payable by bank transfer on a merged PR implementing this.

---

We need to be able to depend on shaded third-party libraries, have the original library properly excluded from the runClasspath, and instead replaced by the shaded classfiles. Right now we can shade stuff in assembly using AssemblyRules, but shading should also apply to:

1. run
2. jar (which should include the shaded dependency)
3. publishLocal/publishAll (which should publish jars containing the shaded classes transitively and no dependency on the original and/or an exclusion),
4. runClasspath (e.g. if someone wants to use the classfiles in a Jvm.runSubprocess or Jvm.runClassLoader it should exclude the original and include the shaded classes)

There's some design space here to explore.

Should have an example under javalib/dependencies.adoc for shading Java using jarjar, scalalib/dependencies.adoc using https://github.com/eed3si9n/jarjar-abrams, maybe something for kotlin

[lefou]

We already have a dependency on jarajar-abrams to provide the Relocate assembly rule.

mill/scalalib/src/mill/scalalib/Assembly.scala

Line 81 in b66ef93

case class Relocate(from: String, to: String) extends Rule

[lihaoyi]

I think this is a broader topic than just assembly. For example, if I shade an upstream library, I should be able to publish to Maven Central and bundle the shaded library, with the normal library <dependency> metadata removed. Same as if I shade a library and a downstream module in the same build depends on me

[lefou]

The dependency going to be shaded should be declared as compileIvyDeps or compileModuleDeps.

[lihaoyi]

But compile*Deps is not sufficient: all that does is ensure the originsl classfiles are not included in the jar, which is correct, but i also want the shaded classfiles included somehow in the jar (not assembly) so it can be used at runtime.