Bug 1249990 - notes on man page for "docker build"
notes on man page for "docker build"
Product: Fedora
Classification: Fedora
Component: docker (Show other bugs)
Unspecified Unspecified
unspecified Severity low
: ---
: ---
Assigned To: Sally
Fedora Extras Quality Assurance
Depends On:
  Show dependency treegraph
Reported: 2015-08-04 06:10 EDT by Robert P. J. Day
Modified: 2016-02-16 15:04 EST (History)
10 users (show)

See Also:
Fixed In Version:
Doc Type: Bug Fix
Doc Text:
Story Points: ---
Clone Of:
Last Closed: 2016-02-16 15:04:07 EST
Type: Bug
Regression: ---
Mount Type: ---
Documentation: ---
Verified Versions:
Category: ---
oVirt Team: ---
RHEL 7.3 requirements from Atomic Host:
Cloudforms Team: ---

Attachments (Terms of Use)

  None (edit)
Description Robert P. J. Day 2015-08-04 06:10:31 EDT
(Side note: This man page needs some serious rewriting but let's start small.)

Under "--cpu-shares":

"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.
Comment 1 Daniel Walsh 2015-09-28 14:58:34 EDT
Sally any update on this?
Comment 2 Sally 2015-10-02 11:13:19 EDT
submitted https://github.com/docker/docker/pull/16722
Comment 3 Sally 2015-10-14 10:18:53 EDT
merged https://github.com/docker/docker/pull/16722
Comment 4 Daniel Walsh 2015-10-14 14:06:12 EDT
Fixed in docker-1.9

Note You need to log in before you can comment on or make changes to this bug.