=================
Inspect the build
=================

.. howto::
   :id: taskhelp
   :title: Show or search help for a command, task, or setting
   :type: command

   help compile

The ``help`` command is used to show available commands and search the help for commands, tasks, or settings.
If run without arguments, ``help`` lists the available commands.

::

    > help
    
      help                         Displays this help message or prints detailed help on 
                                      requested commands (run 'help <command>').
      about                        Displays basic information about sbt and the build.
      reload                       (Re)loads the project in the current directory
      ...

::

    > help compile

If the argument passed to ``help`` is the name of an existing command, setting or task, the help
for that entity is displayed.  Otherwise, the argument is interpreted as a regular expression that
is used to search the help of all commands, settings and tasks.

The ``tasks`` command is like ``help``, but operates only on tasks.
Similarly, the ``settings`` command only operates on settings.

See also ``help help``, ``help tasks``, and ``help settings``.

.. howto::
   :id: listtasks
   :title: List available tasks
   :type: command

   tasks

The ``tasks`` command, without arguments, lists the most commonly used tasks.
It can take a regular expression to search task names and descriptions.
The verbosity can be increased to show or search less commonly used tasks.
See ``help tasks`` for details.


.. howto::
   :id: listsettings
   :title: List available settings
   :type: command

   settings

The ``settings`` command, without arguments, lists the most commonly used settings.
It can take a regular expression to search setting names and descriptions.
The verbosity can be increased to show or search less commonly used settings.
See ``help settings`` for details.

.. howto::
   :id: dependencies
   :title: Display forward and reverse dependencies of a setting or task
   :type: command

   inspect compile

The ``inspect`` command displays several pieces of information about a given setting or task, including
the dependencies of a task/setting as well as the tasks/settings that depend on the it.  For example,

.. code-block:: console

    > inspect test:compile
    ...
    [info] Dependencies:
    [info] 	test:compile::compileInputs
    [info] 	test:compile::streams
    [info] Reverse dependencies:
    [info] 	test:definedTestNames
    [info] 	test:definedSbtPlugins
    [info] 	test:printWarnings
    [info] 	test:discoveredMainClasses
    [info] 	test:definedTests
    [info] 	test:exportedProducts
    [info] 	test:products
    ...

See the :doc:`/Detailed-Topics/Inspecting-Settings` page for details.

.. howto::
   :id: taskdependencytree
   :title: Display tree of setting/task dependencies
   :type: command

   inspect compile

In addition to displaying immediate forward and reverse dependencies as described in the previous section,
the ``inspect`` command can display the full dependency tree for a task or setting.
For example,

.. code-block:: console
    
    > inspect tree clean
    [info] *:clean = Task[Unit]
    [info]   +-*:cleanFiles = List(<project>/lib_managed, <project>/target)
    [info]   | +-{.}/*:managedDirectory = lib_managed
    [info]   | +-*:target = target
    [info]   |   +-*:baseDirectory = <project>
    [info]   |     +-*:thisProject = Project(id: demo, base: <project>, ...
    [info]   |     
    [info]   +-*:cleanKeepFiles = List(<project>/target/.history)
    [info]     +-*:history = Some(<project>/target/.history)
    ...

For each task, ``inspect tree`` show the type of the value generated by the task.
For a setting, the ``toString`` of the setting is displayed.
See the :doc:`/Detailed-Topics/Inspecting-Settings` page for details on the ``inspect`` command.

.. howto::
   :id: description
   :title: Display the description and type of a setting or task
   :type: command

   help compile

While the ``help``, ``settings``, and ``tasks`` commands display a description of a task,
the ``inspect`` command also shows the type of a setting or task and the value of a setting.
For example:

.. code-block:: console

    > inspect update
    [info] Task: sbt.UpdateReport
    [info] Description:
    [info] 	Resolves and optionally retrieves dependencies, producing a report.
    ...
    

.. code-block:: console

    > inspect scalaVersion
    [info] Setting: java.lang.String = 2.9.2
    [info] Description:
    [info] 	The version of Scala used for building.
    ...

See the :doc:`/Detailed-Topics/Inspecting-Settings` page for details.

.. howto::
   :id: delegates
   :title: Display the delegation chain of a setting or task
   :type: command

   inspect compile

See the :doc:`/Detailed-Topics/Inspecting-Settings` page for details.

.. howto::
   :id: related
   :title: Display related settings or tasks
   :type: command

   inspect compile

The ``inspect`` command can help find scopes where a setting or task is defined.
The following example shows that different options may be specified to the Scala
for testing and API documentation generation.

.. code-block:: console

    > inspect scalacOptions
    ...
    [info] Related:
    [info] 	compile:doc::scalacOptions
    [info] 	test:scalacOptions
    [info] 	*/*:scalacOptions
    [info] 	test:doc::scalacOptions

