About this document

This document describes how to build (compile) the EDEN software. EDEN was originally written for the UNIX platform, and then ported to Windows and Mac OS X later. Because of this history, we use a UNIX-style build process on all platforms: we don't use an IDE (eg Visual Studio or Xcode). It would certainly be possible to use such tools, but these instructions don't describe how. When special instructions are necessary for a particular platform, they are marked in a coloured box, as below.

[ashley@joshua ~]$ uname -a
Linux joshua 2.6.18-164.6.1.el5PAE #1 SMP Tue Oct 27 11:46:58 EDT 2009 i686 i686 i386 GNU/Linux

Why document this process carefully, and in such detail? Because it is a tricky process (actually, setting up the build environment can be a more difficult job than fixing bugs in the code itself) and mistakes can introduce bugs. We have very limited resources for bug fixing, and it is probably better to spend time on fixing bugs in the code rather than in the build process...

Why isn't this documentation a part of the source? That's a tricky decision: if this doc were a part of the source, it would be under version control and it would be clear who had updated it and when (and so also exactly what version of the source it applies to). However, if it isn't part of the source, then it can be edited (perhaps by people who don't have commit access to the source), and those edits don't change the source version numbers.

Install development environment

Get the EDEN source code

You can get the source code in a few possible ways:

• Our Subversion repository. This stores the most up-to-date version of the EDEN source code: see our Using Subversion document. This repository will sometimes contain code that is as-yet unreleased. If you are planning to make changes to the code, then this is probably the best place to get the code. See the other document for more details about how to check code out and in, but briefly, to check out the EDEN "trunk" directory from our "EDEN-recent" svn into the current directory, you could use:

$ svn checkout svn://emsvn.dcs.warwick.ac.uk/EDEN-recent/trunk

