
.. ABOUT THIS DOC
.. It's a start for an upgrade guide to all the released versions
.. of Grok and grokproject.
..
.. It's work-in-progress
..

.. contents:: Detailed docs


Upgrading generated projects
============================

There have been a lot of changes between single releases of
`grokproject`. Here is how you can upgrade your local grok project, if
it was generated using an older version of `grokproject`.

.. note:: The version numbers mentioned herein mean the versions of
          `grokproject`, not `grok` versions, except if explicitly
          said so. `grokproject` versions are mainly independent from
          the `grok` version used.

Basics good to know
-------------------

We start with some basic procedures nice to know about before actually
doing the upgrade.

Which version of `grokproject` is currently installed?
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Newer versions of `grokproject` (since 1.0a2) support the
``--version`` option. Run::

  $ grokproject --version
  1.0a4

This is the version of ``grokproject`` that will be used when you
create a new project.

If your installed ``grokproject`` does not support the ``--version``
switch (you can also run ``grokproject --help`` to see what options
are available), then you can lookup the ``grokproject`` script
itself. It is a little Python script and the version number is written
down in the script itself::

  $ which grokproject
  /usr/bin/grokproject

  $ less /usr/bin/grokproject

will reveal what version of `grokproject` you have installed.

.. _upgradetolatest:

How can I upgrade to the latest ``grokproject`` version?
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Run::

  $ easy_install -U grokproject

This will fetch and install the latest version for you.

.. note:: You need appropriate permissions to do so, maybe root or
          Administrator privileges. Use virtualenv_ if this is a
          problem for you.

Upgrading the `grokproject` script will not upgrade your already
generated projects.

How can I bring the installed `grokproject` to a certain version?
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

If you want to bring ``grokproject`` for instance to version 1.0a2,
just run::

  $ easy_install grokproject==1.0a2

This will fetch and install `grokproject` version 1.0a2 for you. All
versions available can be found below.

.. note:: You need appropriate permissions to do so, maybe root or
          Administrator privileges. Use virtualenv_ if this is a
          problem for you.


.. _pingrokversion:

How can I 'pin down' a certain `grok` version with a project?
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Basically, you can run any `grok` version with any `grokproject`
version.

The common approach to pin a certain `grok` version down is to tell
`buildout` to use it. This can be done by setting the version in
`buildout.cfg`.

In the ``[buildout]`` section of your `buildout.cfg` add a line like
this::

  extends = http://grok.zope.org/releaseinfo/grok-1.0a1.cfg

which will read the mentioned file from the grok site and use it as a
`versions.cfg`. Browse http://grok.zope.org/releaseinfo/ to see what
version files are available.

Alternatively you can download this file and place it in your project
root overwriting the old `versions.cfg` file. Make sure, however, to
copy the packages pinned down by `grokproject` itself (near bottom of
your original `versions.cfg`) over to the new versions.cfg.


.. _whereistheconfig:

Where are the configuration files?
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Location of configuration files changed with different `grokproject`
versions.

* 1.0a4, 1.0a3:
    All configuration files are templates and can be found in
    ``etc/``.

* 1.0a2, 1.0a1:
    All configuration files are in ``etc/``

* 0.9, 0.8, 0.7, 0.6:
    deploy.ini, debug.ini:
      Do not exist.

    site.zcml:
      Inline in `buildout.cfg`

    zdaemon.conf, zope.conf:
      can be found in ``parts/zopectl/``

* 0.4 or older:
    deploy.ini, debug.ini:
      Do not exist.

    site.zcml:
      Inline in `buildout.cfg`

    zdaemon.conf, zope.conf:
      can be found in ``parts/instance/``


Which `grokproject` version was used for a **generated** project?
-----------------------------------------------------------------

If you have an already generated project you want to update, things
are more difficult and likely to require some manual work.

But before you can upgrade you have to know what version of
`grokproject` was used when the project was created.

Here is, how you can find out.

1.0a4
~~~~~

Your project was generated by `grokproject` 1.0a4 if...

* it contains a file ``etc/zope.conf.in`` *and*

* this file contains a line saying::

    site-definition ${site_zcml:output}

  on top.

1.0a3
~~~~~

Your project was generated by `grokproject` 1.0a3 if...

* it contains a script ``zpasswd`` in ``bin/`` *and*

