Важно: Этот документ применим к Plone 3.2 и выше. В версиях 3.2 и ниже buildout.cfg отличается, так как Plone не был полностью еггофицирован.

buildout.cfg - это самый главный файл в окружении buildout. Вот его содержание:

[buildout]
parts =
    zope2
    productdistros
    instance
    zopepy

# Change the number here, and in find-links below, to change the version of
# Plone being used
extends = http://dist.plone.org/release/3.3.5/versions.cfg
versions = versions

# Add additional egg download sources here. dist.plone.org contains archives
# of Plone packages.
find-links =
    http://dist.plone.org/release/3.3.5
    http://dist.plone.org/thirdparty

# Add additional eggs here
eggs =
    
# Reference any eggs you are developing here, one per line
# e.g.: develop = src/my.package
develop =

[zope2]
recipe = plone.recipe.zope2install
url = ${versions:zope2-url}

# Use this section to download additional old-style products.
# List any number of URLs for product tarballs under URLs (separate
# with whitespace, or break over several lines, with subsequent lines
# indented). If any archives contain several products inside a top-level
# directory, list the archive file name (i.e. the last part of the URL, 
# normally with a .tar.gz suffix or similar) under 'nested-packages'.
# If any archives extract to a product directory with a version suffix, list
# the archive name under 'version-suffix-packages'.
[productdistros]
recipe = plone.recipe.distros
urls =
nested-packages =
version-suffix-packages = 

[instance]
recipe = plone.recipe.zope2instance
zope2-location = ${zope2:location}
user = admin:admin
http-address = 8080
# comment the following two options in production sites
debug-mode = on
verbose-security = on

# If you want Zope to know about any additional eggs, list them here.
# This should include any development eggs you listed in develop-eggs above,
# e.g. eggs = Plone my.package
eggs =
    Plone
    ${buildout:eggs}

# If you want to register ZCML slugs for any packages, list them here.
# e.g. zcml = my.package my.other.package
zcml = 

products =
    ${buildout:directory}/products
    ${productdistros:location}

[zopepy]
recipe = zc.recipe.egg
eggs = ${instance:eggs}
interpreter = zopepy
extra-paths = ${zope2:location}/lib/python
scripts = zopepy

Давайте пройдемся по этому файлу:

Эта секция - стартовая точка всего файла. Это список частей, которые сконфигурированы в отдельные секции далее в этом файле. Каждая часть имеет соответствующий рецепт - имя егг-пакета, который знает как выполнять конкретную задачу, например, собрать Zope или создать инстанс. Рецепт обычно использует несколько параметров конфигурации.

Наши глобальные настройки следующие:

[buildout]
parts =
    zope2
    productdistros
    instance
    zopepy

find-links =
    http://dist.plone.org/release/3.3.5
    http://dist.plone.org/thirdparty

eggs =
    
develop =

Эта конфигурация определяет, что части zope2, productdistros, instance и zopepy будут выполнены в заданном порядке. Далее мы говорим buildout, что он может искать по нескольким адресам егг-пакеты для загрузки. Также он всегда будет искать в Cheese Shop.

Заметьте, что части конфигурации разбиты в несколько строк. Чтобы это работало, все строки должны начинаться с  4 пробелов.

Дальше мы можем перечислить все егг-пакеты, который buildout должен загрузить и установить. Список можем включать указание версий. Например, если вы хотите sqlalchemy 0.3, а не 0.4, вы можете добавить следующее:

eggs = 
    sqlalchemy>=0.3,<0.4dev

Пожалуйста заметьте, что для работы Plone нужна python библиотека для работы с изображениями (PIL). В это примере допускается, что у вас уже есть эта библиотека установленная и доступная для python-интерпретатора, в противном случае вы можете установить в ваш buildout слегка модифицированную (чтобы обойти несколько общих проблем) версию с "thirdparty" python репозитория, добавив ее имя в список егг-пакетов:

eggs =
    PILwoTk

И полный путь к пакету в секции find-links:

find-links = http://dist.plone.org/thirdparty/PILwoTk-1.1.6.4.tar.gz

