Current

This document is valid for the current version of Plone.

Using buildout on Windows

by Hanno Schlichting — last modified Nov 16, 2012 03:10 PM
Detailed explanation on what to do to get a buildout development environment running with a Plone / Zope on Windows.

Please note: as of Plone 3.2, a Windows installer based on buildout is available. If you're new to Plone and/or new to developing Plone on Windows, it is highly recommended that you download the Windows installer for ease of installation and setup. Additional start up notes are also available.

Introduction

In order to get a working buildout based development environment for Plone on Windows you will need a solid, fast internet connection as you will be downloading several hundreds of megabytes the first time. This how-to will outline all the steps you need to take to go from a fresh Windows 7 (other Windows versions should work the same or similar) to a full buildout environment. If you already have some of the tools described here installed, you can skip the relevant sections. However, make sure you read them nonetheless so you are certain that you have indeed taken all the necessary steps.

Assumptions

This document assumes you have a good working knowledge of Windows (comfortable starting up and using a DOS command window, installing new software, etc) and at least passing familiarity with Plone. If you're not planning on doing serious software development within the Plone environment, then you will want to use the Windows installer to install Plone. These instructions document checking out and installing a core-development version of Plone.

Python 2.6.6

(http://www.python.org/)

  1. Download and install Python 2.6.6 using the Windows installer from http://www.python.org/ftp/python/2.6.6/python-2.6.6.msi
  2. Select 'Install for all users' and it will put Python into the"C:\Python26" folder by default.
  3. You also want the pywin32 extensions available from http://sourceforge.net/projects/pywin32/files/pywin32/Build%20214/pywin32-214.win32-py2.6.exe/download
  4. And as a last step you want to download the Python imaging library available from http://effbot.org/media/downloads/PIL-1.1.6.win32-py2.6.exe
  5. If you develop Zope based applications you will usually only need Python 2.6 so it's easiest to put the Python binary on the systems PATH, so you don't need to specify its location manually each time you call it. 

    So, put "C:\Python26" and "C:\Python26\Scripts" onto the PATH.

    You can find the PATH definition via the Windows Control Panel; next, double click on the System icon and then click on the Advanced tab. At the bottom, there is button is called "Environment Variables", click that. You should now see something like this:

system properties

You want to edit the Path variable and add the two Python paths at the end of the already existing PATH. Note that each path is separated by a semicolon:

%SystemRoot%\system32;%SystemRoot%;C:\Program Files\QuickTime\QTSystem\;C:\Python26;C:\Python26\Scripts

You can test if this was successful by opening a new shell (cmd). Note: Opening a new shell can be done quickly by using the key combination 'Windows-r' or if you are using Parallels on a Mac 'Apple-r'. Type in 'cmd' into the popup box that opens up and hit enter.

Next enter:

python -V

It should report version 2.6.6 (or whichever version you installed).

Subversion

(http://subversion.tigris.org)

Since you will be getting the latest source code from SVN, you'll need a Subversion client.

  1. Download the nice installer from: http://www.collab.net/downloads/subversion/. At the time of writing this the latest installer is called "CollabNet Subversion Command-Line Client v1.6.12 (for Windows)". Any version from the 1.6.x line should work, Subversion 1.7.x is not yet supported.

  2. Run the installer. It defaults to installing into "C:\Program Files\Subversion".

  3. Now put the install locations bin subfolder (for example "C:\Program Files\Subversion\bin") in your system PATH in the same way you put Python in it.

  4. Open a new shell again and type in:

    svn --version

    It should report version 1.6.12 or newer.

Git

For Plone version 4.2, Git is also required. It can be downloaded from http://git-scm.com/download/win.

MinGW

(http://www.mingw.org/)

Note: With Plone 4 there is almost never a need for having a C compiler installed anymore. We provide binary packages for all required software. So skip this step unless you want to develop any of the core packages including C extensions.

Also note that this will install 32bit versions of the entire stack. It's possible to use 64bit versions, but you will need the official Visual Studio 2008 Express and Windows platform SDK instead of MingW in that case.

Download the MinGW installer from http://downloads.sourceforge.net/mingw/MinGW-5.1.4.exe

  1. The installer will ask you which options you would like to install. Choose "base" and "make" here. It will install into "C:\MinGW" by default. The install might take some time as it's getting files from sourceforge.net and you might need to hit 'retry' a couple of times.
  2. Make sure to copy "cc1.exe" and "collect2.exe" from the "C:\MinGW\libexec\gcc\mingw32\3.4.5" folder to the "C:\MinGW\bin" folder.
  3. Now put the install location's bin subfolder (for example "C:\MinGW\bin") in your system PATH in the same way you put Python in it.
  4. Test this again by opening a new shell and type in: 
    gcc --version
    It should report version 3.4.5 or newer.
  5. The WinGW installer downloads several files and places them in the same location from which the installer is run (i.e., if you run the installer from your Desktop, this is where the files will end up). After the installation is finished all these files can be safely deleted.
  6. If your Python distribution does not come with libpython26.a or similar (MingW version of Python library) you need to create it using pexports utility or the compiler will fail in the linking phase
  7. If you use Python from Plone Windows installer, you need to copy file Plone\Python\PC\pyconfig.h to Plone\Python\Include

Configure Distutils to use MinGW

Some general information is available on Python Extensions as an example but you don't need to read them all. The following steps are the most often mis-applied so follow along carefully:

  1. Create a file called 'distutils.cfg' in "C:\Python26\Lib\distutils".
  2. Open it with a text editor ('notepad distutils.cfg') and fill in the following lines:
    [build]
compiler=mingw32
  3. Save the file.

What this does:

This will tell distutils to use MinGW as the default compiler, so you don't need to specify it manually using "--compiler=mingw32" while calling a package's setup.py with a command that involves building C extensions. This is extremely useful if the build command is written down in a buildout recipe where you cannot change the options without hacking the recipe itself.

This is also the one area that will cause the most problems if you have numerous other developer tools or compilers installed.

Get your buildout

We will explain the general procedure using the plone-coredev buildout as an example. This buildout configuration is only suitable for developing Plone itself. If you want to do your own projects refer to the appropriate documentation.

  1. Create a new folder (for example, "C:\plone"). This will contain the development environment and will need at least 300mb of free disk space.
  2. Open a shell (cmd) and go into that folder (cd c:\plone).
  3. Checkout the buildout configuration:
    svn co https://svn.plone.org/svn/plone/buildouts/plone-coredev/branches/4.0 plone
    You will see a number of messages scroll by:
    A    plone\README.txt
A    plone\bootstrap.py
A    plone\buildout.cfg
[...]
    This step will be quite quick to complete. You'll know this step is completed when you see something like:
    Updated to revision 34567.
    (Note: you will see a different revision number!)
  4. If your connection gets interrupted you can resume the checkout by using: 
    svn up plone

Bootstrap buildout

  1. Change into the "check out" folder ('cd plone') and run:
    python2.6 bootstrap.py
    This will create a few folders and download zc.buildout and setuptools from the Python Package Index. You will see something like:
    Downloading http://pypi.python.org/packages/2.6/s/setuptools/setuptools-0.6c11-py2.6.egg
Creating directory 'C:\\Plone\\plone\\bin'.
Creating directory 'C:\\Plone\\plone\\parts'.
Creating directory 'C:\\Plone\\plone\\eggs'.
Creating directory 'C:\\Plone\\plone\\develop-eggs'.
Generated script 'C:\\Plone\\plone\\bin\\buildout'.
  2. Now type: 
    bin\buildout -v
    which will checkout some code, download a few zip files and configure your environment. This will take quite some time the first time you run it. You should see something like:
    Installing 'zc.buildout', 'setuptools'.
We have the best distribution that satisfies 'zc.buildout'.
Picked: zc.buildout = 1.4.4
We have the best distribution that satisfies 'setuptools'.
Picked: setuptools = 0.6c11
[...]
Installing 'plone.recipe.zope2instance'.
We have no distributions for plone.recipe.zope2instance that satisfies 'plone.recipe.zope2instance'.
Getting distribution for 'plone.recipe.zope2instance'.
Got plone.recipe.zope2instance 4.0.3.
Picked: plone.recipe.zope2instance = 4.0.3

[... lots and lots and lots of lines ... then finally near the end ...]

Generated interpreter 'C:\\Plone\\plone\\bin\\zopepy'.
    Note: buildout has a number of additional options.
  3. Congratulations! You now have a working environment, built from the latest source!

Check the README.txt

Since you've checked out the latest source, it will be important to check the README.txt that comes with the checkout. Trunk is a moving target and there's likely to be vital information here.

Adding an administrative user

The core checkout build may not automatically add an administrative user. You'll need to do that yourself, using the command:

bin\instance adduser username password

Starting Plone

You start up Zope with Plone from the same directory ("C:\plone\plone") with the following:

bin\instance console

Or if you want to start Plone in debug mode and see the console output

bin\instance fg

If you have used Plone Windows installer before you might get error

  File "C:\Plone\parts\zope2\lib\python\ZODB\lock_file.py", line 33, in lock_file
    _LockFile(file.fileno(), 0, 0, 1, 0)
winlock.error: 33

This simply means that ZODB database (Data.fs) is locked for another Plone process - usually one started automatically during Windows start up. Use Plone control panel from Start menu to shutdown this Plone instance or kill it through Task Manager (you need to click Show processes for all users in Task Manager and kill Python.exe).

Updating from SVN

Periodically, you will want to "svn up" -- that is, get the latest source from trunk.

  1. Stop Zope. This can be done via the Control Panel in the ZMI
  2. Open a shell (cmd) and change into your top level Plone folder ('cd c:\plone')
  3. Update with:
    svn up plone
  4. Then:
    cd plone
bin\buildout -v
  5. Restart Zope and Plone as before with:
    bin\instance fg

Don't forget to migrate your existing Plone instances! (Force migration to the last item in the dropdown list from portal_migration.

Happy Developing!


Contribute

Something wrong or out of date? Anybody can edit or create a new article in the knowledge base. Simply create an account on this site, log in, and click the Edit button to contribute.