r140 - 21 Oct 2008 - 00:09:26 - LinkUpdaterYou are here: OSAF >  Developers Web  >  ChandlerDesktopSource > BuildingChandlerDesktop

How to Build Chandler

You probably don't want to be here! Go to RunningChandlerFromSourceReleases unless you are absolutely certain you should be here.

Getting Source

See ChandlerDesktopSource. It includes instructions on how to check out the source code in write mode (if you have access) - this page lists only how to get the read-only version.

The quick and easy way - download pre-built binaries

This section assumes that you're doing all your work inside the /chandler tree, that is you're coding in Python and you're not directly working with any of the code in /external (which contains code for PyLucene, M2Crypto and a bunch of other dependencies) or /internal (which contains code for wxPython, chandlerdb and some other dependencies customized for Chandler). In other words, pre-built binaries of all dependencies are sufficient to get your coding work done. Of course, your platform must be one for which we have pre-built binaries, i.e. Mac OS X PPC, Mac OS X Intel, Windows XP or Ubuntu (Dapper). For any other platform, you must jump to the long and more difficult way that'll explain how to build the binaries from source.

First, you need to get the source code from the svn repository:

  • svn co http://svn.osafoundation.org/chandler/trunk/chandler chandler
  • cd chandler

If you have Cygwin installed (or are on Linux or OS X) then the following step downloads and installs the pre-built Chandler binaries:

  • make install
OR
  • make DEBUG=1 install if you want to create a debug version of Chandler

Notes

  1. There may be a problem with GNU make 3.81 - if you get an error about too many targets for line 152 then you have run into this and need to downgrade your make to 3.80. Thanks to Jeffrey and Darshana for tracking this one down.
  2. the make install step does depend on the curl utility to retrieve the pre-built binaries from our server. Make will give you a "command not found" message if you do not have it installed.

OR if are on Windows and don't have Cygwin installed then you can work with some Subversion client to get the source and then install a minimal set of Cygwin utilities as follows:

Running Chandler

Then, start Chandler (execute from within the chandler/ directory):

  • release/RunPython Chandler.py
OR
  • debug/RunPython Chandler.py

On Windows using Cygwin you must append .bat to the file name:

  • release/RunPython.bat Chandler.py
OR
  • debug/RunPython.bat Chandler.py

Or use the launch binaries to start Chandler (they accept the same command line arguments):

  • Windows: ./chandler.exe or ./chandlerDebug.exe
  • Linux: ./chandler or ./chandlerDebug
  • OS X: no binary launcher, use the RunPython scripts as described above

Updating your source tree

Usually it would be enough to just update the chandler directory: cd chandler; svn up. Then just run Chandler as usual.

