Merge pull request #16722 from sallyom/man-docker-build-fix

add clarity in man/docker-build

man/docker-build.1.md

@@ -39,8 +39,9 @@ The Docker CLI reports "Sending build context to Docker daemon" when the context
 the daemon.
 
 When the URL to a tarball archive or to a single Dockerfile is given, no context is sent from
-the client to the Docker daemon. When a Git repository is set as the **URL**, the repository is
-cloned locally and then sent as the context.
+the client to the Docker daemon. In this case, the Dockerfile at the root of the archive and
+the rest of the archive will get used as the context of the build.  When a Git repository is
+set as the **URL**, the repository is cloned locally and then sent as the context.
 
 # OPTIONS
 **-f**, **--file**=*PATH/Dockerfile*
@@ -92,32 +93,50 @@ cloned locally and then sent as the context.
 **-c**, **--cpu-shares**=*0*
   CPU shares (relative weight).
 
-  By default, all containers get the same proportion of CPU cycles. You can
-  change this proportion by adjusting the container's CPU share weighting
-  relative to the weighting of all other running containers.
+  By default, all containers get the same proportion of CPU cycles.
+  CPU shares is a 'relative weight', relative to the default setting of 1024.
+  This default value is defined here: 
+  ```
+   cat /sys/fs/cgroup/cpu/cpu.shares
+   1024
+  ```
+  You can change this proportion by adjusting the container's CPU share 
+  weighting relative to the weighting of all other running containers.
 
-  To modify the proportion from the default of 1024, use the **-c** or
-  **--cpu-shares** flag to set the weighting to 2 or higher.
+  To modify the proportion from the default of 1024, use the **--cpu-shares**
+  flag to set the weighting to 2 or higher.
+
+      Container   CPU share    Flag             
+      {C0}        60% of CPU  --cpu-shares=614 (614 is 60% of 1024)
+      {C1}        40% of CPU  --cpu-shares=410 (410 is 40% of 1024)
 
   The proportion is only applied when CPU-intensive processes are running.
   When tasks in one container are idle, the other containers can use the
   left-over CPU time. The actual amount of CPU time used varies depending on
   the number of containers running on the system.
 
-  For example, consider three containers, one has a cpu-share of 1024 and
-  two others have a cpu-share setting of 512. When processes in all three
+  For example, consider three containers, where one has **--cpu-shares=1024** and
+  two others have **--cpu-shares=512**. When processes in all three
   containers attempt to use 100% of CPU, the first container would receive
-  50% of the total CPU time. If you add a fourth container with a cpu-share
-  of 1024, the first container only gets 33% of the CPU. The remaining containers
+  50% of the total CPU time. If you add a fourth container with **--cpu-shares=1024**,
+  the first container only gets 33% of the CPU. The remaining containers
   receive 16.5%, 16.5% and 33% of the CPU.
 
+
+      Container   CPU share   Flag                CPU time            
+      {C0}        100%        --cpu-shares=1024   33%
+      {C1}        50%         --cpu-shares=512    16.5%
+      {C2}        50%         --cpu-shares=512    16.5%
+      {C4}        100%        --cpu-shares=1024   33%
+
+
   On a multi-core system, the shares of CPU time are distributed across the CPU
   cores. Even if a container is limited to less than 100% of CPU time, it can
   use 100% of each individual CPU core.
 
   For example, consider a system with more than three cores. If you start one
-  container **{C0}** with **-c=512** running one process, and another container
-  **{C1}** with **-c=1024** running two processes, this can result in the following
+  container **{C0}** with **--cpu-shares=512** running one process, and another container
+  **{C1}** with **--cpu-shares=1024** running two processes, this can result in the following
   division of CPU shares:
 
       PID    container    CPU    CPU share
@@ -141,7 +160,7 @@ kernel to restrict the container's CPU usage to the quota you specify.
   CPUs in which to allow execution (0-3, 0,1).
 
 **--cpuset-mems**=*CPUSET-MEMS*
-  Memory nodes (MEMs) in which to allow execution (-1-3, 0,1). Only effective on
+  Memory nodes (MEMs) in which to allow execution (0-3, 0,1). Only effective on
   NUMA systems.
 
   For example, if you have four memory nodes on your system (0-3), use `--cpuset-mems=0,1`
@@ -203,16 +222,16 @@ name, and tag (where the tag in this context means the qualifier after
 the ":"). In this example we build a JBoss image for the Fedora repository 
 and give it the version 1.0:
 
-    docker build -t fedora/jboss:1.0
+    docker build -t fedora/jboss:1.0 .
 
 The next example is for the "whenry" user repository and uses Fedora and
 JBoss and gives it the version 2.1 :
 
-    docker build -t whenry/fedora-jboss:v2.1
+    docker build -t whenry/fedora-jboss:v2.1 .
 
 If you do not provide a version tag then Docker will assign `latest`:
 
-    docker build -t whenry/fedora-jboss
+    docker build -t whenry/fedora-jboss .
 
 When you list the images, the image above will have the tag `latest`.
 
@@ -228,16 +247,17 @@ as context. The Dockerfile at the root of the repository is used as
 Dockerfile. This only works if the GitHub repository is a dedicated
 repository.
 
-    docker build github.com/scollier/Fedora-Dockerfiles/tree/master/apache
+    docker build github.com/scollier/purpletest
 
 Note: You can set an arbitrary Git repository via the `git://` schema.
 
 ## Building an image using a URL to a tarball'ed context
 
 This will send the URL itself to the Docker daemon. The daemon will fetch the
-tarball archive, decompress it and use its contents as the build context. If you
-pass an *-f PATH/Dockerfile* option as well, the system will look for that file
-inside the contents of the tarball.
+tarball archive, decompress it and use its contents as the build context.  The 
+Dockerfile at the root of the archive and the rest of the archive will get used
+as the context of the build. If you pass an **-f PATH/Dockerfile** option as well,
+the system will look for that file inside the contents of the tarball.
 
     docker build -f dev/Dockerfile https://10.10.10.1/docker/context.tar.gz