See the :doc:`/Detailed-Topics/Inspecting-Settings` page for details.

.. howto::
   :id: projects
   :title: Show the list of projects and builds
   :type: command
   
   projects

The ``projects`` command displays the currently loaded projects.
The projects are grouped by their enclosing build and the current project is indicated by an asterisk.
For example,

.. code-block:: console

    > projects
    [info] In file:/home/user/demo/
    [info] 	 * parent
    [info] 	   sub
    [info] In file:/home/user/dep/
    [info] 	   sample


.. howto::
   :id: session
   :title: Show the current session (temporary) settings
   :type: command
   
   session list

``session list`` displays the settings that have been added at the command line for the current project.  For example,

.. code-block:: console

    > session list
      1. maxErrors := 5
      2. scalacOptions += "-explaintypes"

``session list-all`` displays the settings added for all projects.
For details, see ``help session``.

.. howto::
   :id: about
   :title: Show basic information about sbt and the current build
   :type: command
   
   about

.. code-block:: console

    > about
    [info] This is sbt 0.12.0
    [info] The current project is {file:~/code/sbt.github.com/}default
    [info] The current project is built against Scala 2.9.2
    [info] Available Plugins: com.jsuereth.ghpages.GhPages, com.jsuereth.git.GitPlugin, com.jsuereth.sbtsite.SitePlugin
    [info] sbt, sbt plugins, and build definitions are using Scala 2.9.2
    
.. howto::
   :id: value
   :title: Show the value of a setting
   :type: command
   
   show name

The ``inspect`` command shows the value of a setting as part of its output, but the ``show`` command is dedicated to this job.
It shows the output of the setting provided as an argument.  For example,

.. code-block:: console

    > show organization
    [info] com.github.sbt 

The ``show`` command also works for tasks, described next.

.. howto::
   :id: result
   :title: Show the result of executing a task
   :type: command
   
   show update

.. code-block:: console

    > show update
    ... <output of update> ...
    [info] Update report:
    [info] 	Resolve time: 122 ms, Download time: 5 ms, Download size: 0 bytes
    [info] 	compile:
    [info] 		org.scala-lang:scala-library:2.9.2: ...

The ``show`` command will execute the task provided as an argument and then print the result.
Note that this is different from the behavior of the ``inspect`` command (described in other sections),
which does not execute a task and thus can only display its type and not its generated value.

.. howto::
   :id: classpath
   :title: Show the classpath used for compilation or testing
   :type: command
   
   show compile:dependencyClasspath

.. code-block:: console

    > show compile:dependencyClasspath
    ...
    [info] ArrayBuffer(Attributed(~/.sbt/0.12.0/boot/scala-2.9.2/lib/scala-library.jar))
    
For the test classpath,

.. code-block:: console

    > show test:dependencyClasspath
    ...
    [info] ArrayBuffer(Attributed(~/code/sbt.github.com/target/scala-2.9.2/classes), Attributed(~/.sbt/0.12.0/boot/scala-2.9.2/lib/scala-library.jar), Attributed(~/.ivy2/cache/junit/junit/jars/junit-4.8.2.jar))

.. howto::
   :id: applications
   :title: Show the main classes detected in a project
   :type: command
   
   show compile:discoveredMainClasses

sbt detects the classes with public, static main methods for use by the ``run`` method and to tab-complete the ``runMain`` method.
The ``discoveredMainClasses`` task does this discovery and provides as its result the list of class names.
For example, the following shows the main classes discovered in the main sources:

.. code-block:: console
    
    > show compile:discoveredMainClasses
    ... <runs compile if out of date> ...
    [info] List(org.example.Main)

.. howto::
   :id: tests
   :title: Show the test classes detected in a project
   :type: command
   
   show definedTestNames

sbt detects tests according to fingerprints provided by test frameworks.
The ``definedTestNames`` task provides as its result the list of test names detected in this way.
For example,

.. code-block:: console
    
    > show test:definedTestNames
    ... < runs test:compile if out of date > ...
    [info] List(org.example.TestA, org.example.TestB)