Наконец,  мы можем перечислить список егг-пакетов собственного производства, указав директорию, где они распакованы в исходном формате. Например:

eggs =
    my.package

develop = 
    src/my.package

Здесь предполагается, что в директории src/ существует егг-пакет с именем my.package. Немного позже мы узнаем как создавать такие пакеты. Заметьте, что мы должны также перечислить my.package как зависимый егг-пакет: егг-пакеты в разработки не добавляются автоматически в "рабочий набор" пакетов для Zope.

Эта часть внедряет Plone 3.2. Она ссылается на удаленный файл, где указаны версии всех необходимых пакетов. Посмотрите этот файл самостоятельно, чтобы увидеть как эти зависимости указаны.

# Change the number here, and in find-links below, to change the version of
# Plone being used
extends = http://dist.plone.org/release/3.3.5/versions.cfg
versions = versions

Если вы хотите использовать локальную копию файла вместо удаленного, чтобы иметь возможность работать оффлайн, загрузите его в директорию buildout и сделайте такую ссылку:

extends = versions.cfg

Секция [zope2]

Это часть собирает Zope 2, используя рецепт  plone.recipe.zope2install.  Если вы указали существующую Zope установку, то вам эта часть не нужна. В противном случае она выглядит так:

[zope2]
recipe = plone.recipe.zope2install
url = ${versions:zope2-url}

Здесь мы используем путь для загрузки Zope, указанный в файлу versions. Это обеспечивает нам получение рекомендованной версии Zope. Вы можете указать адрес для загрузки вручную, если вы хотите использовать другую версию Zope. 

Секция [productdistros]

Эта секция использует рецепт plone.recipe.distros ,  который загружает дистрибуции  (архивы) продуктов в стиле Zope 2 и делает их видимыми для Zope. Она пустая в начале:

[productdistros]
recipe = plone.recipe.distros
urls =
nested-packages =
version-suffix-packages =

Однако, вы можете перечислить любое количество загрузок. Рецепт также может работать с архивами, которые содержат одну директорию верхнего уровня, в которую вложены директории продуктов (вложенные пакеты) или пакеты, название директории которых содержат указание версии и поэтому должно быть переименованы для получения действительной директории продукта (продукты с суффиксом версии).

Предположим у нас есть такие дистрибуции:

# A typical distribution 
ExampleProduct-1.0.tgz
 |
 |- ExampleProduct
     |
     |- __init__.py
     |- (product code)

# A version suffix distribution
AnotherExampleProduct-2.0.tgz
 |
 |- AnotherExampleProduct-2.0
     |
     |- __init__.py
     |- (product code)

# A nested package distribution
ExampleProductBundle-1.0.tgz
 |
 |- ExampleProductBundle
     |
     |- ProductOne
     |   |- __init__.py
     |   |- (product code)
     | 
     |- ProductTwo
         |- __init__.py
         |- (product code)

Вот так может выглядеть эта часть, если мы хотим установить эти три пакета:

[productdistros]
recipe = plone.recipe.distros
urls =
    http://example.com/dist/ExampleProduct-1.0.tgz
    http://example.com/dist/AnotherExampleProduct-2.0.tgz
    http://example.com/dist/ExampleProductBundle-1.0.tgz
nested-packages = ExampleProductBundle-1.0.tgz
version-suffix-packages = AnotherExampleProduct-2.0.tgz

Вы можете указать несколько загрузок на отдельных строчках. После выполнения  рецепта, директории продуктов могут быть найдены в parts/productdistros.

Секция [instance]

Секция instance собирает все вместе: она конфигурирует инстанс, используя скрипт plone.recipe.zope2instance . Так она выглядит:

[instance]
recipe = plone.recipe.zope2instance
zope2-location = ${zope2:location}
user = admin:admin
http-address = 8080
# comment the following two options in production sites
debug-mode = on
verbose-security = on

eggs =
    Plone
    ${buildout:eggs}

zcml = 

products =
    ${buildout:directory}/products
    ${productdistros:location}

