Skip to content

Commit

Permalink
.
Browse files Browse the repository at this point in the history
  • Loading branch information
lihaoyi committed Oct 4, 2024
1 parent 3b53189 commit f199707
Show file tree
Hide file tree
Showing 21 changed files with 126 additions and 125 deletions.
2 changes: 1 addition & 1 deletion contrib/gitlab/readme.adoc
Original file line number Diff line number Diff line change
Expand Up @@ -33,7 +33,7 @@ object lib extends ScalaModule with GitlabPublishModule {

`publishVersion` and `pomSettings` come from `PublishModule`. `GitlabPublishModule`
requires you to
set `publishRepository` for target of artifact publishing. Note that this *must* be a
set `publishRepository` for task of artifact publishing. Note that this *must* be a
project repository defined by project id (publishing to other type of repositories is not
https://docs.gitlab.com/ee/user/packages/maven_repository/#use-the-gitlab-endpoint-for-maven-packages[supported]).

Expand Down
2 changes: 1 addition & 1 deletion contrib/playlib/readme.adoc
Original file line number Diff line number Diff line change
Expand Up @@ -168,7 +168,7 @@ object core extends PlayApiModule {

== Commands equivalence

Mill commands are targets on a named build. For example if your build is called `core`:
Mill commands are tasks on a named build. For example if your build is called `core`:

* compile: `core.compile`
* run: _NOT Implemented yet_. It can be approximated with `mill -w core.runBackground` but this
Expand Down
8 changes: 4 additions & 4 deletions contrib/versionfile/readme.adoc
Original file line number Diff line number Diff line change
Expand Up @@ -4,8 +4,8 @@

This plugin provides helpers for updating a version file and committing the changes to git.

*Note: You can still make manual changes to the version file in-between execution of the targets provided by the module.*
*Each target operates on the version file as is at the time of execution.*
*Note: You can still make manual changes to the version file in-between execution of the tasks provided by the module.*
*Each task operates on the version file as is at the time of execution.*

== Quickstart

Expand Down Expand Up @@ -83,7 +83,7 @@ In this example, it would look for the file `version` in the same directory as t

== Set release version

The `setReleaseVersion` target removes the `-SNAPSHOT` identifier from the version,
The `setReleaseVersion` task removes the `-SNAPSHOT` identifier from the version,
then overwrites the previous content in the version file with this new version.

=== Example
Expand All @@ -99,7 +99,7 @@ This will update the version file to contain `0.1.0`.

== Set next version

The `setNextVersion` target bumps the version and changes it to a snapshot version,
The `setNextVersion` task bumps the version and changes it to a snapshot version,
then overwrites the previous content in the version file with this new version.

=== Parameters
Expand Down
2 changes: 1 addition & 1 deletion docs/modules/ROOT/pages/depth/cross-builds.adoc
Original file line number Diff line number Diff line change
Expand Up @@ -19,7 +19,7 @@ include::partial$example/depth/cross/11-default-cross-module.adoc[]

include::partial$example/depth/cross/2-cross-source-path.adoc[]

== Using Cross Modules from Outside Targets
== Using Cross Modules from Outside Tasks

include::partial$example/depth/cross/3-outside-dependency.adoc[]

Expand Down
6 changes: 3 additions & 3 deletions docs/modules/ROOT/pages/depth/evaluation-model.adoc
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
= The Mill Evaluation Model
:page-aliases: The_Mill_Evaluation_Model.adoc

Evaluating a Mill target typically goes through the following phases:
Evaluating a Mill task typically goes through the following phases:

1. *Compilation*: Mill compiles the `build.mill` to classfiles, following the
<<_the_mill_bootstrapping_process>> to eventually produce a `RootModule` object
Expand Down Expand Up @@ -73,8 +73,8 @@ the overall workflow remains fast even for large projects:
* xref:depth/tasks.adoc#_targets[Target]s only re-evaluate if their input ``Task``s
change.

* xref:depth/tasks.adoc#_persistent_targets[Task.Persistent]s preserve the `T.dest` folder on disk between runs,
allowing for finer-grained caching than Mill's default target-by-target
* xref:depth/tasks.adoc#_persistent_tasks[Task.Persistent]s preserve the `T.dest` folder on disk between runs,
allowing for finer-grained caching than Mill's default task-by-task
caching and invalidation

* xref:depth/tasks.adoc#_workers[Task.Worker]s are kept in-memory between runs where possible, and only
Expand Down
6 changes: 3 additions & 3 deletions docs/modules/ROOT/pages/depth/library-deps.adoc
Original file line number Diff line number Diff line change
Expand Up @@ -130,7 +130,7 @@ object main extends JavaModule {

== Compile-only dependencies (`provided` scope)

If you want to use a dependency only at compile time, you can declare it with the `compileIvyDeps` target.
If you want to use a dependency only at compile time, you can declare it with the `compileIvyDeps` task.

.Example
[source,scala]
Expand All @@ -142,12 +142,12 @@ def compileIvyDeps = Agg(

When Mill generated file to interact with package manager like `pom.xml` for Maven repositories, such compile-only dependencies are mapped to the `provided` scope.

Please note, that dependencies with `provided` scope will never be resolved transitively. Hence, the name "provided", as the target runtime needs to "provide" them, if they are needed.
Please note, that dependencies with `provided` scope will never be resolved transitively. Hence, the name "provided", as the task runtime needs to "provide" them, if they are needed.


== Runtime dependencies

If you want to declare dependencies to be used at runtime (but not at compile time), you can use the `runIvyDeps` targets.
If you want to declare dependencies to be used at runtime (but not at compile time), you can use the `runIvyDeps` tasks.

.Example
[source,scala]
Expand Down
2 changes: 1 addition & 1 deletion docs/modules/ROOT/pages/depth/modules.adoc
Original file line number Diff line number Diff line change
Expand Up @@ -42,7 +42,7 @@ object Bar extends mill.define.ExternalModule {
----

In the above example, `Bar` is an `ExternalModule` living within the `foo`
Java package, containing the `baz` target and `qux` command. Those can be run
Java package, containing the `baz` task and `qux` command. Those can be run
from the command line via:

[source,bash]
Expand Down
20 changes: 10 additions & 10 deletions docs/modules/ROOT/pages/depth/out-dir.adoc
Original file line number Diff line number Diff line change
Expand Up @@ -51,23 +51,23 @@ out/
└── mill-server/VpZubuAK6LQHHN+3ojh1LsTZqWY=-1/
----

<1> The `main` directory contains all files associated with target and submodules of the `main` module.
<2> The `compile` target has tried to access its scratch space via `T.dest`. Here you will find the actual compile results.
<3> Two targets printed something out while they ran. You can find these outputs in the `*.log` files.
<4> Three targets are overridden but re-use the result of their `super`-targets in some way. You can find these result under the `*.super/` path.
<1> The `main` directory contains all files associated with tasks and submodules of the `main` module.
<2> The `compile` task has tried to access its scratch space via `T.dest`. Here you will find the actual compile results.
<3> Two tasks printed something out while they ran. You can find these outputs in the `*.log` files.
<4> Three tasks are overridden but re-use the result of their `super`-tasks in some way. You can find these result under the `*.super/` path.

== Target Metadata and Cached Files
== Task Metadata and Cached Files

Each named task (``Target`` or ``Command``) that is run has a representation in the `out/` directory structure.

The _module_ structure is reflected in the directories, so that each module of your project has a uniquely associated subdirectory under the `out/` directory.

Each _target_ is associated with one or multiple files and directories under its module directory.
The following files can be found for a target `foo`:
Each _task_ is associated with one or multiple files and directories under its module directory.
The following files can be found for a task `foo`:

`foo.json`::
the cache-key and JSON-serialized return-value of the
`Target`/`Command`.
`Task`/`Command`.
The return-value can also be retrieved via `mill show foo.compile`.
Binary blobs are typically not included in `foo.json`, and instead stored as separate binary files in `foo.dest/` which are then referenced
by `foo.json` via `PathRef` references.
Expand All @@ -82,7 +82,7 @@ conflicting with another `Task`, but can name files within `foo.dest/` arbitrar
optional, the `stdout`/`stderr` of the `Task`. This is also streamed to the console during evaluation.

`foo.super/`::
optional, holds target metadata for overridden targets, so whenever you use a `super.foo()` in your `foo` target, you will find the metadata of the inherited task(s) under this directory.
optional, holds task metadata for overridden tasks, so whenever you use a `super.foo()` in your `foo` task, you will find the metadata of the inherited task(s) under this directory.


The `out/` folder is intentionally kept simple and user-readable.
Expand All @@ -95,7 +95,7 @@ rebuilt, e.g. by deleting the `+out/main/+` or `+out/main/compile.*+` folders, b

[WARNING]
--
Cleaning some target state by manually deleting files under `out/` may be convenient, but you need to be careful to always delete the `foo.json` file whenever you delete a `foo.dest/` or `foo.super/`. Otherwise, you risk running into hard to diagnose issues later.
Cleaning some task state by manually deleting files under `out/` may be convenient, but you need to be careful to always delete the `foo.json` file whenever you delete a `foo.dest/` or `foo.super/`. Otherwise, you risk running into hard to diagnose issues later.

Instead, you should always give the `clean` command a try before manually deleting some file under `out/`.
--
Expand Down
54 changes: 27 additions & 27 deletions docs/modules/ROOT/pages/depth/query-syntax.adoc
Original file line number Diff line number Diff line change
@@ -1,12 +1,12 @@
= Target Query Syntax
:page-aliases: Target_Query_Syntax.adoc
= Task Query Syntax
:page-aliases: Task_Query_Syntax.adoc

When interacting with Mill from the CLI, you often need to select targets or modules.
In most places, where Mill accepts a target, it really accepts a target selector query, which is the name of a target in its simplest form, but it can also contain wildcards, type pattern and other special syntax, making it a powerful tool to select specific targets.
When interacting with Mill from the CLI, you often need to select tasks or modules.
In most places, where Mill accepts a task, it really accepts a task selector query, which is the name of a task in its simplest form, but it can also contain wildcards, type pattern and other special syntax, making it a powerful tool to select specific tasks.

== Selecting dedicated targets
== Selecting dedicated tasks

When invoking Mill, the simplest way to run a target is to give it with a fully qualified names.
When invoking Mill, the simplest way to run a task is to give it with a fully qualified names.

Examples:

Expand All @@ -16,17 +16,17 @@ Examples:
> mill foo.testCached
----

.Understanding target paths and path segments
.Understanding task paths and path segments
****
Each Mill module and target has a unique path.
Each Mill module and task has a unique path.
Each part of the path is called _segment_.
Segments are separated with a dot (`.`).
They look like regular Scala class name qualifiers.
There are two kind of segments: _label segments_ and _cross segments_.
_Label segments_ are the components of a target path and have the same restriction as Scala identifiers.
_Label segments_ are the components of a task path and have the same restriction as Scala identifiers.
They must start with a letter and may contain letters, numbers and a limited set of special characters `-` (dash), `_` (underscore).
They are used to denote Mill modules, tasks, but in the case of xref:depth/modules.adoc#external-modules[external modules] their Scala package names.
Expand All @@ -37,17 +37,17 @@ When combined with <<type-filters,qualified type filter>> which contain dots (`.
****

[#select-multiple-targets]
== Selecting multiple targets
[#select-multiple-tasks]
== Selecting multiple tasks

If you want to select more than one target, you have multiple options:
If you want to select more than one task, you have multiple options:

* <<enumerations,Use target enumerations>>
* <<enumerations,Use task enumerations>>
* <<wildcards,Use wildcard selections>>
* <<type-filters,Specify type filters on wildcard selections>>
* <<add-target-selector,Use `+` to use more than one target selector>>
* <<add-task-selector,Use `+` to use more than one task selector>>

You can also combine these techniques to properly select your targets
You can also combine these techniques to properly select your tasks

[#enumerations]
== Enumerations
Expand All @@ -57,7 +57,7 @@ Inside the curly braces you can place two or more selector paths, separated with

Examples:

* `{foo,bar}` simple enumerates two targets, `foo` and `bar`
* `{foo,bar}` simple enumerates two tasks, `foo` and `bar`
* `foo.{compile,run}` expands to `foo.compile` and `foo.run`
* `+{_,foo.bar}.baz+` expands to `+_.baz+` and `foo.bar.baz`

Expand All @@ -82,9 +82,9 @@ There are two wildcards, you can use as path segment.
* `+__+` The double underscore acts as a placeholder for many segments.
In particular, it can represent an empty segment.

With wildcards, you can get explicit control over the position of a target in the build tree.
With wildcards, you can get explicit control over the position of a task in the build tree.

E.g. the filter `+_._._.jar+` will match all jar targets, that are on the third-level of the build tree.
E.g. the filter `+_._._.jar+` will match all jar tasks, that are on the third-level of the build tree.

[#type-filters]
== Type filters for wildcard selections
Expand All @@ -96,7 +96,7 @@ For module paths this means, the represented module needs to be an instance of t
A type filter always starts with a wildcard (`+_+`, `+__+`) followed by a colon (`:`) and finally the _type qualifier_.

The type is matched by its name and optionally by its enclosing types and packages, separated by a `.` sign.
Since this is also used to separate target path segments, a type selector segment containing a `.` needs to be enclosed in parentheses.
Since this is also used to separate task path segments, a type selector segment containing a `.` needs to be enclosed in parentheses.
A fully qualified type can be denoted with the `+_root_+` package.

[sh]
Expand All @@ -121,19 +121,19 @@ You can also add more than one type filters to a wildcard.
> mill resolve "__:JavaModule:^ScalaModule:^TestModule.jar"
----

NOTE: Type filter are currently only supported for module selections, but not for target selections.
That means, you can't filter based on the result type of a target.
NOTE: Type filter are currently only supported for module selections, but not for task selections.
That means, you can't filter based on the result type of a task.

[#add-target-selector]
== Start a new target selector with `+`
[#add-task-selector]
== Start a new task selector with `+`

On the Mill CLI you can also start a complete new target selector with the `+` sign.
On the Mill CLI you can also start a complete new task selector with the `+` sign.

There is a subtile difference between the expansion of <<enumerations,enumerations>>, <<wildcards,wildcards>> and <<type-filters,wildcards with type filters>> in contrast to the <<add-target-selector,start of a new selector with `+`>>.
There is a subtile difference between the expansion of <<enumerations,enumerations>>, <<wildcards,wildcards>> and <<type-filters,wildcards with type filters>> in contrast to the <<add-task-selector,start of a new selector with `+`>>.

For all the former versions, Mill parses them into a complex but single target selector path and subsequent parameters are used for all resolved targets.
For all the former versions, Mill parses them into a complex but single task selector path and subsequent parameters are used for all resolved tasks.

Whereas the `+` start a completely new selector path to which you can also provide a different parameter list. This is important when using xref:depth/tasks.adoc#commands[command targets] which can accept their own parameters. The `JavaModule.run` command is an example.
Whereas the `+` start a completely new selector path to which you can also provide a different parameter list. This is important when using xref:depth/tasks.adoc#commands[command tasks] which can accept their own parameters. The `JavaModule.run` command is an example.

----
> mill foo.run hello # <1>
Expand Down
10 changes: 5 additions & 5 deletions docs/modules/ROOT/pages/depth/tasks.adoc
Original file line number Diff line number Diff line change
Expand Up @@ -5,10 +5,10 @@ One of Mill's core abstractions is its _Task Graph_: this is how Mill defines,
orders and caches work it needs to do, and exists independently of any support
for building Scala.

Mill target graphs are primarily built using methods and macros defined on
`mill.define.Target`, aliased as `T` for conciseness:
Mill task graphs are primarily built using methods and macros defined on
`mill.define.Task`, aliased as `T` for conciseness:

- {mill-doc-url}/api/latest/mill/define/Target$.html[mill.define.Target]
- {mill-doc-url}/api/latest/mill/define/Task$.html[mill.define.Task]
== Task Cheat Sheet

Expand Down Expand Up @@ -44,9 +44,9 @@ include::partial$example/depth/tasks/3-anonymous-tasks.adoc[]

include::partial$example/depth/tasks/4-inputs.adoc[]

=== Persistent Targets
=== Persistent Tasks

include::partial$example/depth/tasks/5-persistent-targets.adoc[]
include::partial$example/depth/tasks/5-persistent-tasks.adoc[]

=== Workers

Expand Down
4 changes: 2 additions & 2 deletions docs/modules/ROOT/pages/extending/meta-build.adoc
Original file line number Diff line number Diff line change
Expand Up @@ -24,8 +24,8 @@ $ mill --meta-level 1 mill.scalalib.scalafmt.ScalafmtModule/reformatAll sources
----

* `--meta-level 1` selects the first meta-build. Without any customization, this is the only built-in meta-build.
* `mill.scalalib.scalafmt.ScalafmtModule/reformatAll` is a generic task to format scala source files with Scalafmt. It requires the targets that refer to the source files as argument
* `sources` this selects the `sources` targets of the meta-build, which at least contains the `build.mill`.
* `mill.scalalib.scalafmt.ScalafmtModule/reformatAll` is a generic task to format scala source files with Scalafmt. It requires the tasks that refer to the source files as argument
* `sources` this selects the `sources` tasks of the meta-build, which at least contains the `build.mill`.

== Finding plugin updates

Expand Down
8 changes: 4 additions & 4 deletions docs/modules/ROOT/pages/extending/thirdparty-plugins.adoc
Original file line number Diff line number Diff line change
Expand Up @@ -335,7 +335,7 @@ Found undeclared dependencies: (add these to ivyDeps)
Found unimported dependencies: (remove these from ivyDeps)
ivy"org.typelevel::cats-effect:3.3.6",
1 targets failed
1 tasks failed
main.checkExplicitDeps Found 1 undeclared dependencies, 1 unimported dependencies
----

Expand Down Expand Up @@ -367,7 +367,7 @@ object g8 extends G8Module {
}
----

The most common target you'd then use is `mill g8.validate`.
The most common task you'd then use is `mill g8.validate`.

== Git

Expand Down Expand Up @@ -821,7 +821,7 @@ Project home: https://github.com/sake92/mill-powershell-completion

== PublishM2

_Since Mill `0.6.1-27-f265a4` there is a built-in `publishM2Local` target in `PublishModule`._
_Since Mill `0.6.1-27-f265a4` there is a built-in `publishM2Local` task in `PublishModule`._

Mill plugin to publish artifacts into a local Maven repository.

Expand Down Expand Up @@ -970,7 +970,7 @@ object project extends ScalaModule with ScalafixModule {
/project/project/src/MyClass.scala:12:11: error: [DisableSyntax.var] mutable state should be avoided
private var hashLength = 7
^^^
1 targets failed
1 tasks failed
project.fix A Scalafix linter error was reported
----

Expand Down
2 changes: 1 addition & 1 deletion docs/modules/ROOT/pages/javalib/module-config.adoc
Original file line number Diff line number Diff line change
Expand Up @@ -76,7 +76,7 @@ include::partial$example/javalib/module/14-repository-config.adoc[]
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
1 tasks failed
mill.scalalib.ZincWorkerModule.classpath
Resolution failed for 1 modules:
--------------------------------------------
Expand Down
2 changes: 1 addition & 1 deletion docs/modules/ROOT/pages/kotlinlib/module-config.adoc
Original file line number Diff line number Diff line change
Expand Up @@ -78,7 +78,7 @@ include::partial$example/kotlinlib/module/14-repository-config.adoc[]
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
1 tasks failed
mill.scalalib.ZincWorkerModule.classpath
Resolution failed for 1 modules:
--------------------------------------------
Expand Down
Loading

0 comments on commit f199707

Please sign in to comment.