* the ``versions.cfg`` contains also a line pinning ``grokui.admin``
  version.

1.0a2 or 1.0a1
~~~~~~~~~~~~~~

Your project was generated by `grokproject` 1.0a2 or 1.0a1 if...

* it does *not* contain a script ``zpasswd`` in ``bin/`` *and*

* it *does* contain a script ``paster`` in ``bin/``

The changes between 1.0a1 and 1.0a2 did not touch generated projects,
but only options of the `grokproject` script itself.

0.9
~~~

Your project was generated by `grokproject` 0.9 if...

* it does *not* contain a script ``paster`` in ``bin/`` *and*

* it does *not* contain a line with ``lovely.recipe`` in
  ``versions.cfg``.

0.8
~~~

Your project was generated by `grokproject` 0.8 if...

* it *does* contain a line with ``lovely.recipe`` in
  ``versions.cfg`` *and*

* it does contain a script ``bootstrap.py``.

0.7
~~~

Your project was generated by `grokproject` 0.7 if...

* it does *not* contain a script ``bootstrap.py`` *and*

* the ``buildout.cfg`` contains only one ``[data]`` section.

0.6
~~~

Your project was generated by `grokproject` 0.6 if...

* the ``buildout.cfg`` contains two ``[data]`` sections *and*

* it contains a script ``i18nextract`` in the ``bin/`` directory.

0.5.1
~~~~~

Your project was generated by `grokproject` 0.5.1 if...

* it does *not* contain a script ``i18nextract`` in the ``bin/``
  directory *and*

* it does *not* contain a section ``[zope3]`` in `buildout.cfg`.

0.5
~~~

Your project was generated by `grokproject` 0.5 if...

* it does contain a section ``[zope3]`` in `buildout.cfg` *and*

* it does contain a script ``zopectl`` in the ``bin/`` directory.

0.4 or older
~~~~~~~~~~~~

Your project was generated by `grokproject` 0.4 or older if...

* it contains a script ``instance`` in the ``bin/`` directory.


How can I upgrade a generated project from version X to version Y?
------------------------------------------------------------------

If you found out with which `grokproject` version your project was
created with, you can start the real upgrading.

The basic and fastest way to upgrade:

Say, we have an old project ``Cave`` which was generated by
``grokproject`` 1.0a1, we want to upgrade to 1.0a4, and the old project
resides in ``old/Cave/``.

1) Bring ``grokproject`` to the target version (`see above
   <#upgradetolatest>`_)::

     $ easy_install grokproject==1.0a4

2) With this ``grokproject`` create a new project (at a new location)
   with the *same name* as the one to upgrade. You might want to use the
   ``--grokversion`` option to use the same ``grok`` version as your
   old project::

     $ grokproject --grokversion=1.0a3 Cave

   Here we use ``grokproject`` 1.0a4 to create a project that uses
   ``grok`` 1.0a3. Yes, this can be confusing.

3) In your freshly created project remove the generated sources under
   ``src/<projname>/``, i.e. the complete ``<projname>`` folder::

     $ rm -rf Cave/src/cave

4) Copy the sources of src/<projname>, i.e. the ``<projname>`` folder
   from your old project over to the new project.

     $ cp -ar old/Cave/src/cave Cave/src

5) Rerun buildout in your new project::

     $ cd Cave
     $ bin/buildout

   Upgrade finished.

This procedere, however, might fail for certain version bumps, where
also the mean sources (under ``src/<projname>``) have to be changed. The
necessary additional changes are described below.

In our example, for instance, we have to remove the module
``startup.py`` from the sources.

Further problems can arise, if you manually changed the main
configuration files (i.e. in `etc/` or `parts/`, the ``buildout.cfg``
or ``setup.py``). In this case you have to redo your changes in the
new project.

If you use version control, take care of any VC stuff copied over like
hidden subversion directories.


Additional Upgrade Steps (fast lane)
------------------------------------

These steps have to be performed additionally to the above mentioned
procedure.


Pin the `grok` version used in your old project
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

The freshly generated grokproject will by default use the latest grok
version available. This might cause problems with the code of your old
project.

To use the `grok` version your old project used, lookup the `grok`
version your old project used at top of the `versions.cfg` file of
your old project and set this in your upgraded project as described
`above <#pingrokversion>`_.


Eventually remove `startup.py` from sources
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

