Add introduction to the setting system.

src/sphinx/Architecture/Core-Principles.rst

@@ -63,8 +63,63 @@ done through the ``Setting[_]`` sequence.
 Introduction to Settings
 ========================
 
-TODO - Discuss ``Setting[_]``
+A Setting represents the means of constructing the value of one particular ``AttributeKey[_]`` in the ``AttributeMap`` of build state.  A setting consists of two pieces:
 
-TODO - Transition into ``Task[_]``
+1. The ``AttributeKey[T]`` where the value of the setting should be assigned.
+2. An ``Intialize[T]`` object which is able to construct the value for this setting.
 
-TODO - Transition into ``InputTask[_]``
+Sbt's intiialization time is basically just taking a sequence of these ``Setting[_]`` objects and running their initialization objects and then storing the value into the ``AttributeMap``.   This means overwriting an exisitng value at a key is as easy as appending a
+``Setting[_]`` to the end of the sequence which does so.
+
+Where it gets interesting is that ``Initialize[T]`` can depend on other ``AttributeKey[_]``s in the build state.  Each ``Initialize[_]``
+can pull values from any ``AttributeKey[_]`` in the build state's ``AttributeMap`` to compute its value.  Sbt ensures a few things
+when it comes to ``Initialize[_]`` dependencies:
+
+1. There can be no circular dependencies
+2. If one ``Initialize[_]`` depends on another ``Initialize[_]`` key, then *all* associated ``Initialize[_]`` blocks for that key must
+   have run before we load the value.
+
+The above image shows a bit of what's expLet's look at what gets stored for the setting ::
+
+  normalizedName := normalize(name.value)
+
+
+
+.. Note: This image comes from a google drawing: https://docs.google.com/a/typesafe.com/drawings/d/1hvE89XVrQiXdSBsgaQgQGTmcO44EBZPg4_0WxKXU7Pw/edit
+.. Feel free to request access to modify as appropriate.
+
+.. image:: overview-setting-example.png
+
+
+Here, a ``Setting[_]`` is constructed that understands it depends on the value in the ``name`` AttributeKey.  Its intiialize block first grabs the value of the ``name`` key, then runs the function normalize on it to compute its value.
+
+This represents the core mechanism of how to construct sbt's build state.  Conceptually, at some point we have a graph of dependencies
+and initialization functions which we can use to construct the first build state.   Once this is completed, we can then start to process
+user requests.
+
+
+
+Introduction to Tasks
+=====================
+
+The next layer in sbt is around these user request, or tasks.   When a user configures a build, they are defining a set of repeatable
+tasks that they can run on their project.  Things like ``compile`` or ``test``.   These tasks *also* have a dependency graph, where
+e.g. the ``test`` task requires that ``compile`` has run before it can successfully execute.
+
+Sbt's defines a class ``Task[T]``.  The ``T`` type parameter represents the type of data returned by a task.  Remember the tenenats of
+sbt?  "All things have types" and "Dependencies are explicit" both hold true for tasks.   Sbt promotes a style of task dependencies that
+is closer to functional programming:  Return data for your users rather than using shared mutable state.
+
+Most build tools communciate over the filesystem, and indeed sbt, by necessity, does some of this.  However, for stable parallelization it is far better to keep tasks isolated on the filesystem and communicate directly through types.
+
+Similarly to how a ``Setting[_]`` stores both dependencies and an initialization function, a ``Task[_]`` stores both its 
+``Task[_]``dependencies and its behavior (a function).  
+
+
+
+
+TODO - More on ``Task[_]``
+
+TODO - Transition into ``InputTask[_]``, rehash Command
+
+TODO - Tansition into Scope.