Red Hat Bugzilla – Bug 1249990
notes on man page for "docker build"
Last modified: 2016-02-16 15:04:07 EST
(Side note: This man page needs some serious rewriting but let's start small.)
"For example, consider three containers, [where] one has a cpu-share of 1024"
^^^^^ add this word
Also, in that above sentence (and sentences further down), the phrase used is "cpu-share" (singular), while the actual option is "--cpu-shares" (plural). For consistency, either use the generic phrase "CPU share" (which is perfectly valid), or use the option name "cpu-shares" -- don't use this weird in-between reference of "cpu-share".
More to the point, that entire section explaining --cpu-shares seems confusing. One reads:
"To modify the proportion from the default of 1024 ..."
But what does a default value of 1024 *represent*? The reader is not told. Only reading further does it become obvious(?) that 1024 represents the maximum CPU share that can be allocated (if that's in fact what it means; I'm just assuming I'm reading this correctly.)
Now, given the example shown there, it would be useful to present a table as is done for the multi-core example even further down -- a table would be tremendously useful for clarifying what is happening (both for the initial three-container scenario, and for what happens after you add a fourth container).
Next, while "docker build --help" prints the following snippet:
--cpuset-cpus= CPUs in which to allow execution (0-3, 0,1)
--cpuset-mems= MEMs in which to allow execution (0-3, 0,1)
the man page reads:
CPUs in which to allow execution (0-3, 0,1).
Memory nodes (MEMs) in which to allow execution (-1-3, 0,1).
Only effective on NUMA systems. ^^^^ ???
What means "-1-3"? Is that deliberate, or a typo?
Finally (for now), under EXAMPLES, one reads:
"It is also a good practice to add the files required for the image to the sub-directory. These files will then be specified with the COPY or ADD instructions in the Dockerfile."
In what way is this just "good practice" as opposed to being *required*? How else will you have access to those files unless you add them to the context for this build? Or am I missing something here?
And I would reword that second sentence to be much more explicit as to what is going on:
"These files will then be selected for inclusion in the new image with the COPY or ADD instructions in the Dockerfile."
That's all for now.
Sally any update on this?
Fixed in docker-1.9