Commits on Jan 4, 2017

1. config: Adjust process.env to immediately punt to POSIX …

   The uppercase letter / digit / underscore restriction is just for
   "variables used by the utilities in the Shell and Utilities volume of
   IEEE Std 1003.1-2001".
   
   Copying over some POSIX wording and then linking to POSIX didn't seem
   like much gain.  Just point people at POSIX and let them read about
   the name=value definition, charset suggestions, etc. there.
   
   Also link specifically to chapter 8 section 1 (instead of just chapter
   8).
   
   Rob Dolin had suggested "platform-appropriate" wording [1], but it
   seems like Visual Studio 2015 supports an environment-variable array
   with the same semantics [2], and providing an explicit
   "platform-appropriate" wiggle seems like it's adding useless
   complication.
   
   [1]: http://ircbot.wl.linuxfoundation.org/meetings/opencontainers/2016/opencontainers.2016-05-18-17.01.log.html#l-54
   [2]: https://msdn.microsoft.com/en-us/library/431x4c1w.aspx
   
   Signed-off-by: W. Trevor King <wking@tremily.us>

   

   wking committed Jan 4, 2017
   Configuration menu

   • View commit details
   • Copy full SHA for ca2fda1
   • Browse repository at this point

   Copy the full SHA

   ca2fda1 View commit details

   Browse the repository at this point in the history

2. config: Adjust process.args to cite POSIX's execvp …

   This punts the awkward-to-enforce "MUST be available at the given path
   inside of the rootfs" to the kernel, which will do a much better job
   of enforcing that constraint than runtime code or a static validator.
   
   It also punts most of the semantics to POSIX, which does a better job
   than we'll do at specifying this.  The extension is necessary because
   POSIX allows argv to be empty.  In the DESCRIPTION:
   
     The argument arg0 should point to a filename that is associated with
     the process being started by one of the exec functions.
   
   And in RATIONALE:
   
     Early proposals required that the value of argc passed to main() be
     "one or greater".  This was driven by the same requirement in drafts
     of the ISO C standard.  In fact, historical implementations have
     passed a value of zero when no arguments are supplied to the caller
     of the exec functions.  This requirement was removed from the ISO C
     standard and subsequently removed from this volume of IEEE Std
     1003.1-2001 as well.  The wording, in particular the use of the word
     should, requires a Strictly Conforming POSIX Application to pass at
     least one argument to the exec function, thus guaranteeing that argc
     be one or greater when invoked by such an application.  In fact,
     this is good practice, since many existing applications reference
     argv[0] without first checking the value of argc.
   
   But with an empty 'args' we will have no process to call (since
   process lacks an explicit 'file' analog).
   
   I chose the 2001/2004 POSIX spec for consistency with the existing
   reference (which landed in 7ac41c6, config.md: reformat into a
   standard style, 2015-06-30, which did not motivate it's use of an
   older standard).  For 2001 vs. 2004, [1] has:
   
     Abstract: The 2004 edition incorporates Technical Corrigendum Number
     1 and Technical Corrigendum 2 addressing problems discovered since
     the approval of the 2001 edition. These are mainly due to resolving
     integration issues raised by the merger of the Base documents.
   
   and the text in the linked pages uses "IEEE Std 1003.1-2001" for
   internal linking.
   
   Rob Dolin had suggested "platform-appropriate" wording [2], but it
   seems like Visual Studio 2015 supports execvp [3], and providing an
   explicit "platform-appropriate" wiggle seems like it's adding useless
   complication.
   
   [1]: http://pubs.opengroup.org/onlinepubs/009695399/mindex.html
   [2]: http://ircbot.wl.linuxfoundation.org/meetings/opencontainers/2016/opencontainers.2016-05-18-17.01.log.html#l-54
   [3]: https://msdn.microsoft.com/en-us/library/3xw6zy53.aspx
   
   Signed-off-by: W. Trevor King <wking@tremily.us>

   

   wking committed Jan 4, 2017
   Configuration menu

   • View commit details
   • Copy full SHA for 70858bc
   • Browse repository at this point

   Copy the full SHA

   70858bc View commit details

   Browse the repository at this point in the history

3. config: Explicitly list 'hooks' as optional …

   And make it omitempty, otherwise:
   
     $ ocitools generate --template <(echo '{}')
     $ cat config.json | jq -S .
     {
       "hooks": {},
       ...
     }
   
   To provide space for the type information and 'optional', I've
   shuffled the hook docs to follow our usual:
   
     * **`{property}`** ({type}, {when-needed}) {notes}
   
   format.  I've kept the separate event-trigger sections (e.g. "###
   Prestart") since they go into more detail on the timing, purpose, and
   exit handling for the different events (and that seemed like too much
   information to put into the nested lists).
   
   I've replaced the Go reference from 48049d2 (Clarify the semantics of
   hook elements, 2015-11-25, opencontainers#255) with POSIX references (following the
   new process docs) to address pushback against referencing Go [1,2] in
   favor of POSIX links [3].  Rob Dolin had suggested
   "platform-appropriate" wording [4], but it seems like Visual Studio
   2015 supports execv [5], and providing an explicit
   "platform-appropriate" wiggle seems like it's adding useless
   complication.
   
   [1]: opencontainers#427 (comment)
   [2]: http://ircbot.wl.linuxfoundation.org/meetings/opencontainers/2016/opencontainers.2016-05-18-17.01.log.html#l-46
   [3]: http://ircbot.wl.linuxfoundation.org/meetings/opencontainers/2016/opencontainers.2016-05-18-17.01.log.html#l-52
   [4]: http://ircbot.wl.linuxfoundation.org/meetings/opencontainers/2016/opencontainers.2016-05-18-17.01.log.html#l-54
   [5]: https://msdn.microsoft.com/en-us/library/886kc0as.aspx
   
   Signed-off-by: W. Trevor King <wking@tremily.us>

   

   wking committed Jan 4, 2017
   Configuration menu

   • View commit details
   • Copy full SHA for a78f255
   • Browse repository at this point

   Copy the full SHA

   a78f255 View commit details

   Browse the repository at this point in the history