default: update doc

README.rst

@@ -7,96 +7,47 @@
 Default
 -------
 
-The default recipe can be used to execute ad-hoc Python code at both
-init & install phases.
+The default recipe can be used to execute ad-hoc Python code at
+init/install/update phases. `install` must create the path pointed to by
+`location` (default is ${buildout:parts-directory}/${:_buildout_section_name_})
+and any other file system change is not tracked by buildout. `install` defaults
+to `update`, in which case `location` is ignored.
 
-Example buildout that builds software::
+Example that installs software::
 
   [buildout]
   parts =
     script
 
   [script]
-  # default way with using script
   recipe = slapos.recipe.build
-  url_0 = http://host/path/file.tar.gz
-  md5sum = 9631070eac74f92a812d4785a84d1b4e
-  script =
-    import os
-    os.chdir(%(work_directory)s)
-    unpack(%(url_0), strip_path=True)
-    execute('make')
-    execute('make install DEST=%(location)s')
   slapos_promise =
-    directory:bin
-    dynlib:bin/file linked:libz.so.1,libc.so.6,libmagic.so.1 rpath:${zlib:location}/lib,!/lib
     directory:include
-    file:include/magic.h
-    directory:lib
-    statlib:lib/libmagic.a
-    statlib:lib/libmagic.la
-    dynlib:lib/libmagic.so linked:libz.so.1,libc.so.6 rpath:${zlib:location}/lib
-    dynlib:lib/libmagic.so.1 linked:libz.so.1,libc.so.6 rpath:${zlib:location}/lib
-    dynlib:lib/libmagic.so.1.0.0 linked:libz.so.1,libc.so.6 rpath:${zlib:location}/lib
-    directory:share
-    directory:share/man
-    directory:share/man/man1
-    file:share/man/man1/file.1
-    directory:share/man/man3
-    file:share/man/man3/libmagic.3
-    directory:share/man/man4
-    file:share/man/man4/magic.4
-    directory:share/man/man5
-    directory:share/misc
-    file:share/misc/magic.mgc
-
-  [multiarchitecture]
-  recipe = slapos.recipe.build
-  slapos_promise =
-    ...
+    file:share/man/man1/foo.1
+    statlib:lib/libfoo.a
+    statlib:lib/libfoo.la
+    dynlib:bin/foo linked:libbar.so.1,libc.so.6,libfoo.so.1 rpath:${bar:location}/lib,!/lib
   x86 = http://host/path/x86.zip [md5sum]
   x86-64 =  http://host/path/x64.zip [md5sum]
-  script =
-    if not self.options.get('url'): self.options['url'], self.options['md5sum'] = self.options[guessPlatform()].split(' ')
-    extract_dir = self.extract(self.download(self.options['url'], self.options.get('md5sum')))
-    workdir = guessworkdir(extract_dir)
-    self.copyTree(workdir, "%(location)s")
-
-You can remove formatting by using option “format = no” (default is “yes”)
-
-For example::
-
-  [escaping]
-  recipe = slapos.recipe.build
-  example = foobar's one
-  script =
-    print('%%s' %% self.options['example'])
-    # will print “foobar's one”
-
-  [no-escaping]
-  recipe = slapos.recipe.build
-  example = foobar's one
-  foo = bar
-  format = no
-  script =
-    print('%s' % self.options['example'])
-    # will print “foobar's one”
-    print('%(foo)s')
-    # will print “%(foo)s”
+  install =
+    url, md5sum = options[guessPlatform()].split()
+    extract_dir = self.extract(self.download(url, md5sum))
+    self.copyTree(guessworkdir(extract_dir), location)
+    ${:update}
+  update =
+    ...
 
 Using the init option::
 
   [section-one]
   recipe = slapos.recipe.build
   init =
-    import os
-    options['foo'] = os.uname()[4]
+    import platform
+    options['foo'] = platform.uname()[4]
 
   [section-two]
   bar = ${section-one:foo}
 
-It is also possible to use both `init` & `script` in the same section.
-
 Pure download
 ~~~~~~~~~~~~~