Здесь мы определяем zope2-location значением переданным из части [zope2]. Потомы мы определяем логин и пароль администратора, который используется для создания первоначальной базы, и порт, c которым будет связан Zope. Мы также включаем режим отладки и режим verbose security ("многословная безопасность" - в этом режиме выводится полный лог ошибок, связанных безопасностью). Эти режимы полезные в режиме отладки, но не забудьте выключите их на рабочих сайтах, так как они могут нарушить безопасность ваших сайтов. Эти опции используются для генерации соответствующего файла zope.conf для инстанса. Обратитесь к описание рецепта на  Cheese Shop, чтобы узнать подробности о доступных опциях конфигурации.

Далле мы определяем какие егг-пакеты будут доступны в Zope. Мы ссылаемся на глобальную переменную egss из секции [buildout] и также на сам Plone. Вы можете добавить сюда дополнителые егг-пакеты, хотя обычно проще указывать их вверху файла, так, чтобы они включались в набор ${buidout:eggs}.

Файлы configure.zcml егг-пакетрв и продуктов, в которых нет поддержки z3c.autoinclude и ненаходящиеся в пространстве имен Products не загружаются Zope 3 автоматически. Чтобы загрузить ZCML файлы, мы может заствить buildout создать ZCML cлаг, перечислив пакет в опции zcml:

zcml =
    my.package
    my.package-overrides

Мы предполагаем, чтто my.package был определен ранее в buildout. Эта конфигурация обеспечит загрузку двух файлов: configure.zcml и overrides.zcml из этого пакета. Со временем необходимость в этих записях должна уменьшится, так как поддержка z3c.autoinclude становится более распространенной.

Секция [zopepy]

Финальная секция создает python интерпретатор, в котором есть все егг-пакеты (но нет Zope 2 продуктов), которые будут в Zope после старта.  Это может быть полезно для тестирования.

[zopepy]
recipe = zc.recipe.egg
eggs = ${instance:eggs}
interpreter = zopepy
extra-paths = ${zope2:location}/lib/python
scripts = zopepy

Здесь мы копируем егг-продукты из секции [instance] и включаем в pythonpath домашнею директорию Zope.

Чтобы установить глобальные настройки, затрагивающие все билдауты, создайте директорию .buildout (начинается с точки)  в вашей домашней директории и добавьте файл default.cfg. Любая настройка установленная здесь будет применена к соответствующему разделу в любом файле buildout.cfg, который вы выполните, пока не будет переписана более специфичной опцией в самом файле buildout.cfg.

Наиболее распространенные опции:

executable

Определяет python интерпретатор отличный от системного.  Это полезно, если у вас, скажем, установлен Python 2.5, но вы хотите, чтобы билдауты использовали Python 2.4 установленный где-либо.

eggs-directory

Определяет директорию, куда загружаются егг-пакеты. Это позволяет нескольким билдаутом разделять одни и те же пакеты, сохраняя место на диске и сокращая время загрузки. Заметьте, будут активированы только те пакеты, которые явно нужны для конкретного билдаута. Эта директория может содержать намного больше пакетов (или много разных версий одних и тех пакетов), чем те, которые используются в данный момент.

download-cache

Определяет общую директорию для загрузки архивов. Это опять может сохранить дисковое пространство и время загрузки. ЗАМЕЧАНИЯ: до zc.buildout 1.0 она называдась download-directory.

extends-cache

Определяет общую директорию для расширений конфигурация билдаута, которые загружаются по URL.  В Plone 3.2 так определяется версии егг-пакетов . Эта опция была добавлена в zc.buildout 1.4.1, до этого  оффлайн режим в сочетании с extends URL работать не будет.

Пример ~/.buildout/default.cfg:

[buildout]
executable = /opt/python24/bin/python
eggs-directory = /home/username/.buildout/eggs
download-cache = /home/username/.buildout/downloads
extends-cache = /home/username/.buildout/extends

Предполагается, что Python 2.4 установлен в /opt/python2.4. Вы должны создать директории eggs и downloads в ~/.buildout директории, чтобы последние две опции работали.

Способ установки сторонних продуктов зависит от того, является ли пакет "яйцом" или традиционным Zope 2 продуктом.

