From 7c7fc257f1d366b33df9e481ebc0b519c0abc59c Mon Sep 17 00:00:00 2001 From: Olivier Melois Date: Thu, 5 Apr 2018 11:48:03 +0100 Subject: [PATCH] Documentation : correct way to query envVars Adds documentation about the Ctx.Env API to indicate that the user should not use `System.getenv` https://github.com/lihaoyi/mill/issues/257 --- docs/pages/3 - Tasks.md | 20 ++++++++++++++++---- 1 file changed, 16 insertions(+), 4 deletions(-) diff --git a/docs/pages/3 - Tasks.md b/docs/pages/3 - Tasks.md index ca6def42415..7079735ef46 100644 --- a/docs/pages/3 - Tasks.md +++ b/docs/pages/3 - Tasks.md @@ -165,10 +165,10 @@ There are several APIs available to you within the body of a `T{...}` or `T.command{...}` block to help your write the code implementing your Target or Command: -### mill.util.Ctx.DestCtx +### mill.util.Ctx.Dest - `T.ctx().dest` -- `implicitly[mill.util.Ctx.DestCtx]` +- `implicitly[mill.util.Ctx.Dest]` This is the unique `out/classFiles/dest/` path or `out/run/dest/` path that is assigned to every Target or Command. It is cleared before your task runs, and @@ -177,10 +177,10 @@ artifacts. This is guaranteed to be unique for every `Target` or `Command`, so you can be sure that you will not collide or interfere with anyone else writing to those same paths. -### mill.util.Ctx.LogCtx +### mill.util.Ctx.Log - `T.ctx().log` -- `implicitly[mill.util.Ctx.LogCtx]` +- `implicitly[mill.util.Ctx.Log]` This is the default logger provided for every task. While your task is running, `System.out` and `System.in` are also redirected to this logger. The logs for a @@ -188,6 +188,18 @@ task are streamed to standard out/error as you would expect, but each task's specific output is also streamed to a log file on disk e.g. `out/run/log` or `out/classFiles/log` for you to inspect later. +### mill.util.Ctx.Env + +- `T.ctx().env` +- `implicitly[mill.util.Ctx.Env]` + +Mill keeps a long-lived JVM server to avoid paying the cost of recurrent +classloading. Because of this, running `System.getenv` in a task might not yield +up to date environment variables, since it will be initialised when the server +starts, rather than when the client executes. To circumvent this, mill's client +sends the environment variables to the server as it sees them, and the server +makes them available as a `Map[String, String]` via the `Ctx` API. + ## Other Tasks - [Anonymous Tasks](#anonymous-tasks), defined using `T.task{...}`