If your sources (i.e. the package stored in `<src/myproject>` contain
a module `startup.py`, which was not changed since creation, you can
safely remove it.

This module was only generated for projects created with `grokproject`
versions 1.0a1/1.0a2.


Check parameters in configuration files
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Check the parameters set in the configuration files to match the
settings of your old project.

See `Where are the configuration files?`_ to find out where the configuration
files in your old project can be found.

In you new project they can be found as templates in the `etc/`
directory.


Manually upgrading (detailed)
-----------------------------

If you want to perform the single changes between ``grokproject``
releases manually, here is how to do this.


from 1.0a3 to 1.0a4
~~~~~~~~~~~~~~~~~~~

The fastest way might be to create a new project with the same name
with ``grokproject`` 1.0a4 and then replace the complete
``src/<projname>`` tree of your freshly generated stuff with the
contents of the ``src/<projectname>`` tree from your old project.

If you instead want to apply all changes manually, then in your old
project follow these steps:

* remove the line pinning ``grokui.admin`` near the end of
  ``versions.cfg``. 

* replace the line in section ``[handler_accesslog]`` in
  ``etc/debug.ini.in`` starting with ``args =`` with the following
  line::

    args = (os.path.join(r'${buildout:directory}', 'parts', 'log',
            'access.log'), 'a')

* do the same in file ``etc/deploy.ini.in``.

* in ``etc/zope.conf.in`` replace::

    site-definition ${buildout:directory}/etc/site.zcml

  with::

    site-definition ${site_zcml:output}

  and replace::

    path ${buildout:directory}/parts/data/Data.fs

  with::

    path ${data:path}

* in `buildout.cfg` you might add a line to the ``[buildout]`` section
  reading::

    find-links = http://download.zope.org/distribution/

  But read section `Using find-links`_ below.

Rerun ``buildout`` afterwards and you should be done.


from 1.0a2 to 1.0a3
~~~~~~~~~~~~~~~~~~~

* in ``buildout.cfg`` change the ``parts`` line near top from::

     parts = eggbasket app i18n test data log

  to::

     parts = eggbasket app i18n test data log zpasswd
             zope_conf site_zcml zdaemon_conf deploy_ini debug_ini

* in ``buildout.cfg`` add the following sections::

     # This section is named so that the zpasswd utility is
     # called `zpasswd`
     [zpasswd]
     recipe = z3c.recipe.dev:script
     eggs = <projname>
     module = zope.app.server.zpasswd
     method = main
     
     [zope_conf]
     recipe = z3c.recipe.template
     input = etc/zope.conf.in
     output = ${buildout:parts-directory}/etc/zope.conf
     
     [site_zcml]
     recipe = z3c.recipe.template
     input = etc/site.zcml.in
     output = ${buildout:parts-directory}/etc/site.zcml
     
     [zdaemon_conf]
     recipe = z3c.recipe.template
     input = etc/zdaemon.conf.in
     output = ${buildout:parts-directory}/etc/zdaemon.conf
     
     [deploy_ini]
     recipe = z3c.recipe.template
     input = etc/deploy.ini.in
     output = ${buildout:parts-directory}/etc/deploy.ini
     
     [debug_ini]
     recipe = z3c.recipe.template
     input = etc/debug.ini.in
     output = ${buildout:parts-directory}/etc/debug.ini

  and make sure to replace ``<projname>`` in the ``[zpasswd]`` section
  with the egg name of your project (for instance ``sample`` if your
  project was named ``Sample``).

* in ``setup.py``:

  * add ``grokcore.startup`` to the required dependencies.

  * in the entry-point definitions section (near end) replace::

      [console_scripts]
      <projname>-debug = <projname>.startup:interactive_debug_prompt
      <projname>-ctl = <projname>.startup:zdaemon_controller
      [paste.app_factory]
      main = <projname>.startup:application_factory

    with::

      [console_scripts]
      <projname>-debug = grokcore.startup:interactive_debug_prompt
      <projname>-ctl = grokcore.startup:zdaemon_controller
      [paste.app_factory]
      main = grokcore.startup:application_factory

    and of course fill in your real projects eggname (lowercase
    projectname) instead of ``<projname>``.

* in ``versions.cfg`` near bottom, where all `grokproject` specific
  versions are pinned, replace::

    # Here we pin the recipes used in the buildout.cfg
    z3c.recipe.i18n = 0.5.0
    z3c.recipe.eggbasket = 0.4.0
    zc.buildout = 1.0.6
    zc.recipe.egg = 1.1.0b1
    zc.recipe.filestorage = 1.0.1
    zc.recipe.testrunner = 1.0.0
    zc.zodbrecipes = 0.4.0
    zc.zope3recipes = 0.7.0

  with::

    # Here we pin the recipes and other packages that are not in the
    # downloaded versions.cfg of grok
    Paste = 1.7.2
    PasteDeploy = 1.3.2
    PasteScript = 1.7.3
    setuptools = 0.6c9
    z3c.evalexception = 2.0
    z3c.recipe.eggbasket = 0.4.1
    z3c.recipe.i18n = 0.5.0
    z3c.recipe.template = 0.1
    zc.buildout = 1.1.1
    zc.recipe.egg = 1.1.0
    zc.recipe.filestorage = 1.0.1
    grokcore.startup = 0.2



Upgrading already created projects
----------------------------------

`grokproject` received a lot of changes during releases. This also
touched the structure of generated projects. For example there was
support for paster_ introduced and the generation of configuration
files changed heavily.

Here we will explain, what changes were done (and why) and how you can
apply those changes to your existing projects.


Paster and `startup.py`
~~~~~~~~~~~~~~~~~~~~~~~

With `grokproject` 1.0a1 we introduced paster_ support. This means,
that the whole grok application is now by default served as a WSGI_
application served by paster_.

If your project has no `paster` script in ``bin/`` then you still lack
paster support.

To make paster support available in an existing project, follow these
steps:

1) Define entry points for paster, the ZDaemon controller and the debug
   prompt.

  In the `setup.py` of your project replace the (empty) entry points
  definition (near end of file) by something like this::

      entry_points = """
      [paste.app_factory]
      main = grokcore.startup:application_factory
      """,

  If you also want `ZDaemon` controlled starter scripts
  (`bin/mypkg-ctl`, `bin/mypkg-debug`) add also the following entry
  points for console scripts (they are not needed to run plain
  paster) and read `Adding ZDaemon control scripts`_::

      entry_points = """
      [console_scripts]
      <proj_mod_name>-debug = grokcore.startup:interactive_debug_prompt
      <proj_mod_name>-ctl = grokcore.startup:zdaemon_controller
      [paste.app_factory]
      main = grokcore.startup:application_factory
      """,

  Please use the upper *or* the latter snippet, not both.

  Make sure to replace ``<proj_mod_name>`` with the module name of
  your project. This name equals to the directory name of the
  directory holding your sources in ``src/``. So if you have a
  directory ``src/myproj`` then the name will be ``myproj``. Normally
  this is the lowercase version of your project name. Please note that
  this name is case-sensitive.

  The entry points we defined here can be used by certain buildout
  recipes to generate scripts automatically. Note, that the
  ``[console_scripts]`` are not necessary for paster but buildout to
  create simple wrapper scripts for starting our application.

  The entry points above determine, where other components (like
  paster) can find certain python modules. For example we tell, that
  there is a paster-compatible application factory available named
  ``application_factory`` and placed in the ``grokcore.startup``
  module. This module, of course, must be available during startup.

  Let's care for this now.