Пока релиз пакета есть на PyPi или еще где-нибудь, buildout может скачать и установить его, включая любые явно указанные зависимости. Просто перечислите егг-пакет и возможно его версию (в противном случае вы получите последнюю доступную версию) в опции eggs: 

[buildout]
...
eggs = 
    elementtree
    borg.project>=1.0b1,<2.0dev

Если вы хотите, чтобы buildout искал в отличном от PyPi месте, вы можете добавить URL по которому можно загрузить пакет в find-links. Фактически, у нас уже есть пример этого: elementree может быть найден на http://effbot.org/downloads, а не в PyPi. Итак, у нас есть:

[buildout]
...

find-links =
    http://dist.plone.org
    http://download.zope.org/ppix/
    http://download.zope.org/distribution/
    http://effbot.org/downloads

eggs =
    elementtree

Мы также перечислили несколько мест загрузки Zope и Plone яиц.

Мы снова перезапускаем buildout для вступления изменений в силу:

$ ./bin/buildout

Егг-пакеты в разработке

Если ваш пакет еще не перешел в стадию релиза, или вы хотите отслеживать его в Subversion, сделайте чекаут в директрию src/. Убедитесь, что вы загрузили полностью пакет, включая файл setup.py в корне.  Например, чтобы получить последнюю версию plone.portlets нужно:

$ cd src
$ svn co https://svn.plone.org/svn/plone/plone.portlets/trunk plone.portlets

Потом добавьте следующее в buildout.cfg:

[buildout]
...
eggs =
    ...
    plone.portlets

develop =
    src/plone.portlets

Заметьте, что:

• Опция develop содержит относительный путь к месту, где находится исходный код егг-пакета. Buildout ожидает найти подходящий файл setup.py в этой директории.
  
• Егг-пакеты в разработке всегда имеют приоритет над обычными егг-пакетами.
• Чтобы пакет был установлен, вам по-прежнему надо добавить его имя в опцию egg.
• При переопределении егг-пакета, поставляемого с Plone, вам может понадобиться указать его в секции eggs части [plone]:

[buildout]
...
develop =
    src/plone.portlets

...

[plone]
recipe = plone.recipe.plone
eggs = 
    plone.portlets

Это нужно, так как в plone.recipe.plone явно определены версии используемых пакетов для обеспечения правильной работы Plone.

Рецепты buildout (такие как plone.recipe.plone) распространяются в виде егг-пакетов. Вы можете использовать a development egg of a recipe перечислив его в опции develop. Нет необходимости указывать его явно в опции eggs, так как на него ссылается опция recipe соответствующей части.   

Распаковка пакета в папку products внутри buildout - это самый простой способ поставить традиционный Zope 2 продукт. 

Однако, этот подход затрудняет распространение вашего проекта и разделение его с другими разработчиками. Естественно лучше позволить билдауту загружать и устанавливать пакеты самостоятельно. Вы можете это сделать с помощью секции [productdistros] в buildout.cfg. Например, вы можете установить продукт c именем ExampleProduct и набор продуктов с именем ExampleProductBundle:

[productdistros]
recipe = plone.recipe.distros
urls =
    http://example.com/dist/ExampleProduct-1.0.tgz
    http://example.com/dist/ExampleProductBundle-1.0.tgz
nested-packages =
    ExampleProductBundle-1.0.tgz
version-suffix-packages =

Заметьте, что наш вымышленный ExampleProductBundle распространяется в виде единой директории, содержащей несколько продуктов в поддиректориях, поэтому мы перечисляем его в nested-packages.

Как всегда, если вы поменяли buildout.cfg, вы должны перезапустить buildout:

$ ./bin/buildout

[buildout]
...
eggs =
    elementtree
    borg.project

...

[instance]
...
zcml = 
    borg.project

Вы можете использовать следующий синтаксис, если надо загрузить overrides.zcml или meta.zcmlес:

zcml =
    some.package
    some.package-overrides
    some.package-meta

