Skip to content

Commit 2bd9057

Browse files
eed3si9need3si9n
committed
updated site
1 parent c512475 commit 2bd9057

35 files changed

Lines changed: 1772 additions & 64 deletions

‎2.x/docs/en/print.html‎

Lines changed: 197 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -2873,13 +2873,206 @@ <h4 id="forking-tests"><a class="header" href="#forking-tests">Forking tests</a>
28732873
28742874
where `customTestListener` is of type `sbt.TestReportListener`.
28752875
-->
2876-
<div style="break-before: page; page-break-before: always;"></div><h1 id="sbt-publish"><a class="header" href="#sbt-publish">sbt publish</a></h1>
2876+
<div style="break-before: page; page-break-before: always;"></div><h1 id="sbt-inspect"><a class="header" href="#sbt-inspect">sbt inspect</a></h1>
28772877
<h2 id="synopsis-5"><a class="header" href="#synopsis-5">Synopsis</a></h2>
2878+
<p><code>sbt</code> <code>inspect</code> [<em>subproject</em> / ] [ <em>config</em> / ] <em>task</em><br>
2879+
<code>sbt</code> <code>inspect actual</code> [<em>subproject</em> / ] [ <em>config</em> / ] <em>task</em><br>
2880+
<code>sbt</code> <code>inspect tree</code> [<em>subproject</em> / ] [ <em>config</em> / ] <em>task</em></p>
2881+
<h2 id="description-5"><a class="header" href="#description-5">Description</a></h2>
2882+
<p>The <code>inspect</code> command provides a means to inspect the task and setting graph.
2883+
For instace, it can be used to determine which setting should be
2884+
modified to affect another task.</p>
2885+
<h3 id="value-description-and-provided-by"><a class="header" href="#value-description-and-provided-by">Value, Description, and Provided By</a></h3>
2886+
<p>The first piece of information provided by <code>inspect</code> is the type of a
2887+
task or the value and type of a setting.</p>
2888+
<p>For example,</p>
2889+
<pre><code class="language-bash">$ sbt inspect libraryDependencies
2890+
[info] Setting: interface scala.collection.immutable.Seq =
2891+
List(org.scala-lang:scala3-library:3.7.2,
2892+
org.typelevel:toolkit:0.1.29,
2893+
org.typelevel:toolkit-test:0.1.29:test)
2894+
[info] Description:
2895+
[info] Declares managed dependencies.
2896+
[info] Provided by:
2897+
[info] ProjectRef(uri("file:/tmp/aaa/"), "aaa") / libraryDependencies
2898+
....
2899+
</code></pre>
2900+
<p>The following section of output
2901+
is labeled "Provided by". This shows the actual scope where the setting
2902+
is defined.</p>
2903+
<p>This shows that <code>libraryDependencies</code> has been defined on the current
2904+
project (<code>ProjectRef(uri("file:/tmp/aaa/"), "aaa")</code>).</p>
2905+
<h3 id="related-settings"><a class="header" href="#related-settings">Related Settings</a></h3>
2906+
<p>The <em>Related</em> section of <code>inspect</code> output lists all of the definitions
2907+
of a key. For example,</p>
2908+
<pre><code class="language-bash">&gt; inspect compile
2909+
...
2910+
[info] Related:
2911+
[info] Test / compile
2912+
</code></pre>
2913+
<p>This shows that in addition to the requested <code>Compile / compile</code> task,
2914+
there is also a <code>Test / compile</code> task.</p>
2915+
<h3 id="dependencies-1"><a class="header" href="#dependencies-1">Dependencies</a></h3>
2916+
<p>Forward dependencies show the other settings (or tasks) used to define a
2917+
setting (or task). Reverse dependencies go the other direction, showing
2918+
what uses a given setting. <code>inspect</code> provides this information based on
2919+
either the requested dependencies or the actual dependencies. Requested
2920+
dependencies are those that a setting directly specifies. Actual
2921+
settings are what those dependencies get resolved to. This distinction
2922+
is explained in more detail in the following sections.</p>
2923+
<h4 id="requested-dependencies"><a class="header" href="#requested-dependencies">Requested Dependencies</a></h4>
2924+
<p>As an example, we'll look at <code>console</code>:</p>
2925+
<pre><code class="language-bash">$ sbt inspect console
2926+
...
2927+
[info] Dependencies:
2928+
[info] Compile / console / initialCommands
2929+
[info] Compile / console / compilers
2930+
[info] Compile / state
2931+
[info] Compile / console / cleanupCommands
2932+
[info] Compile / console / taskTemporaryDirectory
2933+
[info] Compile / console / scalaInstance
2934+
[info] Compile / console / scalacOptions
2935+
[info] Compile / console / fullClasspath
2936+
[info] Compile / fileConverter
2937+
[info] Compile / console / streams
2938+
2939+
...
2940+
</code></pre>
2941+
<p>This shows the inputs to the <code>console</code> task. We can see that it gets its
2942+
classpath and options from <code>Compile / console / fullClasspath</code> and
2943+
<code>Compile / console / scalacOptions</code>. The information provided by the <code>inspect</code>
2944+
command can thus assist in finding the right setting to change. The
2945+
convention for keys, like <code>console</code> and <code>fullClasspath</code>, is that the
2946+
Scala identifier is camel case, while the String representation is
2947+
lowercase and separated by dashes. The Scala identifier for a
2948+
configuration is uppercase to distinguish it from tasks like <code>compile</code>
2949+
and <code>test</code>. For example, we can infer from the previous example how to
2950+
add code to be run when the Scala interpreter starts up:</p>
2951+
<pre><code class="language-scala">&gt; set Compile / console / initialCommands := "import mypackage._"
2952+
&gt; console
2953+
...
2954+
import mypackage._
2955+
...
2956+
</code></pre>
2957+
<p><code>inspect</code> showed that <code>console</code> used the setting
2958+
<code>Compile / console / initialCommands</code>. Translating the <code>initialCommands</code>
2959+
string to the Scala identifier gives us <code>initialCommands</code>. <code>compile</code>
2960+
indicates that this is for the main sources. <code>console /</code> indicates that
2961+
the setting is specific to <code>console</code>. Because of this, we can set the
2962+
initial commands on the <code>console</code> task without affecting the
2963+
<code>consoleQuick</code> task, for example.</p>
2964+
<h4 id="actual-dependencies"><a class="header" href="#actual-dependencies">Actual Dependencies</a></h4>
2965+
<p><code>inspect actual &lt;scoped-key&gt;</code> shows the actual dependency used. This is
2966+
useful because delegation means that the dependency can come from a
2967+
scope other than the requested one. Using <code>inspect actual</code>, we see
2968+
exactly which scope is providing a value for a setting. Combining
2969+
<code>inspect actual</code> with plain <code>inspect</code>, we can see the range of scopes
2970+
that will affect a setting. Returning to the example in Requested
2971+
Dependencies,</p>
2972+
<pre><code class="language-bash">$ sbt inspect actual console
2973+
...
2974+
[info] Dependencies:
2975+
[info] Compile / console / streams
2976+
[info] Global / taskTemporaryDirectory
2977+
[info] scalaInstance
2978+
[info] Compile / scalacOptions
2979+
[info] Global / initialCommands
2980+
[info] Global / cleanupCommands
2981+
[info] Compile / fullClasspath
2982+
[info] console / compilers
2983+
...
2984+
</code></pre>
2985+
<p>For <code>initialCommands</code>, we see that it comes from the global scope
2986+
(<code>Global</code>). Combining this with the relevant output from
2987+
<code>inspect console</code>:</p>
2988+
<pre><code>Compile / console / initialCommands
2989+
</code></pre>
2990+
<p>we know that we can set <code>initialCommands</code> as generally as the global
2991+
scope, as specific as the current project's <code>console</code> task scope, or
2992+
anything in between. This means that we can, for example, set
2993+
<code>initialCommands</code> for the whole project and will affect <code>console</code>:</p>
2994+
<pre><code class="language-scala">&gt; set initialCommands := "import mypackage._"
2995+
...
2996+
</code></pre>
2997+
<p>The reason we might want to set it here this is that other console tasks
2998+
will use this value now. We can see which ones use our new setting by
2999+
looking at the reverse dependencies output of <code>inspect actual</code>:</p>
3000+
<pre><code class="language-bash">$ sbt inspect actual Global/initialCommands
3001+
...
3002+
[info] Reverse dependencies:
3003+
[info] Compile / console
3004+
[info] consoleProject
3005+
[info] Test / console
3006+
[info] Test / consoleQuick
3007+
[info] Compile / consoleQuick
3008+
...
3009+
</code></pre>
3010+
<p>We now know that by setting <code>initialCommands</code> on the whole project, we
3011+
affect all console tasks in all configurations in that project. If we
3012+
didn't want the initial commands to apply for <code>consoleProject</code>, which
3013+
doesn't have our project's classpath available, we could use the more
3014+
specific task axis:</p>
3015+
<pre><code class="language-scala">&gt; set console / initialCommands := "import mypackage._"
3016+
&gt; set consoleQuick / initialCommands := "import mypackage._"`
3017+
</code></pre>
3018+
<p>or configuration axis:</p>
3019+
<pre><code class="language-scala">&gt; set Compile/　initialCommands := "import mypackage._"
3020+
&gt; set Test / initialCommands := "import mypackage._"
3021+
</code></pre>
3022+
<p>The next part describes the Delegates section, which shows the chain of
3023+
delegation for scopes.</p>
3024+
<h3 id="delegates"><a class="header" href="#delegates">Delegates</a></h3>
3025+
<p>A setting has a key and a scope. A request for a key in a scope A may be
3026+
delegated to another scope if A doesn't define a value for the key. The
3027+
delegation chain is well-defined and is displayed in the Delegates
3028+
section of the <code>inspect</code> command. The Delegates section shows the order
3029+
in which scopes are searched when a value is not defined for the
3030+
requested key.</p>
3031+
<p>As an example, consider the initial commands for <code>console</code> again:</p>
3032+
<pre><code class="language-bash">$ sbt inspect console/initialCommands
3033+
...
3034+
[info] Delegates:
3035+
[info] console / initialCommands
3036+
[info] initialCommands
3037+
[info] ThisBuild / console / initialCommands
3038+
[info] ThisBuild / initialCommands
3039+
[info] Zero / console / initialCommands
3040+
[info] Global / initialCommands
3041+
...
3042+
</code></pre>
3043+
<p>This means that if there is no value specifically for
3044+
<code>console/initialCommands</code>, the scopes listed under Delegates will be
3045+
searched in order until a defined value is found.</p>
3046+
<h3 id="inspect-tree"><a class="header" href="#inspect-tree">Inspect tree</a></h3>
3047+
<p>In addition to displaying immediate forward and reverse dependencies as
3048+
described in the previous section, the <code>inspect tree</code> command can display the
3049+
full dependency tree for a task or setting. For example,</p>
3050+
<pre><code class="language-bash">$ sbt inspect tree console
3051+
[info] Compile / console = Task[void]
3052+
[info] +-Global / cleanupCommands =
3053+
[info] +-console / compilers = Task[class xsbti.compile.Compilers]
3054+
[info] +-Compile / fullClasspath = Task[Seq[class sbt.internal.util.Attributed]]
3055+
[info] +-Global / initialCommands =
3056+
[info] +-scalaInstance = Task[class sbt.internal.inc.ScalaInstance]
3057+
[info] +-Compile / scalacOptions = Task[Seq[class java.lang.String]]
3058+
[info] +-Compile / console / streams = Task[interface sbt.std.TaskStreams]
3059+
[info] | +-Global / streamsManager = Task[interface sbt.std.Streams]
3060+
[info] |
3061+
[info] +-Global / taskTemporaryDirectory = target/....
3062+
[info] +-Global / fileConverter = sbt.internal.inc.MappedFileConverter@10095d95
3063+
[info] +-Global / state = Task[class sbt.State]
3064+
[info]
3065+
[success] elapsed: 0 s
3066+
</code></pre>
3067+
<p>For each task, <code>inspect tree</code> show the type of the value generated by
3068+
the task. For a setting, the <code>toString</code> of the setting is displayed.</p>
3069+
<div style="break-before: page; page-break-before: always;"></div><h1 id="sbt-publish"><a class="header" href="#sbt-publish">sbt publish</a></h1>
3070+
<h2 id="synopsis-6"><a class="header" href="#synopsis-6">Synopsis</a></h2>
28783071
<p><code>sbt</code> [<em>query</em> / ] <code>publish</code><br>
28793072
<code>sbt</code> [<em>query</em> / ] <code>publishSigned</code><br>
28803073
<code>sbt</code> [<em>query</em> / ] <code>publishLocal</code><br>
28813074
<code>sbt</code> [<em>query</em> / ] <code>publishM2</code></p>
2882-
<h2 id="description-5"><a class="header" href="#description-5">Description</a></h2>
3075+
<h2 id="description-6"><a class="header" href="#description-6">Description</a></h2>
28833076
<p>The publish family of tasks provide means for compiling and publishing your project.
28843077
<em>Publishing</em> in this context consists of
28853078
uploading a descriptor, such as a Maven POM or <code>ivy.xml</code>, and artifacts,
@@ -3043,7 +3236,7 @@ <h3 id="modifying-the-generated-pom"><a class="header" href="#modifying-the-gene
30433236
}
30443237
</code></pre>
30453238
<div style="break-before: page; page-break-before: always;"></div><h1 id="watch-command"><a class="header" href="#watch-command">Watch command</a></h1>
3046-
<h2 id="synopsis-6"><a class="header" href="#synopsis-6">Synopsis</a></h2>
3239+
<h2 id="synopsis-7"><a class="header" href="#synopsis-7">Synopsis</a></h2>
30473240
<p><code>sbt</code> <code>~</code> <em>command1</em><br>
30483241
<code>sbt</code> <code>~</code> <em>command1</em> [ <code>;</code> <em>command2</em> <code>;</code> ... ]</p>
30493242
<h2 id="descrption"><a class="header" href="#descrption">Descrption</a></h2>
@@ -3417,7 +3610,7 @@ <h3 id="nativelink"><a class="header" href="#nativelink">NativeLink</a></h3>
34173610
Global / remoteCacheHeaders += IO.read(BuildPaths.defaultGlobalBase / "nativelink_credential.txt").trim
34183611
</code></pre>
34193612
<div style="break-before: page; page-break-before: always;"></div><h1 id="artifact"><a class="header" href="#artifact">Artifact</a></h1>
3420-
<h2 id="description-6"><a class="header" href="#description-6">Description</a></h2>
3613+
<h2 id="description-7"><a class="header" href="#description-7">Description</a></h2>
34213614
<p>An artifact is a single file ready for publishing a specific version of a subproject. This is a concept that originated in <a href="https://maven.apache.org/ref/3.9.11/maven-core/artifact-handlers.html">Apache Maven</a> and <a href="https://ant.apache.org/ivy/history/2.3.0/terminology.html#artifact">Ivy</a>.</p>
34223615
<p>In the JVM ecosystem, common artifacts are Java archives, or JAR files.
34233616
Compressed package formats are often preferred because they are easier to manage, download, and store.</p>

0 commit comments

Comments
 (0)