2) Require `grokcore.startup`.

  Add an entry ``'grokcore.startup'`` to the list of
  ``install_requires`` in your project's `setup.py`.

  If you want your own/special WSGI configuration, then you can do so
  and skip this step (see below for further details).

3) Pin down versions of extra packages (optional).

  To use paster we need some extra packages. The versions of those
  packages can be pinned down in file ``versions.cfg`` or in a special
  ``[versions]`` section of your `buildout.cfg`.

  Add::

    Paste = 1.7.2
    PasteDeploy = 1.3.2
    PasteScript = 1.7.3
    z3c.evalexception = 2.0
    grokcore.startup = 0.2

  The version numbers pinned here are the ones used by latest
  `grokproject` as time of writing (1.0a4). When you read this newer
  versions might be in use.

  You can remove (because we will not use it anymore)::

    zc.zodbrecipes = 0.4.0
    zc.zope3recipes = 0.7.0

4) Create a separate `site.zcml` file.

  When we use paster we also have to provide a separate `site.zcml`
  file, as we have to refer to it in our paster configurations.

5) Modify `buildout.cfg` to make the changes active.

  Right now our modified project is likely to be broken. We have to
  tell buildout that we like to have a paster-powered application.

  * Remove ``zopectl`` from the ``parts`` in `buildout.cfg` (near
    top).

    Also remove the complete ``[zopectl]`` section from `buildout.cfg`
    as we do not use it anymore (optional).

  * In the ``[app]`` section of `buildout.cfg` copy the definition of
    ``site.zcml`` (the one which consists of many lines) to a separate
    file. We might need this later on.

  * Replace the whole ``[app]`` section with the following::

      [app]
      recipe = zc.recipe.egg
      eggs = <proj_egg_name>
             z3c.evalexception>=2.0
             Paste
             PasteScript
             PasteDeploy
      interpreter = python-console

    where instead ``<proj_egg_name>`` you should insert the name of
    your project egg (as defined near top of `setup.py`). It is
    normally the project name.

  * Add a ``[log]`` section.

    Add `log` to the list of parts near the beginning of
    `buildout.cfg`.

    Add the following somewhere in `buildout.cfg`::

      [log]
      recipe = zc.recipe.filestorage

    This will generate a directory ``log/`` in the ``parts/``
    directory of your project.

