What's the buildout:zcml option for?

Question

In one of my projects' buildout.cfg files I have something like this:

[buildout]
...
zcml =
    my.package
    plone.reload
...

Everything works fine but I'm still puzzled about what's the reason some packages do need to be listed here and why others don't.

What's the purpose of it to begin with?

While doing some research I end up on https://pypi.python.org/pypi/munin.zope/2.1 which says that if you use z3c.autoinclude and plone (+3.3) you don't need it.

Does that mean that if a distribution has the z3c.autoinclude slug on its setup.py, i.e.

entry_points="""
# -*- Entry points: -*-
[z3c.autoinclude.plugin]
target = plone
""",

you don't have to care about buildout:zcml?

Answer 1

There is no inherent functionality related to the zcml parameter in the [buildout] section, other than a convenient place to define zcml.

Typically an [instance] section will refer to it:

[instance]
recipe = plone.recipe.zope2instance
eggs = Plone
zcml = ${buildout:zcml}

The use of buildout:zcml similar to buildout:eggs is an anti-pattern, IMO

Answer 2

In buildout config files, name=value can be used in two ways:

• to specify a value for a name that has predefined functionality
• to assign a name to a value to avoid copy and paste.

buildout:zcml is an example of the second case.

In other words, the only reason to use buildout:zcml would be the need to use its value in various places.

However, when I need to reuse zcml, I rather define it in a plone.recipe.zope2instance part. And reuse that value in another part.