Skip to content

Commit

Permalink
Integrate new kotlin examples into docsite (#3592)
Browse files Browse the repository at this point in the history
Apart from adding `.adoc` pages for all the kotlin examples
#3585
#3589
#3555 and the palantir java
format example from
https://github.com/com-lihaoyi/mill/pulls?page=2&q=is%3Apr+is%3Aclosed,
I moved some docs around: the first few things under `Foo Example
Builds` really belong under `Foo Module Configuration`, the
`external/libraries/` folder should be in `depth/libraries/`

The test for `Custom Main Argument Parsers` seems to have bitrotted
since it was implemented, and it accidentally wasn't running in the test
suite before so we didn't notice. For now just disabling that test and
we can fix it later
  • Loading branch information
lihaoyi authored Sep 23, 2024
1 parent adb19da commit b06486c
Show file tree
Hide file tree
Showing 235 changed files with 362 additions and 179 deletions.
2 changes: 1 addition & 1 deletion ci/test-mill-dev.sh
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,7 @@

set -eux

EXAMPLE=example/scalalib/builds/9-realistic
EXAMPLE=example/scalalib/builds/4-realistic

rm -rf $EXAMPLE/out

Expand Down
2 changes: 1 addition & 1 deletion ci/test-mill-release.sh
Original file line number Diff line number Diff line change
Expand Up @@ -5,7 +5,7 @@ set -eux
# Build Mill
./mill -i dist.assembly

EXAMPLE=example/scalalib/builds/9-realistic
EXAMPLE=example/scalalib/builds/4-realistic

rm -rf $EXAMPLE/out

Expand Down
5 changes: 5 additions & 0 deletions docs/modules/ROOT/nav.adoc
Original file line number Diff line number Diff line change
Expand Up @@ -26,6 +26,11 @@
.xref:Kotlin_Intro_to_Mill.adoc[]
* xref:Kotlin_Installation_IDE_Support.adoc[]
* xref:Kotlin_Builtin_Commands.adoc[]
* xref:Kotlin_Module_Config.adoc[]
* xref:Kotlin_Build_Examples.adoc[]
* xref:Testing_Kotlin_Projects.adoc[]
* xref:Linting_Kotlin_Projects.adoc[]
* xref:Publishing_Kotlin_Projects.adoc[]
.Build Tool Comparisons
* xref:Case_Study_Mill_vs_Maven.adoc[]
Expand Down
8 changes: 4 additions & 4 deletions docs/modules/ROOT/pages/Bundled_Libraries.adoc
Original file line number Diff line number Diff line change
Expand Up @@ -9,29 +9,29 @@ Mill comes bundled with a set of external Open Source libraries and projects.
Project page:: https://github.com/com-lihaoyi/os-lib
ScalaDoc:: https://javadoc.io/doc/com.lihaoyi/os-lib_2.13/latest/index.html

include::example/external/libraries/1-oslib.adoc[]
include::example/depth/libraries/1-oslib.adoc[]

== uPickle

Project page:: https://github.com/com-lihaoyi/upickle
ScalaDoc:: https://javadoc.io/doc/com.lihaoyi/upickle_2.13/latest/index.html

include::example/external/libraries/2-upickle.adoc[]
include::example/depth/libraries/2-upickle.adoc[]

== Requests-Scala

Project page:: https://github.com/com-lihaoyi/requests-scala
ScalaDoc:: https://javadoc.io/doc/com.lihaoyi/requests_2.13/latest/index.html

include::example/external/libraries/3-requests.adoc[]
include::example/depth/libraries/3-requests.adoc[]

== MainArgs


Project page:: https://github.com/com-lihaoyi/mainargs
Scaladoc:: https://javadoc.io/doc/com.lihaoyi/mainargs_2.13/latest/index.html

include::example/external/libraries/4-mainargs.adoc[]
include::example/depth/libraries/4-mainargs.adoc[]

== Coursier

Expand Down
17 changes: 3 additions & 14 deletions docs/modules/ROOT/pages/Java_Build_Examples.adoc
Original file line number Diff line number Diff line change
Expand Up @@ -21,30 +21,19 @@ Many of the APIs covered here are listed in the API documentation:
* {mill-doc-url}/api/latest/mill/scalalib/MavenModule.html[`mill.scalalib.MavenModule`]
* {mill-doc-url}/api/latest/mill/scalalib/JavaModule.html[`mill.scalalib.JavaModule`]
== Common Configuration Overrides

include::example/javalib/builds/1-common-config.adoc[]

== Custom Tasks

include::example/javalib/builds/2-custom-tasks.adoc[]

== Overriding Tasks

include::example/javalib/builds/3-override-tasks.adoc[]
== Nesting Modules

include::example/javalib/builds/4-nested-modules.adoc[]
include::example/javalib/builds/1-nested-modules.adoc[]

== Maven-Compatible Modules

include::example/javalib/builds/8-compat-modules.adoc[]
include::example/javalib/builds/2-compat-modules.adoc[]


== Realistic Java Example Project

include::example/javalib/builds/9-realistic.adoc[]
include::example/javalib/builds/4-realistic.adoc[]


== Example Builds for Real Projects
Expand Down
38 changes: 25 additions & 13 deletions docs/modules/ROOT/pages/Java_Module_Config.adoc
Original file line number Diff line number Diff line change
Expand Up @@ -11,52 +11,64 @@ for `JavaModule`.

Many of the APIs covered here are listed in the API documentation:

* {mill-doc-url}/api/latest/mill/scalalib/JavaModule.html[mill.javaalib.JavaModule]
* {mill-doc-url}/api/latest/mill/scalalib/JavaModule.html[mill.javalib.JavaModule]
== Common Configuration Overrides

include::example/javalib/module/1-common-config.adoc[]

== Custom Tasks

include::example/javalib/module/2-custom-tasks.adoc[]

== Overriding Tasks

include::example/javalib/module/3-override-tasks.adoc[]


== Compilation & Execution Flags

include::example/javalib/module/1-compilation-execution-flags.adoc[]
include::example/javalib/module/4-compilation-execution-flags.adoc[]

== Adding Ivy Dependencies

include::example/javalib/module/2-ivy-deps.adoc[]
include::example/javalib/module/5-ivy-deps.adoc[]

== Runtime and Compile-time Dependencies

include::example/javalib/module/3-run-compile-deps.adoc[]
include::example/javalib/module/6-run-compile-deps.adoc[]

== Classpath and Filesystem Resources

include::example/javalib/module/5-resources.adoc[]
include::example/javalib/module/7-resources.adoc[]

== Annotation Processors

include::example/javalib/module/6-annotation-processors.adoc[]
include::example/javalib/module/8-annotation-processors.adoc[]

== Javadoc Config

include::example/javalib/module/7-docjar.adoc[]
include::example/javalib/module/9-docjar.adoc[]

== Unmanaged Jars

include::example/javalib/module/8-unmanaged-jars.adoc[]
include::example/javalib/module/10-unmanaged-jars.adoc[]

== Specifying the Main Class

include::example/javalib/module/9-main-class.adoc[]
include::example/javalib/module/11-main-class.adoc[]

== Downloading Non-Maven Jars

include::example/javalib/module/10-downloading-non-maven-jars.adoc[]
include::example/javalib/module/12-downloading-non-maven-jars.adoc[]

== Customizing the Assembly

include::example/javalib/module/11-assembly-config.adoc[]
include::example/javalib/module/13-assembly-config.adoc[]

== Repository Config

include::example/javalib/module/12-repository-config.adoc[]
include::example/javalib/module/14-repository-config.adoc[]

=== Maven Central: Blocked!

Expand Down Expand Up @@ -86,5 +98,5 @@ If you are using millw, a more permanent solution could be to set the environmen
== Native C Code with JNI
include::example/javalib/module/13-jni.adoc[]
include::example/javalib/module/15-jni.adoc[]
36 changes: 36 additions & 0 deletions docs/modules/ROOT/pages/Kotlin_Build_Examples.adoc
Original file line number Diff line number Diff line change
@@ -0,0 +1,36 @@
= Kotlin Build Examples

++++
<script>
gtag('config', 'AW-16649289906');
</script>
++++

On this page, we will explore the Mill build tool via a series of simple Kotlin
example projects. Each project demonstrates one particular feature of the Mill
build tool, and is also an executable codebase you can download and run. By the
end of this page, you will be familiar with how to configure Mill to work with
realistic Kotlin codebases: cross-building, testing, and publishing them.


Many of the APIs covered here are listed in the API documentation:

* {mill-doc-url}/api/latest/mill/main/RootModule.html[`mill.kotlinlib.RootModule`]
* {mill-doc-url}/api/latest/mill/scalalib/TestModule$.html[`mill.kotlinlib.TestModule`]
* {mill-doc-url}/api/latest/mill/scalalib/PublishModule.html[`mill.kotlinlib.PublishModule`]
* {mill-doc-url}/api/latest/mill/kotlinlib/KotlinMavenModule.html[`mill.kotlinlib.KotlinMavenModule`]
* {mill-doc-url}/api/latest/mill/kotlinlib/KotlinModule.html[`mill.kotlinlib.KotlinModule`]
== Nesting Modules

include::example/kotlinlib/builds/1-nested-modules.adoc[]

== Maven-Compatible Modules

include::example/kotlinlib/builds/2-compat-modules.adoc[]


== Realistic Kotlin Example Project

include::example/kotlinlib/builds/4-realistic.adoc[]

104 changes: 104 additions & 0 deletions docs/modules/ROOT/pages/Kotlin_Module_Config.adoc
Original file line number Diff line number Diff line change
@@ -0,0 +1,104 @@
= Kotlin Module Configuration

++++
<script>
gtag('config', 'AW-16649289906');
</script>
++++

This page goes into more detail about the various configuration options
for `KotlinModule`.

Many of the APIs covered here are listed in the API documentation:

* {mill-doc-url}/api/latest/mill/kotlinlib/KotlinModule.html[mill.kotlinlib.KotlinModule]
== Common Configuration Overrides

include::example/kotlinlib/module/1-common-config.adoc[]

== Custom Tasks

include::example/kotlinlib/module/2-custom-tasks.adoc[]

== Overriding Tasks

include::example/kotlinlib/module/3-override-tasks.adoc[]


== Compilation & Execution Flags

include::example/kotlinlib/module/4-compilation-execution-flags.adoc[]

== Adding Ivy Dependencies

include::example/kotlinlib/module/5-ivy-deps.adoc[]

== Runtime and Compile-time Dependencies

include::example/kotlinlib/module/6-run-compile-deps.adoc[]

== Classpath and Filesystem Resources

include::example/kotlinlib/module/7-resources.adoc[]

== Kotlin Compiler Plugins

include::example/kotlinlib/module/8-kotlin-compiler-plugins.adoc[]

== Javadoc Config

include::example/kotlinlib/module/9-docjar.adoc[]

== Unmanaged Jars

include::example/kotlinlib/module/10-unmanaged-jars.adoc[]

== Specifying the Main Class

include::example/kotlinlib/module/11-main-class.adoc[]

== Downloading Non-Maven Jars

include::example/kotlinlib/module/12-downloading-non-maven-jars.adoc[]

== Customizing the Assembly

include::example/kotlinlib/module/13-assembly-config.adoc[]

== Repository Config

include::example/kotlinlib/module/14-repository-config.adoc[]

=== Maven Central: Blocked!

Under some circumstances (e.g. corporate firewalls), you may not have access maven central. The typical symptom will be error messages which look like this;

----
1 targets failed
mill.scalalib.ZincWorkerModule.classpath
Resolution failed for 1 modules:
--------------------------------------------
com.lihaoyi:mill-scalalib-worker_2.13:0.11.1
not found: C:\Users\partens\.ivy2\local\com.lihaoyi\mill-scalalib-worker_2.13\0.11.1\ivys\ivy.xml
download error: Caught java.io.IOException (Server returned HTTP response code: 503 for URL: https://repo1.maven.org/maven2/com/lihaoyi/mill-scalalib-worker_2.13/0.11.1/mill-scalalib-worker_2.13-0.11.1.pom) while downloading https://repo1.maven.org/maven2/com/lihaoyi/mill-scalalib-worker_2.13/0.11.1/mill-scalalib-worker_2.13-0.11.1.pom
----
It is expected that basic commands (e.g. clean) will not work, as Mill saying it is unable to resolve it's own, fundamental, dependencies. Under such circumstances, you will normally have access to some proxy, or other corporate repository which resolves maven artefacts. The strategy is simply to tell mill to use that instead.
The idea is to set an environment variable COURSIER_REPOSITORIES (see coursier docs). The below command should set the environment variable for the current shell, and then run the mill command.
----
COURSIER_REPOSITORIES=https://packages.corp.com/artifactory/maven/ mill resolve _
----
If you are using millw, a more permanent solution could be to set the environment variable at the top of the millw script, or as a user environment variable etc.
== Native C Code with JNI
include::example/kotlinlib/module/15-jni.adoc[]
5 changes: 5 additions & 0 deletions docs/modules/ROOT/pages/Linting_Java_Projects.adoc
Original file line number Diff line number Diff line change
Expand Up @@ -9,6 +9,7 @@ gtag('config', 'AW-16649289906');
This page will discuss common topics around enforcing the code quality of Java
codebases using the Mill build tool


== ErrorProne

include::example/javalib/linting/1-error-prone.adoc[]
Expand All @@ -17,6 +18,10 @@ include::example/javalib/linting/1-error-prone.adoc[]

include::example/javalib/linting/2-checkstyle.adoc[]

== AutoFormatting with Palantir Java Format

include::example/javalib/linting/3-palantirformat.adoc[]

== Jacoco Code Coverage

Mill supports Java code coverage analysis via the mill-jacoco plugin. See the
Expand Down
18 changes: 18 additions & 0 deletions docs/modules/ROOT/pages/Linting_Kotlin_Projects.adoc
Original file line number Diff line number Diff line change
@@ -0,0 +1,18 @@
= Linting Kotlin Projects

++++
<script>
gtag('config', 'AW-16649289906');
</script>
++++

This page will discuss common topics around enforcing the code quality of Kotlin
codebases using the Mill build tool

== Detekt

include::example/kotlinlib/linting/1-detekt.adoc[]

== KtLint

include::example/kotlinlib/linting/2-ktlint.adoc[]
2 changes: 2 additions & 0 deletions docs/modules/ROOT/pages/Linting_Scala_Projects.adoc
Original file line number Diff line number Diff line change
Expand Up @@ -15,6 +15,8 @@ include::example/scalalib/linting/1-scalafmt.adoc[]

== Scoverage Code Coverage

include::example/scalalib/linting/2-contrib-scoverage.adoc[]

Mill supports Scala code coverage analysis via the Scoverage contrib plugin. See the
contrib plugin documentation for more details:

Expand Down
15 changes: 15 additions & 0 deletions docs/modules/ROOT/pages/Publishing_Kotlin_Projects.adoc
Original file line number Diff line number Diff line change
@@ -0,0 +1,15 @@
= Publishing Kotlin Projects

++++
<script>
gtag('config', 'AW-16649289906');
</script>
++++

This page will discuss common topics around publishing your Kotlin projects for others to use

== Publishing Locally

include::example/kotlinlib/publishing/2-publish-module.adoc[]

include::partial$Publishing_Footer.adoc[]
Loading

0 comments on commit b06486c

Please sign in to comment.