6) Configuration files: templated or manually

  From here we can go two distinct ways: we can generate the still
  missing configuration files manually or go a quicker way by letting
  buildout do it for us using templates.

  If you prefer the latter, read on in section Setting up
  configuration from templates below. This is also the recommended
  approach as using templates for configuration you get configurations
  usable in a version controlled environment (SVN or so) without
  hardcoded paths.

  Otherwise, or if you like to dig deeper into the details of
  configuration, read on here.

7) Create a `deploy.ini`

  If we now rerun `bin/buildout`, there should be generated an
  executable script `bin/paster`.

  This, however, is not enough as we still need the configuration
  files for our application to be served. We must tell paster where to
  find the WSGI application and how it should be configured.

  This is normally done in a file called `deploy.ini` or similar and
  it can be very short::

    # deploy.ini
    [app:main]
    use = egg:<proj_egg_name>

    [server:main]
    use = egg:Paste#http
    host = 127.0.0.1
    port = 8080

    [DEFAULT]
    # set the name of the zope.conf file
    zope_conf = %(here)s/zope.conf

  Again, replace ``<proj_egg_name>`` with the egg name of your
  project.

  This file can be placed where ever you like. Latest grokprojects
  generate the file automatically from templates placed in ``etc/``
  and write the generated file to ``parts/etc/deploy.ini``.


8) Generate a `zope.conf`

  As we can see in the `deploy.ini` above there is a reference to
  another configuration file `zope.conf`. This is needed by the
  application factory to configure the grok application we want to
  serve.

  Let's create a simple one::

    # zope.conf
    # Identify the component configuration used to define the site:
    site-definition <project_path>/parts/etc/site.zcml

    <zodb>
      # Standard Filestorage
      <filestorage>
        path <proj_path>/parts/data/Data.fs
      </filestorage>
    </zodb>

    <eventlog>
      # This sets up logging to a file.
      # The "path" setting can be a relative or absolute
      # filesystem path.
      <logfile>
        path <proj_path>/parts/log/z3.log
        formatter zope.exceptions.log.Formatter
      </logfile>
    </eventlog>

    # Comment this line to disable developer mode.  This should be done in
    # production
    devmode on

  Of course, here we have to replace all ocurrences of ``<proj_path>``
  with the absolute path to our project directory.

  This file (`zope.conf`) has to be placed in the same directory as
  `deploy.ini`.

  Note, that the hardcoded absolute paths in here make it difficult to
  use this configuration in a shared or version controlled development
  environment. You can use templates (see below) to circumvent this.

