daily pastebin goal

Managing projects with Buildout (Plone)

a guest Sep 11th, 2012 203 Never
Not a member of Pastebin yet? Sign Up, it unlocks many cool features!
  1. This is Google's cache of http://staging.plone.org/documentation/manual/developer-manual/managing-projects-with-buildout/referencemanual-all-pages. It is a snapshot of the page as it appeared on 31 Jul 2012 15:43:38 GMT. The current page could have changed in the meantime. Learn more
  2. Tip: To quickly find your search term on this page, press Ctrl+F or ⌘-F (Mac) and use the find bar.
  4. Text-only version
  8. Log in
  9. Login to Plone.org
  10. username  password  
  11. Forgot password?
  13. Click here to create an account
  14. Home
  15. Download & Extend
  16. Documentation
  17. Get Involved
  18. Plone Foundation
  19. Support
  20. Providers
  21. Manuals
  22. Knowledge Base
  23. FAQs
  24. Error Reference
  25. Links
  26. Glossary
  27. Managing projects with Buildout
  29. « Return to page index
  31. Plone Developer Manual is a comprehensive guide to Plone programming.
  33. 1. Introduction
  35. Or: "What's wrong with a plain old Zope instance"?
  37. This tutorial shows how to install Plone 3 into a buildout, and how to use that buildout when working on a software project that extends Plone. A buildout is a self-contained environment where you can manage the dependencies (including Zope and Plone and any third-party products or libraries you need) and custom code for your project. Even if you are not planning on writing any custom code, the buildout approach is an easy way to install Plone in a robust, well-tested manner.  As of Plone 3.2, all of the installers are now buildout based.
  39. Prior to Plone 3.0, most developers and users who did not use a GUI installer, would set up a Zope instance, drop in a few products into the Products folder, and be done with it. Unfortunately, this approach has a few problems:
  41. Plain old Zope instances are not very well equipped to deal with packages distributed as python eggs or using setuptools namespace packages. Many new packages in Plone 3 are made in this way, and more and more third party modules will be as well.
  42. Without access to the metadata that is held in eggs, developers may find it too time-consuming or confusing to factor their work into multiple packages that are more re-usable, preferring monolithic products that are impossible to re-use outside Zope.
  43. Without any further tools, it is cumbersome to repeat a setup across different environments.
  44. As eggs become more important, developers should look to employ more appropriate tools for managing their code. zc.buildout, hereafter referred to only as "buildout" is one such tool. This tutorial shows how to use buildout for day-to-day development as well as deployment.
  46. More buildout documentation and background
  48. Buildout was created by Jim Fulton of Zope Corporation, and is documented in depth at: http://buildout.org/
  50. 2. Packages, products and eggs
  52. Looking at the core concepts in more detail
  54. This page has been removed due to its old, inaccurate, and misleading information.
  56. For usage of paster templates please refer to this document.
  58. -Mikko
  60. 3. Prerequisites
  62. A few things you need before we can get started
  64. This page has been removed as it contained old, inaccurate and misleading information.
  66. For usage of paster templates to create Plone add-on products please refer to this document.
  68. -Mikko
  70. 4. Creating a buildout for your project
  72. How to create a new buildout for a project, adding Plone and other third party products as dependencies
  74. A part of this page has been removed as it contained old, inaccurate and misleading information.
  76. For usage of paster templates to create Plone add-on products please refer to this document.
  78. -Mikko
  80. Â
  82. Now, enter the newly created myproject directory, and run the buildout bootstrap script.  NOTE: Python 2.4 is currently required to Plone 4.x:
  84. $ cd myproject
  85. $ python2.6 bootstrap.py
  86. This will create a number of directories and scripts and dowload the latest version of the zc.buildout egg. This step should be needed only once.
  88. To get started straight away, run:
  90. $ ./bin/buildout
  91. This reads the generated buildout.cfg file and executes its various "parts", setting up Zope, creating a Zope instance, downloading and installing Plone. We will explain this file in more detail shortly.
  93. You will need to run ./bin/buildout again each time you change buildout.cfg. If you do not want buildout to go online and look for updated versions of eggs or download other archives, you can run it in non-updating, offline mode, with;
  95. $ ./bin/buildout -No
  96. To start Zope in foreground and debug mode, run:
  98. $ ./bin/instance fg
  99. The instance script is analogous to zopectl as found in a standard Zope instance. You can use ./bin/instance start to run Zope in daemon mode. It can also be used to run tests:
  101. $ ./bin/instance test -s plone.portlets
  102. Running:
  104. bin/instance console
  105. is equivalent to bin/instance fg, but does not implicitly turn on debug mode but respects the debug-mode setting in buildout.cfg. This can be useful to run Zope in non-development mode with daemon-control programs like supervisord.
  107. Once your buildout installation is up and running, you will still need to install a Plone site.  Log in to the Zope Management Interface (ZMI) and from "select type to add..." choose Plone Site.  Fill in the required details and submit.  Now you have a Plone site at the ID that you specified.
  109. Directories in the buildout
  111. Before we dive into buildout.cfg, let us take a quick look at the directories that buildout has created for us:
  113. bin/
  114. Contains various executables, including the buildout command, and the instance Zope control script.
  115. eggs/
  116. Contains eggs that buildout has downloaded. These will be explicitly activated by the control scripts in the bin/ directory.
  118. Contains non-egg downloads, such as the Zope source code archive.
  119. var/
  120. Contains the log files (in var/log/) and the file storage ZODB data (in var/filestorage/Data.fs). Buildout will never overwrite these.
  121. If you want to import a .zexp file, place it in the var/instance/imports folder.
  122. Previously one had to put that file into parts/instance/import, but this folder gets wiped and regenerated when running bin/buildout, so the import location was changed.
  124. src/
  125. Initially empty. You can place your own development eggs here and reference them in buildout.cfg. More on that later.
  126. products/
  127. This is analogous to a Zope instance's Products/ directory (note the difference in capitalisation). If you are developing any old-style Zope 2 products, place them here. We will see how buildout can automatically download and manage archives of products, but if you want to extract a product dependency manually, or check one out from Subversion, this is the place to do so.
  128. parts/
  129. Contains code and data managed by buildout. In our case, it will include the local Zope installation, a buildout-managed Zope instance, and Plone's source code. In general, you should not modify anything in this directory, as buildout may overwrite your changes.
  130. You can check in a buildout directory to a source code repository to share it among developers. In this case, you should ignore the directories bin/, eggs/, downloads/, var/, and parts/. Each developer can run bootstrap.py to get these back, and will normally need local copies anyway. All your configuration should be in the buildout.cfg file, and all custom code in src/ or products/.
  132. 5. Understanding buildout.cfg
  134. How to manage the main buildout configuration file
  136. Important note: This document applies to Plone 3.2 onwards. In Plone versions prior to 3.2 the vanilla buildout.cfg file was significatively different because Plone wasn't fully eggified.
  138. buildout.cfg is the most important file in your new buildout environment. Here is how it looks:
  140. [buildout]
  141. parts =
  142.     zope2
  143.     productdistros
  144.     instance
  145.     zopepy
  147. # Change the number here, and in find-links below, to change the version of
  148. # Plone being used
  149. extends = http://dist.plone.org/release/3.3.5/versions.cfg
  150. versions = versions
  152. # Add additional egg download sources here. dist.plone.org contains archives
  153. # of Plone packages.
  154. find-links =
  155.     http://dist.plone.org/release/3.3.5
  156.     http://dist.plone.org/thirdparty
  158. # Add additional eggs here
  159. eggs =
  161. # Reference any eggs you are developing here, one per line
  162. # e.g.: develop = src/my.package
  163. develop =
  165. [zope2]
  166. recipe = plone.recipe.zope2install
  167. url = ${versions:zope2-url}
  169. # Use this section to download additional old-style products.
  170. # List any number of URLs for product tarballs under URLs (separate
  171. # with whitespace, or break over several lines, with subsequent lines
  172. # indented). If any archives contain several products inside a top-level
  173. # directory, list the archive file name (i.e. the last part of the URL,
  174. # normally with a .tar.gz suffix or similar) under 'nested-packages'.
  175. # If any archives extract to a product directory with a version suffix, list
  176. # the archive name under 'version-suffix-packages'.
  177. [productdistros]
  178. recipe = plone.recipe.distros
  179. urls =
  180. nested-packages =
  181. version-suffix-packages =
  183. [instance]
  184. recipe = plone.recipe.zope2instance
  185. zope2-location = ${zope2:location}
  186. user = admin:admin
  187. http-address = 8080
  188. # comment the following two options in production sites
  189. debug-mode = on
  190. verbose-security = on
  192. # If you want Zope to know about any additional eggs, list them here.
  193. # This should include any development eggs you listed in develop-eggs above,
  194. # e.g. eggs = Plone my.package
  195. eggs =
  196.     Plone
  197.     ${buildout:eggs}
  199. # If you want to register ZCML slugs for any packages, list them here.
  200. # e.g. zcml = my.package my.other.package
  201. zcml =
  203. products =
  204.     ${buildout:directory}/products
  205.     ${productdistros:location}
  207. [zopepy]
  208. recipe = zc.recipe.egg
  209. eggs = ${instance:eggs}
  210. interpreter = zopepy
  211. extra-paths = ${zope2:location}/lib/python
  212. scripts = zopepy
  213. Let us walk through this file step-by-step:
  215. The main [buildout] section
  217. The [buildout] section is the starting point for the file. It lists a number of "parts", which are configured in separate sections later in the file. Each part has an associated recipe, which is the name of an egg that knows how to perform a particular task, e.g. build Zope or create a Zope instance. A recipe typically takes a few configuration options.
  219. Our global settings are as follows:
  221. [buildout]
  222. parts =
  223.     zope2
  224.     productdistros
  225.     instance
  226.     zopepy
  228. find-links =
  229.     http://dist.plone.org/release/3.3.5
  230.     http://dist.plone.org/thirdparty
  232. eggs =
  234. develop =
  235. This specifies that the parts zope2, productdistros, instance and zopepy will be run, in that order. Then, we tell buildout that it can search one of a number of URLs when it is looking for eggs to download. In addition, it will always search the Cheese Shop.
  237. Note that configuration entries are commonly split into multiple lines.  For this to work, all lines after the first must begin with at least 4 spaces.
  239. Next, we can list any eggs that buildout should download and install for us. This may include version specifications. For example, if you want sqlalchemy 0.3,  but not 0.4, you could list;
  241. eggs =
  242.     sqlalchemy>=0.3,<0.4dev
  243. Please note that you will need the Python Imaging Library (PIL) for Plone to work. This example assumes that you have this library already installed and available from your Python interpreter, but otherwise you can install a slightly modified (to workaround some common problems) version from the "thirdparty" Plone repository in your buildout adding its name to the eggs list:
  245. eggs =
  246.     PILwoTk
  247. And the full path to the package in the find-links, e.g.:
  249. find-links = http://dist.plone.org/thirdparty/PILwoTk-
  250. Finally, we can list development eggs, by specifying a directory where the egg is extracted in source format. For example:
  252. eggs =
  253.     my.package
  255. develop =
  256.     src/my.package
  257. This presumes that there is an egg called my.package in the src/ directory. We will learn how to create such eggs a little later in this tutorial. Notice how we must also list my.package as an actual egg dependency: development eggs are not automatically added to the "working set" of eggs that are installed for Zope.
  259. The extends and versions lines
  261. This part was introduced with Plone 3.2. It references a remote file where the version of each needed package is specified. Check that remote file to see yourself how these dependencies are specified.
  263. # Change the number here, and in find-links below, to change the version of
  264. # Plone being used
  265. extends = http://dist.plone.org/release/3.3.5/versions.cfg
  266. versions = versions
  267. If you want to use a local file instead of a remote one to be able to work offline, download it to your buildout directory and reference it like this:
  269. extends = versions.cfg
  270. The [zope2] section
  272. This part builds Zope 2, using plone.recipe.zope2install. If you specified an existing Zope installation, you will not have this part. Otherwise, it looks like this:
  274. [zope2]
  275. recipe = plone.recipe.zope2install
  276. url = ${versions:zope2-url}
  277. Here, we reference the download location for Zope as present in the versions file. This ensures that we always get the recommended version of Zope. You could specify a download URL manually instead, if you wanted to use a different version of Zope.
  279. When the recipe is run, Zope 2 is installed in parts/zope2. The Zope software home becomes parts/zope2/lib/python.
  281. The [productdistros] section
  283. This uses the plone.recipe.distros recipe, which is able to download distributions (archives) of Zope 2 style products and make them available to Zope. It is empty to begin with:
  285. [productdistros]
  286. recipe = plone.recipe.distros
  287. urls =
  288. nested-packages =
  289. version-suffix-packages =
  290. However, you can list any number of downloads. The recipe is also able to deal with archives that contain a single top-level directory that contains a bundle of actual product directories (nested-packages), or packages that have a version number in the directory name and thus need to be renamed to get the actual product directory (version-suffix-packages).
  292. Consider the following distributions:
  294. # A typical distribution
  295. ExampleProduct-1.0.tgz
  296.  |
  297.  |- ExampleProduct
  298.      |
  299.      |- __init__.py
  300.      |- (product code)
  302. # A version suffix distribution
  303. AnotherExampleProduct-2.0.tgz
  304.  |
  305.  |- AnotherExampleProduct-2.0
  306.      |
  307.      |- __init__.py
  308.      |- (product code)
  310. # A nested package distribution
  311. ExampleProductBundle-1.0.tgz
  312.  |
  313.  |- ExampleProductBundle
  314.      |
  315.      |- ProductOne
  316.      |   |- __init__.py
  317.      |   |- (product code)
  318.      |
  319.      |- ProductTwo
  320.          |- __init__.py
  321.          |- (product code)
  322. Here is what the part would look like if we try to install the three distributions above:
  324. [productdistros]
  325. recipe = plone.recipe.distros
  326. urls =
  327.     http://example.com/dist/ExampleProduct-1.0.tgz
  328.     http://example.com/dist/AnotherExampleProduct-2.0.tgz
  329.     http://example.com/dist/ExampleProductBundle-1.0.tgz
  330. nested-packages = ExampleProductBundle-1.0.tgz
  331. version-suffix-packages = AnotherExampleProduct-2.0.tgz
  332. You can specify multiple downloads on separate lines. When the recipe is run, the product directories for downloaded products are found in parts/productdistros.
  334. The [instance] section
  336. The instance section pulls it all together: It configures a Zope instance using the plone.recipe.zope2instance script. Here is how it looks:
  338. [instance]
  339. recipe = plone.recipe.zope2instance
  340. zope2-location = ${zope2:location}
  341. user = admin:admin
  342. http-address = 8080
  343. # comment the following two options in production sites
  344. debug-mode = on
  345. verbose-security = on
  347. eggs =
  348.     Plone
  349.     ${buildout:eggs}
  351. zcml =
  353. products =
  354.     ${buildout:directory}/products
  355.     ${productdistros:location}
  356. Here, we reference the Zope 2 installation from the [zope2] part - if you specified a location yourself when creating the buildout, you would see that one here. Then, we specify the initial admin user and password used only when creating the initial database, and the port that Zope will be bound to. We also turn on debug mode and verbose security. They are useful for development, but remember to turn them off in production sites since they can compromise the security of your site. These options are used to generate an appropriate zope.conf file for this instance. See the recipe page in the Cheese Shop for more details on the options available.
  358. Next, we specify which eggs that will be made available to Zope. This references the "global" eggs from the [buildout] section, as well as Plone itself. You could add additional eggs here, though it is generally easier to specify these at the top of the file, so that they get included in the ${buildout:eggs} working set.
  360. Zope 3 configure.zcml files are not automatically loaded for eggs or packages that lack z3c.autoinclude support and are not in the Products namespace. To load ZCML files for a regular package, we can make buildout create a ZCML slug by listing the package under the zcml option:
  362. zcml =
  363.     my.package
  364.     my.package-overrides
  365. This assumes that my.package was previously referenced in the buildout. This would load both the main configure.zcml and the overrides.zcml file from this package.  Over time, the need for these entries should diminish, as z3c.autoinclude support becomes widespread.
  367. Finally, we list the various directories that contain Zope 2 style products - akin to the Products/ directory in a traditional instance. Notice how the products/ directory in the main buildout directory comes first, followed by the products downloaded with the [productdistros] part.
  369. When the recipe is run, the Zope instance home will be parts/instance, and a control script is created in ./bin/instance.
  371. The [zopepy] section
  373. This final section creates a Python interpreter that has all the eggs and packages (but not Zope 2 style products) that Zope would have during startup. This can be useful for testing purposes.
  375. [zopepy]
  376. recipe = zc.recipe.egg
  377. eggs = ${instance:eggs}
  378. interpreter = zopepy
  379. extra-paths = ${zope2:location}/lib/python
  380. scripts = zopepy
  381. Here, we copy the eggs from the [instance] section, and include in the pythonpath the Zope instance home.
  383. When the recipe is run, the script will be created in ./bin/zopepy.
  385. 6. Creating a buildout defaults file
  387. This makes it possible to share configuration across multiple buildouts, and save some time and disk space.
  389. To set "global" options affecting all buildouts, create a directory .buildout (note leading dot) in your home directory, and add a file there called default.cfg. Any option set here will be applied to the corresponding section in any buildout.cfg that you run, unless it is overridden by a more specific option in the buildout.cfg file itself.
  391. The most common options are:
  393. executable
  394. Specify a python interpreter other than the system default. This is useful if you have Python 2.5 installed, say, but you want your buildouts to use another installation of Python 2.4.
  395. eggs-directory
  396. Specify a directory where eggs will be downloaded. This allows multiple buildouts to share the same eggs, saving disk space and download time. Note that only those eggs explicitly required by a particular buildout will be activated. The eggs directory may contain many more eggs (or many different versions of the same package) than what is used at any one time.
  397. download-cache
  398. Specify a shared directory for downloaded archives. Again, this can save disk space and download time. NOTE: before zc.buildout 1.0, this was called download-directory
  399. extends-cache
  400. Specify a shared directory for extended buildout configurations that are downloaded from a URL. As of Plone 3.2 this is how Plone pins the versions of its eggs. This option was added in zc.buildout 1.4.1, prior to that the offline mode in combination with a extends URL would not work.
  401. Here is an example ~/.buildout/default.cfg setting all three:
  403. [buildout]
  404. executable = /opt/python24/bin/python
  405. eggs-directory = /home/username/.buildout/eggs
  406. download-cache = /home/username/.buildout/downloads
  407. extends-cache = /home/username/.buildout/extends
  408. This assumes Python 2.4 is installed in /opt/python2.4. For the last two options to work, you would need to create the directories eggs and downloads inside the ~/.buildout directory.
  410. 7. Installing a third party product
  412. How to install a new package using these tools
  414. How to install a new third-party products will depend on whether it is packaged as an egg, or a traditional Zope 2 product.
  416. Installing eggs
  418. So long as an egg has a release in the PyPi or elsewhere, buildout can download and install it, including any explicitly specified dependencies. Simply list the egg, and optionally a version (otherwise, you get the latest available), in the eggs option.
  420. [buildout]
  421. ...
  422. eggs =
  423.     elementtree
  424.     borg.project>=1.0b1,<2.0dev
  425. If you want buildout to search an index other than PyPi's, you can add a URL to find-links that contains download links for the eggs. In fact, we have already seen an example of this: elementtree is found at http://effbot.org/downloads, not in PyPi directly. Thus, we have:
  427. [buildout]
  428. ...
  430. find-links =
  431.     http://dist.plone.org
  432.     http://download.zope.org/ppix/
  433.     http://download.zope.org/distribution/
  434.     http://effbot.org/downloads
  436. eggs =
  437.     elementtree
  438. We have also listed some of the download locations for Zope and Plone eggs.
  440. Again - re-run buildout for the changes to take effect:
  442. $ ./bin/buildout
  443. Development eggs
  445. If there is not a release for your egg, or you want to track an egg in Subversion, check it out to the src/ directory. Make sure you get the full egg, including the top-level setup.py file. For example, to get the plone.portlets trunk development, egg do:
  447. $ cd src
  448. $ svn co https://svn.plone.org/svn/plone/plone.portlets/trunk plone.portlets
  449. Then, add the following to buildout.cfg:
  451. [buildout]
  452. ...
  453. eggs =
  454.     ...
  455.     plone.portlets
  457. develop =
  458.     src/plone.portlets
  459. Note that:
  461. The develop option contains a relative path to where the source egg is installed. Buildout will expect to find a suitable setup.py in this directory.
  462. Development eggs always take precedence over regular eggs.
  463. You still need to list the egg name  in the eggs option for it to be installed.
  464. If you are overriding an egg that ships with Plone, you may need to list it in the eggs section of the [plone] part instead:
  465. [buildout]
  466. ...
  467. develop =
  468.     src/plone.portlets
  470. ...
  472. [plone]
  473. recipe = plone.recipe.plone
  474. eggs =
  475.     plone.portlets
  476. This is because plone.recipe.plone is very expilcit about which versions of its various eggs to use, to ensure Plone keeps running as it was released.
  478. Buildout recipes (such as plone.recipe.plone) are distributed as eggs. You can use a development egg of a recipe by listing it under the develop option. There is no need to explicitly list it under the eggs option, since it is referenced by the recipe option of the relevant part.
  480. Installing a traditional Zope 2 product
  482. The easiest way to try out a traditional Zope 2 product is to extract it into the products/ folder inside the buildout. If you see documentation referring to the Products/ folder in a Zope instance, this is the same thing.
  484. However, this approach makes it harder to redistribute your project and share it with other developers. It is often more predictable to let buildout download and install the package for you. You can do this with the [productdistros] section of buildout.cfg. For example, here is how you might install a product named ExampleProduct and a set of products named ExampleProductBundle:
  486. [productdistros]
  487. recipe = plone.recipe.distros
  488. urls =
  489.     http://example.com/dist/ExampleProduct-1.0.tgz
  490.     http://example.com/dist/ExampleProductBundle-1.0.tgz
  491. nested-packages =
  492.     ExampleProductBundle-1.0.tgz
  493. version-suffix-packages =
  494. Note that our fictional ExampleProductBundle is distributed as a single directory containing a number of products in sub-directories, so we list it under nested-packages.
  496. As always, if you change buildout.cfg, you must re-run buildout:
  498. $ ./bin/buildout
  499. Managing ZCML files
  501. It is important to realize that Zope will not load configure.zcml files automatically for packages that are not in the Products.* namespace and lack support for z3c.autoinclude (see next page for more on using z3c.autoinclude). Instead, you must explicitly reference the package. Buildout can create such a reference (known as a ZCML slug) with the zcml option under the [instance] part. Here is how to ensure that borg.project is available to Zope:
  503. [buildout]
  504. ...
  505. eggs =
  506.     elementtree
  507.     borg.project
  509. ...
  511. [instance]
  512. ...
  513. zcml =
  514.     borg.project
  515. Should you need to load an overrides.zcml or a meta.zcml, you can use a syntax like:
  517. zcml =
  518.     some.package
  519.     some.package-overrides
  520.     some.package-meta
  521. Policy products
  523. Many developers prefer to create a single "policy product" (also known as a "deployment product") that orchestrates various dependencies. If you have such a product, you may want to include various dependencies directly from the policy product's configure.zcml file, with lines such as:
  525. <configure xmlns="http://namespace.zope.org/zope">
  527.     <include package="borg.project" />
  529. </configure>
  530. In this case, you may still need one slug (using the zcml option as above) for the policy product.
  532. 8. Creating a new package
  534. Adding a new custom package is not much different from installing a third-party one.
  536. Creating a traditional Zope 2 product
  538. To create a traditional Zope 2 product, put it in the top-level products/ directory and re-start Zope. Nothing more should be required. As explained previously, products placed here will be found automatically at start-up, and their configure.zcml files will be executed automatically.
  540. Creating an egg
  542. Of course, if you are using products, you cannot benefit from the additional features of eggs, including automatic dependency
  543. management, distribution via the Cheese Shop and nested namespaces.
  545. A part of this page has been removed as it contained old, inaccurate and misleading information.
  547. For usage of paster templates to create Plone add-on products please refer to this document.
  549. -Mikko
  551. Â
  553. You will now have:
  555. A setup.py which contains the metadata you entered
  556. A package in myorg.mypackage/myorg/mypackage. Your source code goes here.
  557. A skeleton configure.zcml, tests.py and a few other useful starting points.
  558. Some generic documentation in myorg.mypackage/docs.
  559. Of course, you must also add this package to the buildout. In buildout.cfg, you might have:
  561. [buildout]
  562. ...
  563. eggs =
  564.     ...
  565.     myorg.mypackage
  567. develop =
  568.     src/myorg.mypackage
  569. Unless you plan to include this package from another one (or use automatic ZCML loading, explained below), you probably also need a ZCML slug:
  571. [instance]
  572. ...
  573. zcml =
  574.     myorg.mypackage
  575. Do not forget to re-run buildout after making the change:
  577. $ ./bin/buildout
  578. Automate ZCML loading for your package
  580. If you're not including your package from another one, you can still avoid having to include a ZCML slug in buildout.cfg for it. This is particulary useful to avoid unneccessary repetition of package names in buildout.cfg, which begginer integrators might easily overlook. From Plone 3.3 on, you can make your packages signal that their ZCML should be included by adding:
  582. setup(...
  583. entry_points="""
  584. ...
  585. [z3c.autoinclude.plugin]
  586. target = plone
  587. ...)
  588. """
  589. to their setup.py file. For further information, see the setuptools documentation about dynamic discovery of services and plugins.
  591. Specifying dependencies
  593. If your new package has explicit dependencies, you can list them in setup.py. That way, buildout will be able to download and install these as well. Dependencies are listed in the install_requires argument to the setup() method, By default, setuptools is listed here, since we need this to support namespace packages. To add sqlalchemy 0.3 (but not 0.4), and the MySQL-Python driver, you could amend this to read:
  595. install_requires=[
  596.           'setuptools',
  597.           'sqlalchemy>=0.3,<0.4dev',
  598.           'MySQL-Python',
  599.       ],
  600. Uploading your egg to the Cheese Shop
  602. If you want to share your packge with the rest of the Python community and make it easy to install using tools like buildout and easy_install, you can upload the package to the Cheese Shop.
  604. Before doing so, you should:
  606. Commit your latest changes and tag the release in Subversion, if applicable.
  607. Remove (temporarily) the setup.cfg file: this makes your package a development release.
  608. Make sure the version number in setup.py is correct. This should use common conventions such as "1.0b2" for the second beta of version 1.0, or "2.1.3rc1" for the first release candidate of version 2.1.3.
  609. If you are using Mac OS X, run export COPY_EXTENDED_ATTRIBUTES_DISABLE=true on the shell first - otherwise, the egg will contain Mac OS X resource forks which cause problems if your egg is used on Windows.
  610. When you are ready, run the following command from your package's directory (e.g. src/myorg.mypackage):
  612. $ python setup.py egg_info -RDb "" sdist register upload
  613. This will ask you to create a Cheese Shop account if you do not have one already. You can run this command as often as you'd like to release a new version (probably with a new version number).
  615. 9. A deployment configuration
  617. How to use buildout for deployment configuration
  619. Finally, let's take a look at a more advanced configuration, better suited for deployment. Save this file as deployment.cfg, at the root of the buildout next to the main buildout.cfg file:
  621. [buildout]
  622. extends =
  623.     buildout.cfg
  625. parts +=
  626.     debug-instance
  627.     zeoserver
  628.     varnish-build
  629.     varnish-instance
  631. [zeoserver]
  632. recipe = plone.recipe.zope2zeoserver
  633. zope2-location = ${instance:zope2-location}
  634. zeo-address = ${instance:zeo-address}
  636. [instance]
  637. recipe = plone.recipe.zope2instance
  638. zope2-location = ${zope2:location}
  639. zeo-client = true
  640. zeo-address = 8100
  641. zodb-cache-size = 5000
  642. zeo-client-cache-size = 300MB
  643. debug-mode = off
  644. verbose-security = off
  645. eggs += Products.CacheSetup
  647. [debug-instance]
  648. recipe = collective.recipe.zope2cluster
  649. instance-clone = instance
  650. http-address = 8081
  651. debug-mode = on
  652. verbose-security = on
  654. [varnish-build]
  655. recipe = zc.recipe.cmmi
  656. url = http://downloads.sourceforge.net/varnish/varnish-2.0.2.tar.gz
  658. [varnish-instance]
  659. recipe = plone.recipe.varnish
  660. daemon = ${buildout:parts-directory}/varnish-build/sbin/varnishd
  661. bind =
  662. backends =
  663. cache-size = 1G
  664. Here, we are:
  666. Referencing the main buildout.cfg file, extending and overriding it with configuration more appropriate for deployment.
  667. Setting up a ZEO server with two client instances, instance and debug-instance (see plone.recipe.zope2zeoserver and plone.recipe.zope2instance for more details)
  668. Compiling the Varnish cache server (see plone.recipe.varnish for more details).
  669. By combining buildout configuration files like this, you can create tailor-made configurations for different deployment scenarios. To learn more about the advanced features of buildout, see its documentation.
  671. To build this environment, you must explicitly specify a configuration file:
  673. $ ./bin/buildout -c deployment.cfg
  674. To start Zope and Plone, you will need to start the ZEO server, the instance and the Varnish server:
  676. $ ./bin/zeoserver start
  677. $ ./bin/instance start
  678. $ ./bin/varnish-instance
  679. If you need to bring up an instance for debugging then you can start up the debug-instance in foreground mode.
  681. $ ./bin/debug-instance fg
  682. The recipes will also create scripts to back up the ZODB filestorage (in ./bin/repozo) and to pack the database (in ./bin/zeopack).
  684. Further options
  686. zc.buildout is a very flexible system. It is relatively easy to create new recipes, and you can combine existing recipes in powerful ways. Search the Cheese Shop for "buildout" to find more recipes, or take a look at the source code for some of Plone's own recipes to understand how recipes are created.
  690. 10. Useful buildout recipes
  692. A list of the most common and useful buildout recipes used when working with Plone.
  694. The list is more or less sorted by topic. Check all available recipes at PyPI.
  696. zc.recipe.egg - Installs eggs into a buildout eggs directory. It also generates scripts in a buildout bin directory with egg paths baked into them.
  697. infrae.subversion - This zc.buildout recipe will check out a number of URLs into its parts directory. It won't remove its parts directory if there are any changes in the checkout, so it's safe to work with that checkout for development.
  698. plone.recipe.zope2install - Installs Zope 2, i.e. its Python libraries and scripts, but doesn't create any instance.
  699. plone.recipe.zope2instance - Creates and configures a Zope 2 instance in parts. It also installs a control script, which is like zopectl, in the bin/ directory.
  700. plone.recipe.zope2zeoserver - This recipe creates and configures a Zope 2 ZEO server in parts. It also installs a control script, which is like zeoctl, in the bin/ directory.
  701. plone.recipe.distros -  Installs distributions, i.e. Zope products not packaged as eggs.
  702. plone.recipe.apache - Builds and configures the Apache web server.
  703. gocept.nginx - zc.buildout recipe for configuring an nginx server
  704. plone.recipe.varnish - Installs the Varnish reverse-cache proxy. It works for non-Zope sites as well.
  705. plone.recipe.squid - Installs the Squid proxy. It works for non-Zope sites as well.
  706. collective.recipe.omelette - Creates a unified directory structure of all namespace packages, symlinking to the actual contents, in order to ease navigation.
  707. collective.recipe.i18noverrides - Creates an i18n directory within one or more Zope 2 instances in your buildout. It copies some .po files to those directories. The translations in those .po files will override any other translations.
  708. zc.recipe.cmmi - The Configure-Make-Make-Install recipe automates installation of configure-based source distribution into buildouts.
  709. plone.recipe.command - Execute arbitrary commands in buildout through os.system.
  710. 11. Installing products from Subversion
  712. Sometimes Plone products are not eggified, but available only in Subversion version control repository. This how to tells how such product can be automatically installed in buildout installations.
  714. A few buildout recipes provide direct version control checkout functionality:
  716. plone.recipe.bundlecheckout - recipe provides Subversion (and CVS) downloads. Always does checkout - not suitable if you change files.
  717. mr.developer -  a zc.buildout extension which makes it easier to work with buildouts containing lots of packages of which you only want to develop some.
  719. infrae.subversion - can do SVN update
  720. In this example we use the later.
  722. Step by step
  724. Add the infrae.buildout recipe to your buildout.cfg. Adding a recipe means adding a new line to [buildout] parts=...myrecipename at the beginning of the file and then later a corresponding [mypartname] recipe = xxx.yyy section.
  726. [buildout]
  728. parts =
  730.     plone
  731.     zope2
  732.     productdistros
  733.     svnproducts
  734.     instance
  735.     zopepy
  736.     zopeskel
  737. List all the URLs of the products you want in suvnproducts section. In the example below we checkout TickingMachine product.
  739. # Get TickingMachine directly from SVN since it's not eggified    
  741. [svnproducts]
  742. recipe = infrae.subversion
  744. urls =
  745.     http://tickingmachine.googlecode.com/svn/trunk TickingMachine
  746. In the case you're installing an old product (not eggified) you will also need to register it in the [products] section so that they get added to your Python path:
  748. products =
  749.     ${buildout:directory}/products
  750.     ${productdistros:location}
  751.     ${plone:products}
  752.     ${svnproducts:location
  753. After rerunning buildout, TickingMachine will be found under parts/development-products folder.
  755. Further information
  757. infrae.subversion: a recipe against disaster
  758. Note that pointing to trunk is only a good practice for active development. Anyone else that needs to use this technique should point to a tag or branch URL.
  759. Certification errors and passwords
  761. Self-signed certificates are often used with Subversion repositories. Since infrae.subversion is made for automatization, it cannot accept security decisions for the user. So if you are receiving certification validation errors and password prompts, please access the Subversion repository first manually using svn command. Accept the choice and the svn client will remember this in your user account home folder. It is recommended not to use your commit account for this, since storing passwords is insecure.
  763. Here's an example about how to access a SVN repository using the svn ls command and accepting the security decisions for the svn client to remember them permanently:
  765.  svn ls   https://svn.plone.org/svn/collective/collective.easytemplate/trunk
  766. Error validating server certificate for 'https://svn.plone.org:443':
  767.  - The certificate is not issued by a trusted authority. Use the
  768.    fingerprint to validate the certificate manually!
  769. Certificate information:
  770.  - Hostname: *.plone.org
  771.  - Valid: from Mon, 14 Jan 2008 08:35:24 GMT until Wed, 13 Jan 2010 08:35:24 GMT
  772.  - Issuer: Plone Foundation, Houston, Texas, US
  773.  - Fingerprint: 39:6e:42:08:44:65:aa:7b:cb:55:85:9a:0c:0c:13:95:16:aa:38:48
  775. (R)eject, accept (t)emporarily or accept (p)ermanently? p
  777. About
  778. You are reading:
  780. Jump to:
  781. from Developer Manual.
  783. Plone Developer Manual is a comprehensive guide to Plone programming.
  785. All content on a single page
  787. Use with:
  788. Plone 4
  789. Plone 3
  790. Relevant for:
  791. Developers
  792.  Author: Israel Saeta Pérez
  793. Also contributing: Mikko Ohtamma, Martin Aspeli, Kamon Ayeva, Israel Saeta Pérez.
  794. Last modified: 959 days ago.
  795. Visit our chat rooms or support forums if you have more specific questions.
  797. You can also learn how to design, build, and deploy a website in Plone through one of the numerous Plone training sessions around the world.
  799. Report errors, omissions, etc., to the documentation by emailing plone-docs@lists.sourceforge.net
  802. The Plone® CMS/WCM is © 2000–2012 the Plone Foundation and friends. Site hosted by Six Feet Up.
  804. Plone® and the Plone logo are registered trademarks of the Plone Foundation. You’re looking good today.
  807. Get Plone
  808. Themes
  809. Development tools
  810. Authentication
  811. …and more.
  812. Documentation
  813. FAQs
  814. Tutorial videos
  815. Manuals
  816. Books
  817. Error Reference
  818. Sites using Plone
  819. Developers
  820. Roadmap
  821. Report bugs in Plone
  822. Report website issues
  823. Latest changes
  824. Browse source
  825. Contribute to Plone
  826. Community blogs
  827. Plone Foundation
  828. Donate
  829. Sponsors
  830. Meeting minutes
  831. Current board
  832. Foundation members
  833. Apply for membership
  834. Contact
  835. Support
  836. Commercial services
  837. Chat room
  838. Forums
  839. Sector-specific forums
  840. Region-specific forums
  841. Local user groups
  842. Training
RAW Paste Data