Многие разработчики предпочитают создавать единый продукт политики (известные также как продукт развертывания), которые организуют различные зависимости. Если у вас есть такой продукт, вы можете захотеть включить  зависимости прямо из продукта политики в configure.zcml таким образом:

<configure xmlns="http://namespace.zope.org/zope">

    <include package="borg.project" />

</configure>

В этом случае, вам по-прежнему нужно создать один слаг (используя опцию zcml как показано выше) для продукта политики.

$ cd src

$ paster create -t plone myorg.mypackage

Вам будет задана серия вопросов. Убедитесь, что пространство имен пакета и имя пакета соответствуют имени яйца. В нашем случае, пространство имен - myorg, а имя пакета - mypackage. Ответьте  False на вопрос является ли ваш пакет "zip safe" и введите остальные метаданные.

Теперь у вас есть:

• Файл setup.py который содержит введенные вами метаданные
  
• Пакет в myorg.mypackage/myorg/mypackage.  Ваш исходный код будет здесь.
  
• "Cкелет" файлов configure.zcml, tests.py и некоторых других.
• Немного общей документации в myorg.mypackage/docs.

Конечно, вы должны добавить этот пакет в ваш buildout. В buildout.cfg у вас может быть:

[buildout]

...

eggs =

    ...

    myorg.mypackage



develop =

    src/myorg.mypackage

Пока вы не планируете подключать этот пакет из какого-нибудь другого (или использовать автоматическую ZCML загрузку, которой далее), вы скорее всего должны добавить ZCML слаг:

[instance]

...

zcml =

    myorg.mypackage

Не забудьте перезапустить buildout:

$ ./bin/buildout

Автоматическая загрузка ZCML для вашего пакета

Если вы не планируете подключать ваш пакет из другого пакета, вы все равно можете не использовать ZCMl cлаг в buildout.cfg. Это позволяет избежать повторения имени пакета в файле конфигурации, о котором легко может забыть начинающий интегратор.  Начиная с Plone 3.3, вы можете обеспечить включение ZCMl пакета добавлением следующего кода в setup.py:

setup(...
entry_points="""
...
[z3c.autoinclude.plugin]
target = plone
...)
"""

 Для детальной информации обратитесь к документации setuptools о динамическом обнаружении сервисов и плагинов .

Указание зависимостей

Если ваш пакет имеет явные зависимости, вы можете перечислить их в  setup.py. Таким образом, buidlout автоматически загрузит и установит их. Зависимости перечисляются в аргументе install_requires метода setup(). По умолчанию, здесь есть setuptools, так как нам необходима поддержка пространства имен пакета. Вы можете изменить эту часть следующим образом, если хотите добавить sqlalchemy 0.3 (но не 0.4) и драйвер MySQL-Python:

install_requires=[

          'setuptools',

          'sqlalchemy>=0.3,<0.4dev',

          'MySQL-Python',

      ],

Загрузка яйца в Cheese Shop

Если вы хотите поделиться своим пакетом с Python сообществом и сделать легкой его установку с помощью инструментов подобных buildout и easy_install, вы можете загрузить пакет в Cheese Shop.

Прежде чем сделать это, вы должны:

• Сделать коммит последних изменений и присвоить тег релизу в системе контроля версий, если необходимо.
  
• Удалить(временно) файл setup.cfg: это сделает пакет development release.
  
• Убедиться, что номер версии правильный. Используйте общепринятые соглашения для версий, например, "1.0b2" для второй беты версии 1.0, или  "2.1.3rc1" для первого релиз-кандидата версии 2.1.3
• Если вы используете  Mac OS X, запустите сначала export COPY_EXTENDED_ATTRIBUTES_DISABLE=true в консоле - иначе, яйцо будет содержать вилки ресурсов Mac OS X, которые могут доставить проблемы пользователям Windows.

После того, как все будет готово, выполните следующую команду в директории пакета (например src/myorg.mypackage):

$ python setup.py egg_info -RDb "" sdist register upload

Вам будет предложено создать Chees Shop аккаунт, если у вас еще его нет. Вы можете выполнять загрузка каждый раз, когда вы пожелаете зарелизить новую версию.