9) Create a `site.zcml`

  The `zope.conf` contains a reference to a file called `site.zcml`,
  where the configuration of the component architechture is stored
  in. This file is also needed on startup, so we create a simple
  `site.zcml`::

    <configure xmlns="http://namespaces.zope.org/zope"
               i18n_domain="MYPKG">

      <include package="MYPKG" />
        <configure i18n_domain="MYPKG">
          <unauthenticatedPrincipal id="zope.anybody"
                                    title="Unauthenticated User" />
          <unauthenticatedGroup id="zope.Anybody"
                                title="Unauthenticated Users" />
          <authenticatedGroup id="zope.Authenticated"
                              title="Authenticated Users" />
          <everybodyGroup id="zope.Everybody"
                          title="All Users" />
          <principal id="zope.manager"
                     title="Manager"
                     login="grok"
                     password_manager="SHA1"
                     password="e3756f86739bd029629243732eb682db005a7541f7509622"
          />
          <!-- Replace the following directive if you do not want
               public access -->
          <grant permission="zope.View"
                 principal="zope.Anybody" />
          <grant permission="zope.app.dublincore.view"
                 principal="zope.Anybody" />

          <role id="zope.Manager" title="Site Manager" />
          <role id="zope.Member" title="Site Member" />
          <grantAll role="zope.Manager" />
          <grant role="zope.Manager"
                 principal="zope.manager" />
       </configure>
    </configure>

  Please replace ``MYPKG`` with the name of your toplevel source
  package, which is normally the lowercase projectname. In other
  words: if your project contains a directory ``src/mypackage/`` then
  replace ``MYPKG`` with ``mypackage`` in the above template.

  The SHA1-hashed password above is ``grok`` in plain text (see also
  "`Adding zpasswd script`_" below).

  Put this file (`site.zcml`) at the location given in `zope.conf`
  above.

  Now you should be able to start paster. Try::

    $ bin/paster serve deploy.ini

  and if everything works okay, you should be able to browse
  ``http://localhost:8080/``. The username/password with the
  `site.zcml` configuration given above is ``grok`` and ``grok``.

If you now also want ZDaemon controlled starter scripts (see step 1),
read on below at `Adding ZDaemon control scripts`_.

Defining your own WSGI configuration
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

.. _conftemplates:

Configuration templates
-----------------------

With `grokproject` 1.0a3 we introduced generation of all main
configuration files (`deploy.ini`, `debug.ini`, `zope.conf`,
`site.zcml`, `zdeamon.conf`) via template files.

The template files are by default put in the `etc/` directory of a
freshly generated project and have the ``.in`` filename
extension. They are read by a special recipe used by `buildout` and
generate the real configuration files in the `parts/etc/` directory of
your project when you run `buildout`. See
`collective.recipe.template`_ for deeper insights.

With the configuration templates enabled, `buildout` reads the
configuration templates pointed to in `buildout.cfg`, expands any
variables therein and writes the result to the real configuration
files in `parts/etc/`.

Using templates has a lot of advantages over manually writing
configuration files. Most notably you can avoid hardcoded paths, so
that the same configuration will work also on computers of other
developers/users without changes.

To make all this happen, you need the configuration file templates
normally generated by `grokproject` and some new entries in
`buildout.cfg`.

We modify `buildout.cfg` so that the configuration files are looked up
in the `etc/` subdirectory of our project. For each configuration file
we give the template file and the location, where the resulting file
should be created.

Add the following sections to `buildout.cfg`::

  [zope_conf]
  recipe = collective.recipe.template
  input = etc/zope.conf.in
  output = ${buildout:parts-directory}/etc/zope.conf

  [site_zcml]
  recipe = collective.recipe.template
  input = etc/site.zcml.in
  output = ${buildout:parts-directory}/etc/site.zcml

  [zdaemon_conf]
  recipe = collective.recipe.template
  input = etc/zdaemon.conf.in
  output = ${buildout:parts-directory}/etc/zdaemon.conf

  [deploy_ini]
  recipe = collective.recipe.template
  input = etc/deploy.ini.in
  output = ${buildout:parts-directory}/etc/deploy.ini

  [debug_ini]
  recipe = collective.recipe.template
  input = etc/debug.ini.in
  output = ${buildout:parts-directory}/etc/debug.ini

Each of these section names (``zope_conf``, ``site_zcml``, etc.) must
also added to the list of ``parts`` near top of `buildout.cfg`, so
that is might read similar to this::

  parts = eggbasket app i18n test data log zpasswd
          zope_conf site_zcml zdaemon_conf deploy_ini debug_ini

Now all we need to make this work are the configuration file templates
placed in an `etc/` subdirectory.

Generating configuration templates using `grokproject`
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

If the configuration files of your old project were not modified too
heavily, you can easily generate all configuration files like this:

1) Upgrade `grokproject` to the latest release (see above)::

     $ easy_install -U grokproject

