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

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

• 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:

• download http://builds.osafoundation.org/external/windows/mincyg.zip into the chandler directory (where you should normally be already)
• unzip mincyg.zip
• installWin install (or installWin DEBUG=1 install)

Running Chandler

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

• release/RunPython Chandler.py

• debug/RunPython Chandler.py

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

• release/RunPython.bat Chandler.py

• 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:
  • Debian and Ubuntu Notes
  • Fedora Core Notes
  • Gentoo Notes
  • Building in a 32-bit chroot on x86_64

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

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

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

External Libraries included in Chandler for support or for developer tools

Deprecated Libraries