Понимание buildout.cfg

Важно: Этот документ применим к 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. 

После выполнения рецепта, Zope 2 будет установлен в parts/zope2. Домашняя директория Zope станет parts/zope2/lib/python. 

 

Секция [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 становится более распространенной.

Наконец, мы перечисляем различные директории, которые содержат Zope 2 продукты - наподобие директории Products в традиционном инстансе. Заметьте, что директория products/ идет первой, за ней следуют загружаемые продукты из  части  [productdistros].
После выполнения рецепта, домашней директорией Zope станет parts/instance и контролирующий скрипт ./bin/instance будет создан.

Секция [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.

После выполнения рецепта скрипт ./bin/zopepy будет создан.