2) Create a Grok project with the same projectname as the project you
   want to upgrade::

     $ grokproject Cave

   Afterwards you have the complete bunch of configuration templates
   in the `etc/` directory of your project.

3) Copy the complete `etc/` directory of you freshly generated project
   over to the old project:

     $ cp -r Cave/etc old_proj/Cave/

You might want to check, whether the settings in the configuration
files (ports, passwords, etc.) meet your old project's settings.

The configuration files hide in older projects somewhere in the
`parts/` directory of your project.

Please note that any terms like ``${buildout:directory}`` in template
files are expanded when running buildout. Do not overwrite them with
static absolute paths from your old configuration file unless you know
what you are doing.

If you rerun `buildout` afterwards, the new configuration files should
be written to `parts/etc/` in your project.

If you want to change the configuration files (not the templates),
consider modifying the templates instead as on the next run of
`buildout` your direct changes to files in `parts/` are likely to
vanish while changes to the templates will go to the configuration
files generated there.


.. _findlinks:

Using ``find-links``
--------------------

Some versions of `grokproject` generated an additional line in
`buildout.cfg` saying::

    find-links = http://download.zope.org/distribution/

This line tells buildout to look for eggs not only in the standard
Python PyPI (=Python Package Index, located at
http://pypi.python.org/ ) but also in other locations like the Zope
package index.

The Zope PyPI was planned in the beginning as a pure mirror of the
canonical Python PyPI, but was soon filled also with eggs not
available at the standard PyPI. This means, that you still cannot get
certain eggs from PyPI which are still hosted at the Zope site only.

Furthermore the Zope PyPI was planned to serve as a fallback in case
of outages of the central PyPI site and it should deliver eggs faster.

Usage of ``find-links`` is quite common in the Zope2 and Plone world
but it is meanwhile deprecated in the Zope 3 (aka ZTK, Zope Toolkit)
world.

As developers wanted to concentrate on a single repository shared with
the whole Python community, all egg authors should now host their
packages on http://pypi.python.org/ only.

To enforce this usage pattern, people are strongly encouraged *not* to
use the above `find-links` statement any more.

Unfortunately, there is still a little number of eggs available from
the Zope package index only, which also includes some eggs some
`megrok` packages depend on. If you want this `megrok` packages to
work (namely `megrok.form`), you have to lookup the Zope package index
or in other words: you have to use the above `find-links` statement.

As a rule of thumb you should try to cope without it. If, however, you
get some errors during running `buildout` telling that some packages
cannot be found, add the `find-links` statement.


.. _zdaemon:

Adding ZDaemon control scripts
------------------------------

To start a daemon that serves your grok application, all versions of
`grokproject` generate a suitable script in the `bin/` directory.

Recent versions of `grokproject` generate scripts in the `bin/`
directory called `<proj-name>-ctl` and `<proj-name>-debug` where
``<proj-name>`` is the lowercase project name.

These scripts can be used like the well-known init-scripts on Unix
systems. I.e. you can say something like::

  $ ./bin/myproj-ctl start|stop|restart|fg|--help

This is functionality actually provided by the `ZDaemon` software,
also a part of the Zope software.

In oldest versions, this script was called ``instance``.

With introducing paster, the way of generating those scripts
changed. So you have to care for this if upgrading.





.. _zpasswd:

Adding ``zpasswd`` script
-------------------------

You can add a ``zpasswd`` script (if you still lack one) by modifying
the `buildout.cfg` in your project.

1) Add ``zpasswd`` to the list of parts near top of the file.

2) Add the following ``zpasswd`` section somewhere in `buildout.cfg`,
   maybe at the end::

     # This section is named so that the zpasswd utility is
     # called `zpasswd`
     [zpasswd]
     recipe = z3c.recipe.dev:script
     eggs = <proj_egg_name>
     module = zope.app.server.zpasswd
     method = main

   Make sure to replace ``<proj_egg_name>`` by the name of your
   project egg as set it ``setup.py`` (normally the project name).

Rerun `bin/buildout` and the script should be generated.

.. _collective.recipe.template: 
         http://pypi.python.org/pypi/collective.recipe.template

.. _paster: http://pypi.python.org/pypi/Paste

.. _virtualenv: http://pypi.python.org/pypi/virtualenv

.. _WSGI: http://www.wsgi.org/wsgi/