However, when something has changed outside the chandler directory (for example, we've upgraded some 3rd party library), it is usually necessary to do make install as explained above.

The long and more difficult way - build the binaries yourself

This way assumes you need to (or want to) build everything from source instead of downloading pre-built binaries for your platform.

Requirements:

  • Windows: Install Cygwin and make sure you have at least the following Cygwin packages: bash, binutils, byacc, bzip2, coreutils, curl, cygwin, gettext, gettext-devel, gzip, make, patchutils, perl, tar, and unzip. You will probably also want the package svn to do command line svn operations. Note that instead of Cygwin Perl you could use some other Perl on your system, like ActiveState's Perl. You will also need Microsoft Visual Studio .NET 2003.
    (On older Cygwin versions you may need to use sh-utils and textutils instead of coreutils which replaced them.)
  • OS X:
    • Make sure your OS X install has the latest Subversion client, at least 1.4 - if not you can download a universal binary from http://metissian.com/projects/macosx/subversion/
    • Make sure your version of Ant is 1.6.5 or above, the PyLucene build requires it
    • OS X 10.3 "Panther": Install XCode 2.3 or later Developer Tools.
    • OS X 10.4 "Tiger":
      • Install XCode 2.3 or later Developer Tools. See OS X Tiger Notes for more details.
      • Chandler depends on a newer version of GetText than ships with OS X - see BuildingGettext on how to install the latest version.
      • Intel hardware: Install XCode 2.3 or later Developer Tools. See OS X Tiger Notes for more details.
  • Linux: You may already have a compatible version of gcc if your installation uses 3.4.2 or later. See the wiki page that's relevant for your Linux distribution:

Once those requirements are fulfilled, you're now ready to buid Chandler proper. First, you need to get the full source code:

  • svn co http://svn.osafoundation.org/chandler/trunk chandler

Then build the external projects:

  • cd chandler/external
  • export BUILD_ROOT=`pwd` (yes, external is part of the BUILD_ROOT var)

Notes:

  1. Do not use any spaces in the directory where you place the Chandler source tree.
  2. Be sure to NOT include a trailing slash (/) in the directory name of the BUILD_ROOT variable (if you do not use `pwd` as suggested above). E.g., .../chandler/external not .../chandler/external/
  3. if you are building or developing in the wx source tree then you should read wxPython Notes
  4. if you are working with localizations or your environment doesn't include GNU's Gettext (or, like OS X, an older version), you can install or build it by following the instructions: BuildingGettext

At this point, your environment should be ready to be verified:

   make env

If make env didn't complain, you're ready to build everything. If you are on one of the supported platforms you can do simply:

   make world

or

   make DEBUG=1 world

If you are on some unsupported platform, things get harder (until we fix Bug:5363 ). You need to make sure that you don't accidentally download any pre-built binary tarballs that are incompatible for your platform. We need to break the world target into sub-steps:

$ make all binaries install
$ cd ../internal
$ make all binaries install
$ cd ../chandler
$ make install purge HOST=nosuchhost

The last part is the most important one. The HOST=nosuchhost makes sure that if the quick builds and full builds are out of sync, curl will fail trying to connect to the the non-existing host. You now have a couple of options:

  • If the packages that it tried to download do not contain any compiled code (for example pure Python), and that there are no incompatible API changes, you could just do the make install step without overriding HOST. Things should just work. In other words, just do: make install in the chandler dir.

  • If there are incompatible API changes, or compiled code, things get harder. You need to figure out from svn history what svn revision to downgrade to in the appropriate libraries in both external and internal, edit chandler/Makefile to the correct binary tarball versions, make realclean in all toplevel directories, and redo the build using the instructions above.

You are now ready to run Chandler as described above.

Updating your source tree

Usually it would be enough to just update the chandler directory: cd chandler; svn up. Then just run Chandler as usual.

However, when something has changed outside the Chandler directory (for example, we've upgraded some 3rd party library) it is usually necessary to update the whole tree and rebuild before you can use Chandler again. The easy way to update the whole tree is to change to the parent of the external and chandler directories and do svn up (this does assume that you have an svn working directory of the trunk). Then just follow the full build instructions above.


Top Makefile targets

Use DEBUG=1 for debug versions.

Most sub-projects depend on at least one other. Be sure to preserve the order in which they're built (listed in the SYSTEMS Makefile variable).

  • world: builds all of external and internal; Chandler will be ready to run
  • all (default): build all subsystems
  • env: check build environment
  • compilers: download and install compilers for your platform
  • binaries: create release or debug binaries for upload
  • install: installs binaries into chandler directory
  • sources: download sources and expand them into the source tree
  • clean: clean all subsystems of files generated by build tools (will not remove downloaded source tarballs)
  • realclean: return the directory to the state it was after svn checkout
  • realcleanworld: In external/ only; return the whole tree to the state it was after svn checkout

Common Makefile targets in sub-project Makefiles

Use DEBUG=1 for debug versions

  • build or all (default): build the subsystem
  • clean: clean the subsystem
  • binaries or snap: make a binary archive called release.tar.gz or debug.tar.gz of this subsystem only. This archive can be installed on top of a Chandler install for testing/debugging.
  • install: Copy the binary tarball to chandler/../downloads directory. You will need to cd chandler; make install to unpack the tarballs.
  • drop: Unpack the binary tarball directly into chandler directory, nice when working with internal/wx for example.
  • apply: apply the patches. Not all sub-projects have patches. This target is invoked during the build process.
  • expand: unpack the source packages

Some notes about external and internal

  • external needs to be built first
  • external is not expected to change often
  • the external binaries have one global version
  • internal depends on external
  • internal depends on being a directory sibling of external
  • internal systems are expected to change frequently (some of them)
  • the internal binaries have distinct versions that depend on their rate of change
  • the default version of things is the current chandler version followed by a sequence number, as in 0.3-4.
  • additional notes about BuildStructure20040512 should be read for developers used to the "old style" directory layout

When you are a developer making changes in external, you bump up the sequence number in the top Makefile, upload new sources and release and debug binaries for all three platforms and update the Makefile in the chandler directory to reflect the new version(s) of required archive(s), so that all will get the change(s) when they run make install again. When you are adding a new module to external, follow the guidelines in NewModule.

When you are a developer making changes in internal, you need external built first because internal depends on binaries in external (such as python for example), you bump up the sequence number in the system(s) you've been working on, upload release and debug binaries for all three platforms and update the Makefile in chandler to reflect the new version(s), so that all will get the change(s) when they run make install again. As an example, here are some notes about updating Twisted.

Of course, in both cases, you only commit changes and upload binaries once you are ready to release your changes. Until then, you build binaries locally and use the "make install" target in external for your own testing purposes. In each external and internal subdirectory there is a make target called 'binaries' provided for that purpose.

Tracking down a faulty revision

The problem: You know a thing broke sometime in the last few months, and you want to know the exact checkin that did it.

Solution: Pull some revision far enough back that you know worked. Test that it works. Then do the following loop to track down the faulty revision:

  1. Pull a clean tree
  2. svn up -r XXXX
  3. make world
  4. test
  5. make realcleanworld
  6. continue from 2.

Troubleshoot

  • Problem: After doing an svn update Chandler fails to start or has strange errors or I don't see the expected changes.
    • Possible Answer 1: do make clean install purge and try again.
    • Possible Answer 2: If previous answer did not help, try starting Chandler with the --create command line option.

External Libraries that Chandler depends on

Library Version Our Version Patched? URL Owner Notes
python 2.5.1 2.5.1 Yes http://www.python.org/ Bear  
bdb 4.5.20 4.5.20 No http://www.sleepycat.com/ Andi  
icu 3.6 3.6 No http://www.icu-project.org/ Andi  
openssl 0.9.8d 0.9.8d Yes http://www.openssl.org/ Heikki Patched only for build purposes. OS X and Windows only. Chandler works with 0.9.7 or later.
m2crypto 0.17 0.17 Yes http://websvn.osafoundation.org/m2crypto Heikki Patched only for build purposes.
setuptools 0.6c6 0.6c6 No http://peak.telecommunity.com/DevCenter/setuptools Bear  
twisted 2.4 2.4 r18795 No http://twistedmatrix.com Bear  
zope interfaces 3.3.0b2 3.3.0b2 No http://www.zope.org/Products/ZopeInterface Bear  
pyicu 0.6 0.6 r76 No http://websvn.osafoundation.org/pyicu/ Andi  
pylucene 2.1.0 2.1.0-2 Yes http://websvn.osafoundation.org/pylucene/ Andi  
openjdk 7-ea-j2re-b21 7-ea-j2re-b21 No   Andi  
vobject 0.4.8 0.4.8 r186 No http://vobject.skyhouseconsulting.com Jeffrey  
zanshin r163 r163 No http://websvn.osafoundation.org/zanshin/ Grant  
dateutil 1.1 1.1 No http://labix.org/python-dateutil Bear  
parsedatetime 0.8.4 0.8.4 No http://code-bear.com/code/parsedatetime/ Bear  
wxpython 2.8.4.1 2.8.4.1-r177 Yes http://wxpython.org/ Robin  
configobj 4.3.2 4.3.2 No http://www.voidspace.org.uk/python/configobj.html Bear  
readline 5.2 5.2 No http://cnswww.cns.cwru.edu/php/chet/readline/rltop.html Bear Used only for the Python build on OS X and Windows and not included in the distribution
swig 1.3.29 1.3.29 Yes http://www.swig.org/ Bear  
zlib 1.2.3 1.2.3 No http://www.zlib.net/ Bear Used only for the Python build on the windows platform

External Libraries included in Chandler for support or for developer tools

Library Version Our Version Patched? URL Owner Notes
pychecker 0.8.17 0.8.17 No http://pychecker.sourceforge.net/ Bear  
pylint 0.13.1 0.12.2 No http://www.logilab.org/projects/pylint Heikki  
logilab-common 0.21.2 0.21.0 No   Heikki pylint sub-project
logilab-astng 0.17 0.16.3 No   Heikki pylint sub-project
epydoc 3.0beta1 3.0beta1 Yes http://epydoc.sourceforge.net/ Bear our version has patched it to include a exclude option that is no longer needed

Deprecated Libraries

Library Removed Version Our Version Patched? URL Owner Notes
elementtree Chandler 0.7 1.2.6 1.2.6 No http://effbot.org/zone/element-index.htm Bear  
libxml2 Chandler 0.7 2.6.23 2.6.16 Yes http://xmlsoft.org/ Bear  
soappy Chandler 0.7 0.12.0 0.10.2 Yes http://pywebsvcs.sourceforge.net/ Bear we cannot use the current version as it depends on fpconst which does not appear in Apple's Python. See PEP 754 and http://mail.python.org/pipermail/pythonmac-sig/2005-January/012577.html
jabberpy Chandler 0.7 0.5 0.4 Yes http://jabberpy.sourceforge.net/ Bear jabberpy seems to be no longer managed and the 0.5 version has a bug in the install process that prevents it from being a python module - need to review
Edit | WYSIWYG | Attach | Printable | Raw View | Backlinks: Web, All Webs | History: r140 < r139 < r138 < r137 < r136 | More topic actions
 
Open Source Applications Foundation
Except where otherwise noted, this site and its content are licensed by OSAF under an Creative Commons License, Attribution Only 3.0.
See list of page contributors for attributions.