Using a tarball
Getting the latest version of the source code using Subversion
Each one brings a different value to the users of the project and it is important to understand the contribution made by each.
Once you have read this chapter, you should be able to retrieve and deploy CherryPy, as well as understand how to use each technique for your own software.
Python 2.4 or above
We will also assume you have knowledge of Python itself as we will not cover the language.
Installing a Python module or package is usually an easy process. First let's discuss the most common way to build and install a new package, thanks to a standard module, distutils, which appeared with Python 2.0.
This module provides a clean interface for specifying how a package is structured, what are the required dependencies, and the building rules of the package. For the user, it usually means typing the following commands:
python setup.py build python setup.py install
The first one will simply build the package against the rules defined by the developers, reporting errors so that the end user knows about a missing dependency for example. The second one will install the package in the default directory used by Python to store third-party packages or modules. Note that the latter command will call the former by default to quickly check that nothing has changed since the last run.
On UNIX or Linux
On Microsoft Windows
C:\Python or C:\Python2x
On UNIX or Linux it will depend how your Python installation has been deployed, but the directories given above are the most common. When importing a module, Python will look into a list of directories, some defaults and others provided by the user, until it finds a matching module or else an exception will be raised. The searched list can be modified either by defining the
PYTHONPATH environment variable or by amending it from the code itself as follows:
import sys sys.path.append(path)
PYTHONPATH environment variable is one of the variables read by the Python engine when it is being launched. It contains additional paths to append to the searched list of paths for third-party modules and packages.
Another method is to set a file named after the package with the
.pth extension. This file should contain the full path of the package.
Notwithstanding its simplicity, this algorithm has its limitations. Since the
sys.path list is ordered you have to make sure that if two paths contain the same module with different versions, the one your application imports is the first one to be reached. This leads us to the following package versioning problem.
Imagine that you install CherryPy 2.2.1 in your global installation of Python; it would be available under the directory
/usr/local/lib/site-packages/cherrypy. However, the path does not contain the version information of the package. Therefore, if you must install CherryPy 3.0.0 as well, you have to overwrite the existing installation.
Luckily the Python community has come up with a solution to this problem—eggs. An egg is a compressed folder containing all the files and sub-folders of a package with the version details of the package in its name.
An egg is a distributable bundle, by default zipped, of a Python package or module including information such as the author and the version of the package.
For example, CherryPy 2.2.1 built by Python 2.4 would look like the following:
Cherrypy-2.2.1-py2.4.egg. An egg by itself is not very useful; its deployment requires easy_install, a Python module that contains the logic for handling eggs. This means you can have multiple versions deployed in the same directory and leave it up to easy_install to decide which one to load.
In the next sections we will see in detail how to install CherryPy using the most common cases.
Historically the compression used has usually been
gzip and the extension of a tarball is either
CherryPy provides a tarball for each release whether it is alpha, beta, release candidate, or stable. They can all be retrieved from http://download.cherrypy.org/.
CherryPy tarballs contain the complete source code of the library.
To install CherryPy from a tarball you need to go through the following steps:
1. Download the version that interests you from http://download.cherrypy.org/.
2. Go to the directory where the tarball has been downloaded and uncompress it:
If you are using Linux, type the following command:
tar zxvf cherrypy-x.y.z.tgz
In the given command,
x.y.zis the version you have fetched.
If you are running Microsoft Windows, you can use a utility such as 7-Zip to uncompress the archive via a graphical interface.
3. Move to the newly created directory and enter the following command, which will build CherryPy:
python setup.py build
4. Finally, in order to do a global installation you have to issue the following command (you will more than likely need administrator permissions):
python setup.py install
Note that these commands will have to be issued from a command line. Under Microsoft Windows you will run those from a DOS command prompt
The above steps will perform a global installation of CherryPy on your system for the default Python environment. There are cases where this is not suitable or not possible. For example, you may want to install CherryPy only for a given version of Python; in that case you will have to specify the correct Python binary such as
python2.4 in steps 3 and 4 mentioned earlier.
python setup.py install --home=~
This will put the files in
$HOME represents your home directory.
python setup.py install --prefix=c:\some\path
The path you choose is not important in itself and you can use whatever suits your environment.
Then you will have to make sure Python goes through that directory when you need to import modules. The easiest way is to set the
PYTHONPATH environment variable to the following:
On Linux using a bash shell
On Microsoft Windows using a command prompt
On MacOS using a
setenv PYTHONPATH "/some/path/"
PYTHONPATH environment variable will be read at startup by the Python interpreter, which will append it to its internal system path.
Easy_install is a Python module that can be found on the Python Enterprise Application Kit (PEAK) website to facilitate the deployment of Python packages and modules. From the developer's point of view, it provides an easy API to import Python modules either for a given version or a range of versions. For instance, here is what you would do to load the first CherryPy version greater than 2.2 found in your environment:
>>> from pkg_resources import require >>> require("cherrypy>=2.2") [CherryPy 2.2.1 (/home/sylvain/lib/python/ CherryPy-2.2.1-py2.4.egg)]
From the user's point of view it simplifies the procedure of downloading, building, and deploying Python products.
Before installing CherryPy, we must install
easy_install itself. Download the
ez_setup.py module from http://peak.telecommunity.com/dist/ez_setup.py and run it as follows, as a user with administrative rights on the computer:
If you do not have administrator permission, you can use the
-install-dir (-d) option as follows:
python ez_setup.py -install-dir=/some/path
Make sure that
/some/path is part of the Python system path. You can set
PYTHONPATH to that directory for example.
This will set up your environment to support easy_install. Then to install a Python product that supports easy_install, you should issue the following command:
easy_install will search the Python Package Index (PyPI) to find the given product. PyPI is a centralized repository of information about Python products.
In order to deploy the latest available version of CherryPy, you should then issue the following command:
easy_install will then download CherryPy, build, and install it globally to your Python environment. If you prefer installing it in a specific location, you will have to enter the following command:
Once installed, you will have a file named
cherrypy.x.y.z-py2.4.egg depending on the latest version of CherryPy.
The basic principle of such systems is to register a resource and then keep track of every change made to it, so that any developer can retrieve any previous version, compare two versions, or even follow the evolution over time of the said resource. A resource can be a source code file, a binary, an image, documentation, or anything that is expressible in machine-readable form.
Subversion is centralized, so a project is managed by a subversion server and each client has a copy of it. The developer works on that copy and commits back any changes he or she has made. When a conflict arises, for instance, if another developer has modified the same file and has committed it already, the server will let you know and forbid your commit until you resolve the issue.
Subversion is often viewed as the successor of CVS and is considered much friendlier. However, other revision systems also exist such as Monotone or Darcs.
Under Linux, you can either install Subversion from its sources or using a package manager. Let's describe the procedure for the source code.
1. Get the latest tarball from http://subversion.tigris.org/
2. Then type the following command in the command console:
tar zxvf subversion-x.y.z.tar.gz
3. Enter the newly created directory and type:
4. Then to build the package itself type:
5. You might later need the Python binding for Subversion as well:
6. To install Subversion globally, you will need to be the administrator and then enter:
make install; make install-swig-py
Most of the time, under Linux or UNIX, it is easier to use Subversion through the command line. However, if you prefer to use a graphical interface, I would advise you to install a fat client application such as eSvn or kdesvn.
Getting CherryPy using Subversion is recommended in the following situations:
A feature exists or a bug has been fixed and is only available in code under development.
You decide to work on CherryPy itself.
You need to branch from the main trunk in order to try and see a feature, a new design, or simply backport bug fixing in a previous release.
In order to use the most recent version of the project, you will first need to check out the trunk folder found on the Subversion repository. Enter the following command from a shell:
svn co http://svn.cherrypy.org/trunk cherrypy
Under Microsoft Windows you can do this from a command line or simply use TortoiseSVN. Please refer to its documentation for more information.
This will create a
cherrypy directory and download the complete source code into it. As it is usually not recommended to deploy globally a version under development; you would type the following command to install CherryPy into a local directory:
Under Linux and related systems using a console:
python setup.py install --home=~
Under Microsoft Windows using the command prompt:
python setup.py install --prefix=c:\some\path
Then simply point the
PYTHONPATH environment variable to the chosen directory.
>>> import cherrypy >>> cherrypy.__version__ '3.0.0'
If you do not install CherryPy globally to your Python environment, do not forget to set the
PYTHONPATH environment variable, else you will get an error as follows:
>>> import cherrypy Traceback (most recent call last): File "<stdin>", line 1, in ? ImportError: No module named cherrypy
Installed using a tarball
Usually the cleanest way to ensure the update goes smoothly is to first remove the directory containing the package from its location in
sys.path, then to follow the steps described previously to install the library.
Installed using easy_install
Updating is one of the key features provided by easy_install.
easy_install -U cherrypy
As the eggs containing the library are named after the version they serve, you can simply follow the steps defined in the previous section without removing an existing egg. Be careful though, as this only holds true when the application running specifies precisely which version it requires.
Installed using Subversion
The interesting aspect of this approach is that you can update the library almost continuously. To update your installation, you need to enter
svnupdate from the top directory holding the source code and then issue the
python setup.py installcommand.
We have discussed in this chapter the different ways of installing CherryPy in your environment via three techniques. The traditional approach is to use an archive containing all the files of the Python package to install and use the
setup.py module within that archive. A newer and more common way of deploying a package is to use the
easy_install command to install eggs. Finally, if you wish to be synchronized with the latest development of CherryPy, you can get the package from its Subversion repository. Whichever method you follow, they will all lead to CherryPy being available on your system.