How it works...

Buildout works by processing a configuration file, which is called buildout.cfg by default. This file uses a syntax close to ConfigParser (with a few extensions) to describe the desired target environment. There is one mandatory section, [buildout], which contains a parts entry listing the sections to process. Most sections have a recipe entry that gives the name of a buildout recipe to use to build the section. There are lots of recipes available (take a look at http://www.buildout.org/en/latest/docs/recipelist.html for a partial listing), and different recipes can be combined in a single configuration file. Each recipe supports its own configuration settings. Recipes are Python modules, usually made available from PyPI.

Buildout configuration files are extensible and support parameterization:

• A configuration file can extend another one; configuration settings are added or overwritten by the extending file.
• Configuration settings can refer to the value of other settings using the ${section:name} syntax.
• In step 1, we prepare our base buildout.cfg configuration file. We define a section called [odoo] and set the anybox.recipe.odoo parameter as the buildout recipe in charge for this section. Here are the settings we use:
  • version: This defines the Odoo version we want. Here, we are using the latest version from the 9.0 branch on GitHub. The depth options limit the Git clone depth to speed up the installation.
  • OCA: This is a custom setting used to simplify the URLs of the OCA addons we are listing in the following settings, using the ${odoo:OCA} variable.
  • addons: This lists the addons directories to install, one by one. The syntax is protocol URL destination revision options. The Git protocol will use Git to clone a repository. The local protocol will use a local directory (and revision must not be provided in this case). Other available protocols are hg (for mercurial repositories), svn (subversion), bzr (bazaar). The revision can be a tag, a branch, or a commit identifier.

The [versions] section is a standardized buildout section used to specify the versions of the Python dependencies that will be installed in the environment. It is important to fix the version of zc.buildout, anybox.buildout.odoo, and setuptools in this section to ensure the repeatability of the build, which is what we do in the first two lines of the section. The anybox.buildout.odoo recipe is able to find the names of the dependencies from the Odoo server version, but not the versions. To generate this list, we copied the requirements.txt file for the Odoo codebase and replaced the == operator with =.

As we write this chapter, the adaptation of anybox.recipe.odoo to work with Python3 and Odoo 11.0 are not finalized. We are therefore unable to suggest a version number which will be compatible; you will need to check the documentation.

The prod.cfg and dev.cfg files extend the base configuration defined in buildout.cfg. In the [odoo] section, they both define settings with names starting with options. (Mind the dot): buildout will use these when generating a configuration file for the instance with the options set as specified in the configuration file. If you've read the recipe Adapting the configuration file for production in this chapter, the prod.cfg file should be familiar.

In order to ensure that the buildout environment is insulated from the system Python, we use a virtualenv (called sandbox in this recipe) configured to not have setuptools available. We use this virtualenv to run the bootstrap.py script that we downloaded from the buildout source code repository. The role of bootstrap.py is to prepare things for buildout to work, including installing buildout itself. A script, bin/buildout, is created in the directory of the build to run buildout.

You can then manage your buildout configuration in a version management system such as Git. It is recommended that you store the bootstrap.py file together with the buildout configuration file; this file evolves with buildout, and since we are freezing the version of buildout in the configuration file, we need to keep the bootstrap.py file that we know will work with this version.

To run buildout, just execute the bin/buildout script with the -c option to specify a configuration file. This will do several things:

• Odoo gets installed in the parts/ subdirectory
• The specified addons are installed in the specified subdirectory (we recommend that you use parts/ for this too)
• The dependencies of Odoo and any additional dependencies are installed in the eggs/ subdirectory
• A configuration file is created in etc/odoo.cfg with the appropriate value for addons_path and all the options specified in the buildout configurations
• A helper script bin/start_odoo is created; it uses the generated configuration file and the installed Python dependencies