Tópico Entendendo o buildout.cfg do Manual do Desenvolvedor Plone traduzido para o Português
Como gerenciar o arquivo principal de configuração do buildout
Nota importante: Este documento se aplica ao Plone 3.2 ou superior. Em versões do Plone anteriores a 3.2, o arquivo padrão do buidout.cfg era significativamente diferente porque o Plone não era totalmente eggficado.
O buildout.cfg é o arquivo mais importante em seu novo ambiente de buildout. Veja como ele se parece:
Vamos agora percorrê-lo passo-a-passo.
A seção [buildout]
A seção [buildout] é o ponto de partida do arquivo de configuração. Ela contém uma lista de "parts" que serão configuradas separadamente em seções ao longo do arquivo. Cada part, ou seção, possui uma recipe (receita) associada que é o nome de um egg que sabe como executar uma determinada tarefa, por exemplo, construir o Zope ou criar uma instância do Zope. Uma recipe tipicamente contém um mínimo de configurações/opções.
Nossas configurações globais são as seguintes:
Isto especifica que as seções zope2, productdistros, instance e zopepy serão executadas, nessa ordem. Em seguida, nós dizemos ao buildout que ele pode pesquisar em uma lista de links quando for procurar eggs para fazer download. Sempre será adicionada a essa lista a busca no Cheese Shop, isto é, o PyPI: Python Package Index.
Observe que as configurações são comumente quebradas em múltiplas linhas. Para isso funcionar, todas as linhas depois da primeira devem começar com ao menos 4 espaços.
Em seguida, nós podemos listar quaisquer eggs que o buildout deva baixar e instalar para nós. Nesta configuração podemos incluir a especificação da versão. Por exemplo, se você quer o sqlalchemy 0.3 e não o 0.4, você poderia listar:
Por favor observe que você necessitará do Python Image Library (PIL) para o Plone funcionar. Este exemplo assume que você já possui esta biblioteca instalada e disponível em seu interpretador Python, mas todavia você pode instalar uma versão levemente modificada (a fim de contornar alguns problemas comuns) a partir de um repositório Plone "thirdparty" (de terceiro) acrescentando o seguinte nome em sua lista de eggs:
E o caminho completo para o pacote na opção find-links:
Por fim, nós podemos listar os development eggs, especificando o diretório onde estão os fontes do egg, por exemplo:
Isso presume que existe um egg chamado my.package no diretório src/. Nós veremos como criar eggs um pouco mais a frente neste tutorial. Observe que nós devemos acrescentar my.package também na lista de dependências: development eggs não são acrescentadas automaticamente no "working set" de eggs que serão instalados pelo Zope.
As linhas extends e versions
Essas opções foram introduzidas no Plone 3.2 e fazem referência a um arquivo remoto onde a versão de cada pacote necessário é especificada. Acesse tal arquivo remoto para ver você mesmo como tais dependências são especificadas.
Se você quer utilizar um arquivo local ao invés de um remoto para poder trabalhar offline, baixe-o para o seu diretório de buildout e o referencie assim:
A seção [zope2]
Esta seção constrói o Zope 2, utilizando a receita plone.recipe.zope2install. Se você escolher usar uma instalação do Zope já existente, você não precisará dessa parte. Em todo o caso, ela se parece com isso:
Aqui nós referenciamos a URL de download para o Zope conforme definido na seção versions. Isso assegura que nós sempre baixemos a versão recomendada do Zope. Ao invés disso, você poderia informar manualmente uma URL para download se desejar utilizar uma versão diferente do Zope.
Quando a receita está executando, o Zope 2 é instalado em parts/zope2. A home do Zope ficaria então em parts/zope2/lib/python.
A seção [productdistros]
Esta seção utiliza a recipe plone.recipe.distros e permite o download de distribuições old-style (tarballs) de produtos Zope 2, disponibilizando-os para o Zope. Por padrão vem vazia:
Todavia, você pode listar quantos produtos necessitar para que seja feito o download. Este recipe também é capaz de lidar com pacotes em diretórios de alto nível que contenham um conjunto de diretórios de produto (pacotes aninhados), ou com pacotes que tenham um número de versão no nome do diretório e, portanto, precisa ser renomeado para obter o diretório do produto real (pacote com versão como sufixo).
Considere as seguintes distribuições:
A seguir temos como esta seção deverá ser configurada para tentar instalar as três distribuições listadas acima:
Você pode especificar múltiplos downloads em linhas separadas. Quando a recipe é executada, os diretórios dos produtos importados são localizados em parts/productdistros.
A seção [instance]
A seção [instance] põe tudo junto. Ela configura uma instância do Zope através do script plone.recipe.zope2instance. Aqui está com que ela se parece:
Aqui, nós referenciamos a instalação do Zope2 configurada na seção [zope2] - se você especificou um local quando criou o buildout você o veria aqui. Então nós especificamos o usuário admin e a senha inicial que será usada apenas quando da criação do banco de dados inicial, e a porta na qual o Zope será vinculado. Nós também ativamos o modo de depuração e o modo de segurança detalhado. Eles são úteis para o desenvolvimento, mas lembre-se de desligá-los para sites em produção, uma vez que podem comprometer a segurança do seu site. Estas opções são usadas para gerar um arquivo zope.conf apropriado para a instância. Acesse página da recipe na Cheese Shop para maiores detalhes sobre as opções disponíveis.
Em seguida, nós especificamos quais eggs serão disponibilizados para o Zope. Isto faz referência ao "global" eggs da seção [buildout], bem como ao próprio Plone. Você pode incluir eggs adicionais aqui, porém geralmente é mais fácil especificá-los no começo do arquivo, de modo que eles sejam referenciados pela variável ${buildout:eggs}.
Arquivos configure.zcml do Zope 3 não são carregados automaticamente por eggs ou pacotes que não suportem z3c.autoinclude e que não estão no namespace Products. Para que pacotes comuns carreguem arquivos ZCML, nós podemos fazer o buildout criar uma ZCML slug listando os pacotes sob a opção zcml:
Aqui assume-se que my.package foi referenciado anteriormente no buildout. Isto carregaria os arquivos tanto o configure.zcml principal quanto o overrides.zcml deste pacote. A necessidade dessa entrada tende a desaparecer na medida que o uso do z3c.autoinclude se torna generalizado.
Finalmente, nós listamos os diretórios que contenham os produtos no formato Zope 2 - idêntico a pasta Products/ de uma instância convencional. Perceba que o diretório products/ na pasta do buildout principal vem primeiro, seguido pelos produtos baixados definidos na seção [productdistros].
Quando a recipe é executada, o diretório home da instância Zope será parts/instance, e será criado um script de controle em ./bin/instance.
A seção [zopepy]
Nesta última seção é criado um interpretador Python que tem todos os eggs e pacotes (exceto os produtos no estilo Zope 2) que o Zope teria durante a inicialização. Isto pode ser útil para testes.
Aqui nós copiamos os eggs da seção [instance], e incluímos o diretório home da instância do Zope no pythonpath.
Quando a recipe é executada, o script será criado em ./bin/zopepy.
Referências
Nota importante: Este documento se aplica ao Plone 3.2 ou superior. Em versões do Plone anteriores a 3.2, o arquivo padrão do buidout.cfg era significativamente diferente porque o Plone não era totalmente eggficado.
O buildout.cfg é o arquivo mais importante em seu novo ambiente de buildout. Veja como ele se parece:
[buildout]
parts =
zope2
productdistros
instance
zopepy
# Modifique o numero aqui, e no find-links abaixo, para alterar a versão
# do Plone que será utilizado
extends = http://dist.plone.org/release/3.3.5/versions.cfg
versions = versions
# Adicione aqui fontes adicionais para download de eggs (repositórios).
# O repositório dist.plone.org contém os arquivos de pacotes do Plone.
find-links =
http://dist.plone.org/release/3.3.5
http://dist.plone.org/thirdparty
# Acrescente eggs adicionais aqui.
eggs =
# Referencie quaisquer eggs que esteja desenvolvendo aqui, um por linha
# por exemplo: develop = src/my.package
develop =
[zope2]
recipe = plone.recipe.zope2install
url = ${versions:zope2-url}
# Utilize esta seção para baixar produtos old-style adicionais.
# Liste as URLs dos tarballs dos produtos (separados por espaço
# em branco, ou quebra de linha, com linhas subseqüentes indentadas).
# Caso algum arquivo contenha muitos produtos como em um diretório
# de alto nível, liste os nomes de arquivo (isto é, a última parte da URL,
# normalmente com um sufixo .tar.gz ou similar) sob 'nested-packages'.
# Se algum arquivo extrai para um diretório de algum produto com o sufixo
# da versão, liste o nome do arquivo em '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
# Para sites em produção, comente as duas linhas a seguir
debug-mode = on
verbose-security = on
# Se você quer que o Zope reconheça qualquer egg adicional, liste-os aqui.
# Isto deveria incluir qualquer development egg que você listou em develop-eggs
# acima, por exemplo: eggs = Plone my.package
eggs =
Plone
${buildout:eggs}
# Se você quer registrar slugs ZCML para algum pacote, liste-os aqui.
# por exemplo: 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
Vamos agora percorrê-lo passo-a-passo.
A seção [buildout]
A seção [buildout] é o ponto de partida do arquivo de configuração. Ela contém uma lista de "parts" que serão configuradas separadamente em seções ao longo do arquivo. Cada part, ou seção, possui uma recipe (receita) associada que é o nome de um egg que sabe como executar uma determinada tarefa, por exemplo, construir o Zope ou criar uma instância do Zope. Uma recipe tipicamente contém um mínimo de configurações/opções.
Nossas configurações globais são as seguintes:
[buildout]
parts =
zope2
productdistros
instance
zopepy
find-links =
http://dist.plone.org/release/3.3.5
http://dist.plone.org/thirdparty
eggs =
develop =
Isto especifica que as seções zope2, productdistros, instance e zopepy serão executadas, nessa ordem. Em seguida, nós dizemos ao buildout que ele pode pesquisar em uma lista de links quando for procurar eggs para fazer download. Sempre será adicionada a essa lista a busca no Cheese Shop, isto é, o PyPI: Python Package Index.
Observe que as configurações são comumente quebradas em múltiplas linhas. Para isso funcionar, todas as linhas depois da primeira devem começar com ao menos 4 espaços.
Em seguida, nós podemos listar quaisquer eggs que o buildout deva baixar e instalar para nós. Nesta configuração podemos incluir a especificação da versão. Por exemplo, se você quer o sqlalchemy 0.3 e não o 0.4, você poderia listar:
eggs =
sqlalchemy>=0.3,<0.4dev
Por favor observe que você necessitará do Python Image Library (PIL) para o Plone funcionar. Este exemplo assume que você já possui esta biblioteca instalada e disponível em seu interpretador Python, mas todavia você pode instalar uma versão levemente modificada (a fim de contornar alguns problemas comuns) a partir de um repositório Plone "thirdparty" (de terceiro) acrescentando o seguinte nome em sua lista de eggs:
eggs =
PILwoTk
E o caminho completo para o pacote na opção find-links:
find-links = http://dist.plone.org/thirdparty/PILwoTk-1.1.6.4.tar.gz
Por fim, nós podemos listar os development eggs, especificando o diretório onde estão os fontes do egg, por exemplo:
eggs =
my.package
develop =
src/my.package
Isso presume que existe um egg chamado my.package no diretório src/. Nós veremos como criar eggs um pouco mais a frente neste tutorial. Observe que nós devemos acrescentar my.package também na lista de dependências: development eggs não são acrescentadas automaticamente no "working set" de eggs que serão instalados pelo Zope.
As linhas extends e versions
Essas opções foram introduzidas no Plone 3.2 e fazem referência a um arquivo remoto onde a versão de cada pacote necessário é especificada. Acesse tal arquivo remoto para ver você mesmo como tais dependências são especificadas.
# Modifique o numero aqui, e no find-links abaixo, para alterar a versão
# do Plone que será utilizado extends = http://dist.plone.org/release/3.3.5/versions.cfg versions = versions
Se você quer utilizar um arquivo local ao invés de um remoto para poder trabalhar offline, baixe-o para o seu diretório de buildout e o referencie assim:
extends = versions.cfg
A seção [zope2]
Esta seção constrói o Zope 2, utilizando a receita plone.recipe.zope2install. Se você escolher usar uma instalação do Zope já existente, você não precisará dessa parte. Em todo o caso, ela se parece com isso:
[zope2]
recipe = plone.recipe.zope2install
url = ${versions:zope2-url}
Aqui nós referenciamos a URL de download para o Zope conforme definido na seção versions. Isso assegura que nós sempre baixemos a versão recomendada do Zope. Ao invés disso, você poderia informar manualmente uma URL para download se desejar utilizar uma versão diferente do Zope.
Quando a receita está executando, o Zope 2 é instalado em parts/zope2. A home do Zope ficaria então em parts/zope2/lib/python.
A seção [productdistros]
Esta seção utiliza a recipe plone.recipe.distros e permite o download de distribuições old-style (tarballs) de produtos Zope 2, disponibilizando-os para o Zope. Por padrão vem vazia:
[productdistros] recipe = plone.recipe.distros urls = nested-packages = version-suffix-packages =
Todavia, você pode listar quantos produtos necessitar para que seja feito o download. Este recipe também é capaz de lidar com pacotes em diretórios de alto nível que contenham um conjunto de diretórios de produto (pacotes aninhados), ou com pacotes que tenham um número de versão no nome do diretório e, portanto, precisa ser renomeado para obter o diretório do produto real (pacote com versão como sufixo).
Considere as seguintes distribuições:
# Uma distribuição típica
ExampleProduct-1.0.tgz
|
|- ExampleProduct
|
|- __init__.py
|- (código do produto)
# Uma distribuição com versão como sufixo
AnotherExampleProduct-2.0.tgz
|
|- AnotherExampleProduct-2.0
|
|- __init__.py
|- (código do produto)
# Uma distribuição com pacotes aninhados
ExampleProductBundle-1.0.tgz
|
|- ExampleProductBundle
|
|- ProductOne
| |- __init__.py
| |- (código do produto)
|
|- ProductTwo
|- __init__.py
|- (código do produto)
A seguir temos como esta seção deverá ser configurada para tentar instalar as três distribuições listadas acima:
[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
Você pode especificar múltiplos downloads em linhas separadas. Quando a recipe é executada, os diretórios dos produtos importados são localizados em parts/productdistros.
A seção [instance]
A seção [instance] põe tudo junto. Ela configura uma instância do Zope através do script plone.recipe.zope2instance. Aqui está com que ela se parece:
[instance]
recipe = plone.recipe.zope2instance
zope2-location = ${zope2:location}
user = admin:admin
http-address = 8080
# comente as duas opções abaixo para sites em produção
debug-mode = on
verbose-security = on
eggs =
Plone
${buildout:eggs}
zcml =
products =
${buildout:directory}/products
${productdistros:location}
Aqui, nós referenciamos a instalação do Zope2 configurada na seção [zope2] - se você especificou um local quando criou o buildout você o veria aqui. Então nós especificamos o usuário admin e a senha inicial que será usada apenas quando da criação do banco de dados inicial, e a porta na qual o Zope será vinculado. Nós também ativamos o modo de depuração e o modo de segurança detalhado. Eles são úteis para o desenvolvimento, mas lembre-se de desligá-los para sites em produção, uma vez que podem comprometer a segurança do seu site. Estas opções são usadas para gerar um arquivo zope.conf apropriado para a instância. Acesse página da recipe na Cheese Shop para maiores detalhes sobre as opções disponíveis.
Em seguida, nós especificamos quais eggs serão disponibilizados para o Zope. Isto faz referência ao "global" eggs da seção [buildout], bem como ao próprio Plone. Você pode incluir eggs adicionais aqui, porém geralmente é mais fácil especificá-los no começo do arquivo, de modo que eles sejam referenciados pela variável ${buildout:eggs}.
Arquivos configure.zcml do Zope 3 não são carregados automaticamente por eggs ou pacotes que não suportem z3c.autoinclude e que não estão no namespace Products. Para que pacotes comuns carreguem arquivos ZCML, nós podemos fazer o buildout criar uma ZCML slug listando os pacotes sob a opção zcml:
zcml =
my.package
my.package-overrides
Aqui assume-se que my.package foi referenciado anteriormente no buildout. Isto carregaria os arquivos tanto o configure.zcml principal quanto o overrides.zcml deste pacote. A necessidade dessa entrada tende a desaparecer na medida que o uso do z3c.autoinclude se torna generalizado.
Finalmente, nós listamos os diretórios que contenham os produtos no formato Zope 2 - idêntico a pasta Products/ de uma instância convencional. Perceba que o diretório products/ na pasta do buildout principal vem primeiro, seguido pelos produtos baixados definidos na seção [productdistros].
Quando a recipe é executada, o diretório home da instância Zope será parts/instance, e será criado um script de controle em ./bin/instance.
A seção [zopepy]
Nesta última seção é criado um interpretador Python que tem todos os eggs e pacotes (exceto os produtos no estilo Zope 2) que o Zope teria durante a inicialização. Isto pode ser útil para testes.
[zopepy]
recipe = zc.recipe.egg
eggs = ${instance:eggs}
interpreter = zopepy
extra-paths = ${zope2:location}/lib/python
scripts = zopepy
Aqui nós copiamos os eggs da seção [instance], e incluímos o diretório home da instância do Zope no pythonpath.
Quando a recipe é executada, o script será criado em ./bin/zopepy.
Referências
- Plone.org (http://plone.org/documentation/manual/developer-manual/managing-projects-with-buildout/understanding-buildout.cfg) acessado em 21 de novembro de 2011.
Comentários
Postar um comentário