• A tarball archive on our website. Sometimes we make code available this way on the EDEN downloads page. This is an archive of the source code used to build a particular release. If you just want to build the software for your platform, this might be easier than using Subversion (because downloading a tarball is a little easier than checking out from Subversion if you don't already know how to do that, and also because the tarball archive should already contain the generated 'configure' script - more details below).
• Copy the source from a friend, sneaker net, OCR scan old code etc etc... !

I assume in these instructions (and some of the 'band-aid configure scripts do too) that you are keeping the source in a directory named 'trunk', within a directory named 'EDEN-recent'. Ie, like this:

EDEN-recent/

trunk/

configure script, Eden directory etc

Install bison

We use the 'bison' software to generate code for some of the various parsers within EDEN. For example, Eden/yacc.c is generated by bison from Eden/yacc.y (the files are named 'yacc' because they were originally written to be compiled by the "Yet Another Compiler Compiler", for which bison is a compatible replacement). Unfortunately we can't use the current versions of bison at the moment, since we are using a "bison.simple" feature which was removed from bison at some point. We have found bison 1.28 to work OK (and 1.27 seems OK as well). Note that the source for bison was added to our SVN in r200, but it was removed again in r248, since no modifications to it are required to use it with EDEN. (Perhaps it should be stored in SVN as an 'external' - but this is for another day.)

If your copy of the source code already includes the bison-generated source code (eg Eden/yacc.c), then you don't need to install bison and create these files again - unless you want to make some changes to the Eden notation itself. However, it is unlikely that your code of the source will include these files, unless you (eg) copy it from a friend.

If you need it:

• Download the bison-1.28 source from http://www.gnu.org/software/bison/
  
• $ tar xvf bison-1.28.tar.gz
  
• $ cd bison-1.28
  
• $ ./configure
  
• $ make
  
• $ cd ..
  

• Arrange the bison and EDEN source into directories like this:
  

bison-1.28/

configure script, src directory etc

EDEN-recent/

trunk/

configure script, Eden directory etc

Compile pcre

EDEN uses the "Perl Compatible Regular Expressions" library for the Eden regmatch and regreplace pre-defined procedures (and possibly elsewhere, but I believe this is the extent of it). The source for this is included in our SVN, I believe because some changes were necessary.

We only need to compile the file pcre.o.

• $ cd EDEN-recent/trunk/pcre-3.9
  
• $ make distclean; rm -rf RunTest dftables dftables.dSYM .libs
  (This step is only necessary if you are starting with a source directory that you have copied from another system: if you start with a clean copy of the source from SVN, this isn't necessary.)
• $ ./configure
  
• $ make pcre.o

Install some X11 headers (only necessary on Windows)

Build an EDEN icon object file (only necessary on Windows)

Generate the configure script

The EDEN build system uses the GNU autoconf macros to produce a shell script named 'configure' from a file 'configure.in'. When the 'configure' script is run, it attempts to guess & test the existence and location of various libraries used by EDEN. It produces various Makefiles and a header file called config.h. Sadly this system isn't working too well for EDEN, and various 'band-aid' shell scripts (which have names ending in .configure) have been added in order to assist 'configure' with its guessing (eg the 'dcs-linux-i686.configure' script). In Ashley's opinion, ideally we'd replace these band-aid scripts, configure.in and configure with simpler Makefiles: have some configuration-information-only Makefiles, one for each platform, similar to the current band-aid scripts, which then call the main Makefiles. Some time in the future, perhaps...

Your copy of the source may already have the 'configure' script (eg if you got the source from a tarball archive), in which case, you shouldn't need to do this step to regenerate it. The 'configure' script itself isn't checked in to SVN, since it is generated source. If you do need to generate the 'configure' script:

• $ cd EDEN-recent/trunk/
• $ autoconf
  

Run the configure script, perhaps via a 'band-aid' script

...
configure: creating ./config.status
config.status: creating generic.mk
config.status: creating Misc/Makefile
config.status: creating Eden/Makefile
config.status: creating EX/Makefile
config.status: creating Scout/Makefile
config.status: creating Makefile
config.status: creating Donald/Makefile
config.status: creating LSD/Makefile
config.status: creating Sasami/Makefile
config.status: creating config.h
configure: WARNING: Could not locate GL - probably cannot build Sasami
configure: WARNING: Type 'make' for further instructions

...
configure: creating ./config.status
config.status: creating generic.mk
config.status: creating Misc/Makefile
config.status: creating Eden/Makefile
config.status: creating EX/Makefile
config.status: creating Scout/Makefile
config.status: creating Makefile
config.status: creating Donald/Makefile
config.status: creating LSD/Makefile
config.status: creating Sasami/Makefile
config.status: creating config.h
configure: WARNING: Could not locate GL - probably cannot build Sasami
configure: WARNING: Could not locate PNG - probably cannot build Sasami
configure: WARNING: Type 'make' for further instructions

Check the output of the configure script

If you see errors, here are some hints about how you might proceed:

• Note that it is expected currently that the configure outputs include some errors about Sasami. Sasami is a notation which can be used to generate 3D graphics in tkeden using OpenGL. Unfortunately it is partly based on an open source Tk widget called 'Togl', and we are having difficulties with this on the Mac at the moment. Therefore, Sasami is disabled in all the present releases (via the '--enable-disable-sasami' option to configure).
  
• If you get errors from configure which don't mention Sasami (eg "WARNING: Could not locate curses"), then there is some difference between your machine and the test machine, or there is a mistake in these instructions etc. :( It is worth trying to build EDEN anyway, but you will probably come across an issue. :(
• If you get an error "Cached system name does not agree with actual", do "rm config.cache" and then run the configure script again.
  
• Have a look at the 'config.log' file to see the tests that 'configure' ran and the errors that were encountered.
• The configure script can be given some options to give it hints about where to look for libraries etc. The command './configure --help' shows the available options. Note that many of the options are provided as standard by GNU autoconf. The options specific to EDEN are listed starting in the "Optional Features" section. An example of using some of these options is: ./configure --with-tk-include="-I/usr/local/include" --with-tk-lib="-L/usr/local/lib -R/usr/local/lib -ltk8.2"

Build and test ttyeden

ttyeden is a terminal-based version of EDEN. It doesn't have a graphical interface, but it can be good for trying out some quick tests of the Eden language. Also, if tkeden doesn't build for some reason, it can be a good idea to building ttyeden: in some ways it is simpler (it doesn't use Tcl/Tk)... but in other ways it isn't (it uses the curses library to handle the terminal).

• $ cd EDEN-recent/trunk/
• $ make ttyeden
• $ ./ttyeden -v

... you should get some output including the version detail, for example "ttyeden version 1.72 (r245)".  If you are going to distribute the binary you've made here, please make sure the svn r number shown here is "simple" -- has just one number (eg r245).  If it shows something more complex, eg r242:244MS, then you probably need to check in any source code modifications you've made. (If you see 'r???', check that the 'svnversion' utility is in your $PATH.) Please make sure any binaries you distribute are based on source from just one revision in SVN (ie they have a "simple" r number) -- this way, someone else can retrace your steps for debugging if necessary.

• $ ./ttyeden
  

... now test ttyeden a bit, including:

• $ ./ttyeden Tests/listtest.eden
  
• $ ./ttyeden Tests/stringtest.eden
  

(these should just print SUCCESS if all is well.)

Compile the tkeden binary

• $ cd EDEN-recent/trunk/
  
• $ make clean
  (This is necessary as various files generated for ttyeden in the previous step will still exist.)

• $ make tkeden
  

• You should now have a tkeden binary (named 'tkeden.exe' on Windows, just 'tkeden' on others). Note that, unless you are on UNIX, it can't be run directly yet, since the supporting resources aren't in the right place - see later steps.
  

Compile the htmlwidget library (only necessary on Mac)

The htmlwidget library is required by tkeden if you create an HTML window using %angel (as the EMPE does, for example). Binary versions of this library for Windows and Linux have been checked in to our SVN - and this is an error of a kind, since our SVN should not contain generated files. However, we're using those binaries on those platforms anyway, but on the Mac, we need to compile this library ourselves if it is required.

Bundle together the binary and necessary resources, then start tkeden

Do some basic tests of tkeden

It is a good idea to do at least the following basic tests before doing anything more sophisticated.

• Open the 'About tkeden' window (in the Help menu - or on the Mac, in the 'tkeden' application menu) and check the details there. As per the 'ttyeden -v' instructions earlier, it should include the version detail, for example "tkeden version 1.72 (r245)".  If you are going to distribute the binary you've made here, please make sure the svn r number shown here is "simple" -- has just one number (eg r245). If it shows something more complex, eg r242:244MS, then you probably need to check in any source code modifications you've made. (If you see 'r???', check that the 'svnversion' utility is in your $PATH.) Please make sure any binaries you distribute are based on source from just one revision in SVN (ie they have a "simple" r number) -- this way, someone else can retrace your steps for debugging if necessary.
• Try File > Open and choose EDEN-recent/trunk/Tests/html.gel. This is a test of the htmlwidget library (see a few steps earlier). If this works, you should see a window containing some formatted text, reading "Interface Specification" (etc).

Package up the files for distribution

If you want to give your results from all this to someone else so they can run EDEN, you will need to package it up. You will need to send them the binary, but also some associated resources (eg the lib-tkeden directory). On some platforms, there is a Makefile rule to assist with this.

Note! You probably need to update the file lib-tkeden/change.log before doing this.

Other hints

• If you want Scout to be able to display images from files formats other than just the Tk default PPM/PGM and GIF (I believe these are the defaults, but actually haven't checked since 2001!), follow the instructions provided with the Tk Img package to install it, and tkeden should detect and load it automatically at runtime.
• If you want to compile non-optimised (for easy single-stepping in a debugger), I'd recommend that you set the environment variable CFLAGS to "-g -O0" and then re-make everything.
• The configure script has the --enable-depend option, which turns on some automatic Makefile source code dependency checking to make sure that the necessary source is recompiled when files are changed. To use this (NB I'm not really sure if this is necessary on modern machines since they compile EDEN pretty quickly and you can easily do 'make clean; make tkeden' if you think there is a problem with sources not being compiled in the correct order), run configure with this option, then do 'make generate' and 'make depend'.

History of this document

• 19 Oct 2010: Added note about updating change.log. [Ash]
• 12 Oct 2010: Corrections to information re bison-generated files (they aren't included in the archive tarball), merged in trunk/Docs/INSTALL.TXT, added more detail from Nick via WMB about Ubuntu & Cadence, and minor other fixes. [Ash]
• 11 Oct 2010: First version -- combining and replacing existing "Building EDEN for Linux at DCS", "Building EDEN for Windows" and "Building EDEN for Mac" documents and adding much other explanation. [Ash]