========
template
========

Lets create a minimal `buildout.cfg` file::

  >>> write('buildout.cfg',
  ... '''
  ... [buildout]
  ... parts = template
  ... offline = true
  ...
  ... [template]
  ... recipe = p01.recipe.setup:template
  ... source = template.in
  ... target = template
  ... ''')

We create a template file::

  >>> write('template.in',
  ... '''#!/bin/bash
  ... My template knows about buildout path:
  ... ${buildout:directory}
  ... ''')

Now we can run buildout::

  >>> print(system(join('bin', 'buildout')))
  Installing template.
  template: Change mode ... for template

The template was indeed created:

  >>> cat('template')
  #!/bin/bash
  My template knows about buildout path:
  /sample-buildout

The variable ``buildout:directory`` was also substituted by a path.


content
-------

For very short script it can make sense to put the source directly into
`buildout.cfg`. If you do this, yo must use the content attribute instead of
the source attr::

  >>> write('buildout.cfg',
  ... '''
  ... [buildout]
  ... parts = template
  ... offline = true
  ...
  ... [foo]
  ... bar = bar from foo and more
  ...
  ... [template]
  ... recipe = p01.recipe.setup:template
  ... content =
  ...    My template knows about buildout path:
  ...    ${buildout:directory}
  ...    and the sample value:
  ...    ${template:sample}
  ...    or other parts value:
  ...    ${foo:bar}
  ... target = ${buildout:parts-directory}/template
  ... sample = some sample text
  ... ''')

Now we can run buildout::

  >>> print(system(join('bin', 'buildout')))
  Uninstalling template.
  Installing template.
  template: Change mode 420 for /sample-buildout/parts/template

The template should have been created::

  >>> cat('parts', 'template')
  My template knows about buildout path:
  .../sample-buildout
  and the sample value:
  some sample text
  or other parts value:
  bar from foo and more

Normally the file mode gets copied from the template, but it can also be
specified manually, which especially makes sense in this case:

  >>> write('buildout.cfg',
  ... '''
  ... [buildout]
  ... parts = template
  ... offline = true
  ...
  ... [template]
  ... recipe = p01.recipe.setup:template
  ... content =#!/bin/bash
  ...    echo foo
  ... target = ${buildout:parts-directory}/template
  ... mode = 666
  ... ''')

Run buildout again ::

  >>> print(system(join('bin', 'buildout')))
  Uninstalling template.
  Installing template.
  template: Change mode ... for /sample-buildout/parts/template

The template should have the specified file mode::

  >>> from os import stat
  >>> from stat import S_IMODE
  >>> print('%o' % S_IMODE(stat('parts/template').st_mode))
  666


Creating a template in a variable path
--------------------------------------

Lets create a minimal `buildout.cfg` file. This time the target should
happen in a variable path::

  >>> write('buildout.cfg',
  ... '''
  ... [buildout]
  ... parts = template
  ... offline = true
  ...
  ... [template]
  ... recipe = p01.recipe.setup:template
  ... source = template.in
  ... target = ${buildout:parts-directory}/template
  ... ''')

Now we can run buildout::

  >>> print(system(join('bin', 'buildout')))
  Uninstalling template.
  Installing template.
  template: Change mode ... for /sample-buildout/parts/template

The template was indeed created::

  >>> cat('parts', 'template')
  #!/bin/bash
  My template knows about buildout path:
  /sample-buildout


Creating missing paths
----------------------

If an target file should be created in a path that does not yet exist,
then the missing items will be created for us::

  >>> write('buildout.cfg',
  ... '''
  ... [buildout]
  ... parts = template
  ... offline = true
  ...
  ... [template]
  ... recipe = p01.recipe.setup:template
  ... source = template.in
  ... target = ${buildout:parts-directory}/etc/template
  ... ''')

  >>> print(system(join('bin', 'buildout')))
  Uninstalling template.
  Installing template.
  template: Create path /sample-buildout/parts/etc
  template: Change mode ... for /sample-buildout/parts/etc/template

  >>> ls('parts')
  d etc
  - template

Also creation of several subdirectories is supported::


  >>> write('buildout.cfg',
  ... '''
  ... [buildout]
  ... parts = template
  ... offline = true
  ...
  ... [template]
  ... recipe = p01.recipe.setup:template
  ... source = template.in
  ... target = ${buildout:parts-directory}/foo/bar/template
  ... ''')

  >>> print(system(join('bin', 'buildout')))
  Uninstalling template.
  Installing template.
  Create path /sample-buildout/parts/foo
  template: Create path /sample-buildout/parts/foo/bar
  template: Change mode ... for /sample-buildout/parts/foo/bar/template

  >>> cat('parts', 'foo', 'bar', 'template')
  #!/bin/bash
  My template knows about buildout path:
  /sample-buildout

When changes happen to the target path, then the old path is removed
on uninstall. Therefore the ``etc/`` directory created above has
vanished now::

  >>> ls('parts')
  d foo
  - template
