add docs

diff --git a/doc/manual.asciidoc b/doc/manual.asciidoc
index 03d27df..b01cdad 100644 (file)
--- a/doc/manual.asciidoc
+++ b/doc/manual.asciidoc
@@ -420,6 +420,57 @@ If the top-level Ninja file is specified as an output of any build
 statement and it is out of date, Ninja will rebuild and reload it
 before building the targets requested by the user.
 
+Pools
+~~~~~
+
+Pools allow you to allocate one or more rules or edges a finite number
+of concurrent jobs which is more tightly restricted than the total job
+number that you specify to ninja on the command line.
+
+This can be useful, for example, to restrict a particular expensive rule
+(like link steps for huge executables), or to restrict particular build
+statements which you know preform poorly when run concurrently.
+
+Each pool has a `depth` variable which is specified in the build file.
+The pool is then referred to with the `pool` variable on either a rule
+or a build statement.
+
+The jobs amount specified on the command line is always respected, no
+matter what pools you've set up.
+
+----------------
+# No more than 4 links at a time
+pool link_pool
+  depth = 4
+
+# No more than 1 heavy object at a time
+pool heavy_object_pool
+  depth = 1
+
+rule link
+  ...
+  pool = link_pool
+
+rule cc
+  ...
+
+# The link_pool is used here. Only 4 links will run concurrently.
+build foo.exe: link input.obj
+
+# A build statement can be exempted from it's rule's pool by setting an
+# empty pool
+build other.exe: link input.obj
+  pool =
+
+# A build statement can specify a pool even if its rule does not
+# Only one of these builds will run at a time.
+build heavy_object1.obj: cc heavy_obj1.cc
+  pool = heavy_object_pool
+build heavy_object2.obj: cc heavy_obj2.cc
+  pool = heavy_object_pool
+
+----------------
+
 
 Generating Ninja files from code
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~