Personal tools


From OpenLaszlo

These are the instructions for building modern OpenLaszlo builds, including 3.4.x and 4.x. See 3.x Build Instructions for build instructions for 3.3.x and earlier. These instructions were last modified on May 16 by Henry Minsky. Ono Keiji added a comment at the 'install rhino' for Linux users on May 29th.

Trying to build older versions of the tree with the latest set of build tools?: BuildingOlderVersions

Instructions for building on a native Windows 7 machine (no cygwin) can be found here: NativeWindows7SubversionBuildInstructions

Please help us make these instructions better by reporting your experience to the laszlo-dev mailing list laszlo-dev mailing list and the Laszlo developer forums.

If you don't know what you want, you probably want "trunk".



The philosophy of these installation instructions is to create a user-owned-and-operated installation with all of the tools you need in one place. If you follow these instructions, we don't think you will need root access at any point. If you are a power user, use these instructions as guidelines; you can put anything anywhere, so long as you set the correct environment variables defined in [tools/trunk/env/]


You will need Java, Subversion, a command line, and the ability to set environment variables.

If you have firewall software, including Windows Firewall, you might need to open up access to port 8080. We'll mostly be using port 8080, but the other ones are briefly used for controlling server shutdown, startup, and secure connections. Do this with caution; if you don't know what it means to poke a hole in your firewall, you probably shouldn't do it.

Migrating from an existing installation

If you have installed OpenLaszlo on your machine, you don't need to uninstall it, but you do have to stop tomcat. Find and run the command "Stop OpenLaszlo Server."

If you have already built OpenLaszlo on your machine, but from a source other than the subversion repository, the cleanest thing to do is to ignore that distribution and start over. You don't need to delete it, but you do need to take references to it out of your path. (For advanced users only: you can keep your tools installed where they are, while changing your LPS-specific environment variables.)

Which platform?

If you have access to multiple platforms on which to experiment, we recommend building OpenLaszlo on Mac OS X at first.


To build OpenLaszlo, we recommend that you install Cygwin. You can build and run without Cygwin, but you will struggle a bit. When you install Cygwin, be sure to select at least these packages: gcc, subversion, and unzip. A fairly comprehensive list of suggested packages is below; these are the packages that one developer found were sufficient to build OpenLaszlo on a fresh, clean Cygwin install. (A significantly smaller set of packages would also suffice!)

Archiveunzip, zip
BaseInstall everything!
Develautoconf, autoconf, autoconf2.1, autoconf2.5, automake, binutils, ctags, diffstat, e2fsprogs, expat, , gcc, gcc-core, gcc-g++, gcc-mingw-core, gcc-mingw-g++, gdb, gettext, glib-devel,ioperm, libbrlapi, libfontconfig-devel, libfreetype2-devel, libiconv, libncurses-devel, libxml2, , make, mingw-runtime, mktemp, pango, pango-runtime, patchutils, pcre, readline, ruby, subversion
Editorsemacs, gvim, vim,
Interpretersemacs, expat, gawk, libexpat0, libxml2, m4, perl, ruby
LibsxmHTML, complace, crypt, expat, fontconfig, freeglut, freetype2, gettext, glib, glib-devel, gtk+, imlib, ioperm, jpeg, libapr1, libaprutil1, libbz2_1, libcharset1, libcurl4, libexpat0,libgdbm4, libggi2, libggiwmh0, libgii1, libglitz1, libgmp3, libiconv, libiconv2, libintl1, libintl2, libintl3, libintl8, libjpeg-devel, libjpeg62, libncurses-devel, libncurses7, libncurses8, libneon26, libopenldap2_3_0, libcre0, libpng, libpng12, libpopt0libpq4, libreadline6, libsasl2, libssh2_1, libtiff4, libtiff5, libungif4, libxml2, mingw-runtime, minires, openssl, pango, pango-runtime, readline, t1lib, tcltk, termcap, w32api, zlib
NetApache, curl, intelutils, openssh, openssl, ping, rsync
Shells bash, bash-completion,
Systemioperm, man, ping, rebase, util-linux
Utilsbzip2, cygutils, diffstat, diffutils, patch, patchutils, pcre, rebase, time, util-linux
WebxmHTML, apache, curl, lynx, wget

To select an item for installation, click on Default in the left hand column for that item until a version number appears. Once that occurs, the item is selected and ready to install.

If the system asks you if you want to load additional packages to satisfy dependencies, say 'yes'.

After the installation of Cygwin completes, and before you launch it for the first time, create a HOME environment variable in Windows, and point it to C:\cygwin\home\<your_user_name>. When Cygwin launches for the first time, it will see that environment variable, and create your home directory on your C:\.

OS X: Developer Tools and bash

You'll need to install the developer tools in order to compile OpenLaszlo. They can be found on your Mac OS X installation CD, or at You will need to have at least Developer Tools version 2.2 installed if you are running OS X 10.4.x.

All the shell scripts referenced here use the bash shell. That's the default on OS X.

Clean up Tomcat

Clean up any other Tomcat instances you have running, or any processes which are using port 8080, 8005, or 8043. To find existing Tomcat instances:


  ps -o args -C java


  ps | grep java

Windows (this stops the LPS instance if it exists):

  sc delete LPS

Create a directory to hold the source and tools you're about to install -- for example, C:\Laszlo on Windows, while on OS X and Linux, we like /home/$USER/src/svn.

Get Java

As of OpenLaszlo 5.0, we recommend using Java 1.6/JDK 6.

You must get the Java Development Kit (JDK), not the Java Runtime Environment (JRE).

JDK Download Page

NOTE: OpenLaszlo versions prior to 5.0 required Java 1.5/JDK 5.

Windows: Install Java in a path with no spaces in the name. That is,

   C:\Java\jdk1.5.0_06    (good)


   C:\Program Files\Java\jdk1.5.0_06     (bad)

Be sure to set JAVA_HOME appropriately.

Mac OS X: comes with Java pre-installed. Set JAVA_HOME to /Library/Java/Home. As of Snow Leopard, OS X includes and defaults to Java 1.6/JDK 6. If you have problems, see the Gotchas section at the end of this document.

If you are running Mac OS X 10.5, you can update to Java 1.6/JDK 6 here: Java for Mac OS X 10.5 Update 1

Get the Subversion client

General information on Subversion is at These instructions use the command line client for Subversion.

The package is usually called "subversion" and the executable is "svn". Before you try to install, check if you already have it by going to a command prompt and typing


If the result is "command not found" or something like that, you need to install Subversion. If the result is something like "Do svn help for more instructions", then you do not need to install Subversion. We suggest subversion 1.6.12.

Windows: There are several options.

1) You can get the binaries directly from Apache Subversion.

2) For a nice GUI, we've had success with TortoiseSVN Note: if you are using Tortoise you need to make the command line tools available also, or the build system will not be able to query svn for version info. [Our build system wants to talk to svn so that it can include the svn version in the binaries, which we find helpful for reporting bugs. You can get this information even in non-debug builds from LzCanvas.versionInfoString(). Alternatively, you can say

   ant build

to cause the build system not to query svn; but you will lose the svn version information from versionInfoString.]

3) Use the Cygwin installer: the Subversion package is inside the "Devel" group. Earlier builds of cygwin build of svn (version 1.2.3) might have a problem with properly checking out a source tree. See this posting for details. Cygwin now ships with subversion 1.4.5 and so far no problems have been reported for this version.

4) If you elect to use the native Windows svn command line client, and also have the cygwin Subversion package, make sure to put it in your bash shell path in front of the cygwin bin directories, so you don't inadvertently use the cygwin 'svn' command by mistake.

Macintosh: As of Leopard (10.5) OS X comes with subversion pre-installed, although you may need to upgrade to the latest version. For earlier versions of OS X, the easy way is to install Subversion using the pre-built binaries. The openCollabNet version is a Universal Binary, and the easiest to install. Using Fink or building Subversion from source will probably also work, but then you must know what you're doing.

Linux: If you have a Linux box, you surely know how to install Subversion.

Get the source

As stated in the philosophy section, these instructions show you how to make a user-owned-and-operated installation. Once you're a power user, you can be clever in all the ways you want to be clever; first-timers should stick to this path, and post on laszlo-dev if they have trouble.

Make a directory in which you'll put all the stuff you're about to get. We recommend $HOME/src/svn for the downloaded code, and $HOME/lib for the libraries you'll have to install.

   cd $HOME
   mkdir src
   mkdir src/svn
   mkdir lib

To get the source with Subversion, do

   cd $HOME/src/svn
   svn co openlaszlo/trunk

Note that the URL is, not You'll get an Authentication Realm message if you mistakenly use www.

This will take a while, because you're getting upwards of 100 MB.

Also get the vendor directory, which contains third-party libraries and applications which are required to build and run the OpenLaszlo server. These are here as a convenience; they are exactly the bits that you would get from each vendor's distribution of that version. Note that there are some tricky version requirements; if you get weird errors, check that you're using the suggested versions.

   cd $HOME/src/svn
   svn co

The tools directory, which provides customized tools written by OpenLaszlo developers, is helpful for development:

   cd $HOME/src/svn
   svn co tools/trunk

You can check these trees out to anywhere you want. We recommend this structure:

               trunk/                 this is LPS_HOME if you're working in trunk
                   branchname/    this is LPS_HOME if you're working in a branch
               trunk/                  this is LZ_TOOLS_ROOT
           vendor/                     this is LZ_VENDOR_ROOT
   $HOME/lib                           this is LZ_INSTALLS_ROOT            

We've created a script to ease configuration. Take a look at [tools/trunk/env/] and the rest of this document might make more sense. This script enables you to specify with command line parameters the location of these directories: openlaszlo, tools, installed libraries, and vendor. The script sets environment variables relative to the specified directories. If you follow the recommended paths in this document, you can just do

   . $HOME/src/svn/tools/trunk/env/

Note the leading dot. You'll have to invoke this setup script in every shell in which you want to do OpenLaszlo development. You might have to edit the script so that the environment variables correspond to your directory structure.

There are a few applications you must install in order to build OpenLaszlo. The Subversion repository contains the installers, but you need to run the installers. Run these installers from the same user account with which you will be developing. We recommend installing these tools into $HOME/lib; this makes it easier to force the tools to use the versions that come with OpenLaszlo.

Install the tools

Make sure you have unzip

Check to see if you have at least one of /usr/bin/unzip or /sw/bin/unzip. If you don't have it there are a number of ways you can get unzip. For some reason I didn't have unzip even though I'd installed the Apple developer tools. Supposedly, the Apple developer tools will do it, but Installing fink will work. Another choice is for an easy and free download and install of zip and unzip.

Get ant 1.7.1

We are using ant 1.7.1. If you don't already have that:

   unzip $LZ_VENDOR_ROOT/
   export ANT_HOME=$LZ_INSTALLS_ROOT/apache-ant-1.7.1-bin

Windows-no-cygwin: use the WinZip GUI to unzip the .zip file into your lib directory.

Mac-no-unzip: If you don't have /usr/bin/unzip, you may be able to double-click on the .zip file in the finder, and drag the resulting folder into $LZ_INSTALLS_ROOT (most likely ~/lib).

Mac OS X: As of Snow Leopard (10.6), ant 1.7.1 is pre-installed. You can skip the above and just say:

    export ANT_HOME=/usr/share/ant/

SUSE linux: do not install the ant rpm.

Install ant support jars

We use some additional ant tasks in our build scheme that rely on additional jars. To avoid polluting your ant installation, you should install these additional jars in your ~/.ant/lib directory. (You may have to create that directory if you do not already have one.)

For Linux, do this command first:

    mkdir -p ${HOME}/.ant/lib/

The minimal set that ant 1.7 needs (for building) is:

    cp ${LZ_VENDOR_ROOT}/{ant-contrib,catalina-ant,jing,js}.jar ${HOME}/.ant/lib/

Also, we would suggest changing the variable $HOME to $LASZLO_HOME because $HOME has special meaning in Unix-based systems. To build the doc you also need the xalan and serializer jars. You must copy these jars for doc builds, don't use the Xalan version shipped with Java 1.6, it has a known bug with <xsl:key>.

[Ant 1.6 also needed commons-logging and bsf jars, but these are part of ant in 1.7 and must be removed if you upgrade to 1.7]

[The build machines need additional jars: activation and javamail-1.4 to be able to send mail]

[Cygwin: I needed to copy the jars into my Windows user-directory instead of the Cygwin user-directory, that means I had to use:

    cp ${LZ_VENDOR_ROOT}/{ant-contrib,catalina-ant,jing,js}.jar "`cygpath -u "$USERPROFILE"`"/.ant/lib

The "-diagnostics" parameter may help you to find out which jars are loaded by ant:

    ant -diagnostics


Install JavaCC

JavaCC is a compiler compiler, like yacc; we use it to help build the compiler. We suggest to install it to $LZ_INSTALLS_ROOT/javacc-5.0:

   unzip $LZ_VENDOR_ROOT/

You will also need to add JavaCC to your path, but the setup-lps script has taken care of this for you.

When installing on Windows, be sure to install to: 'C:\cygwin\home\<your_user_name>\lib\javacc-5.0'. --Sosullivan 09:17, 28 September 2007 (PDT)

Install Tomcat

OpenLaszlo should work with any recent Tomcat installation. It has been tested with Tomcat 5.0.30 and 6.0.x, and the setup instructions below have been tested with 5.0.30. We've provided a Tomcat 5.0.30 installer in our vendor directory that is exactly the same as the official Tomcat 5.0.30 release.

Windows: Get the Tomcat 5.0.30 installer from Run the installer. When it asks you where to put it, say C:/Tomcat5. Don't start Tomcat; we'll do that later.

OS X and Linux:

   unzip $LZ_VENDOR_ROOT/

This installs tomcat into $LZ_INSTALLS_ROOT/jakarta-tomcat-5.0.30/

Create a user with "admin" and "manager" roles, in jakarta-tomcat-5.0.30/conf/tomcat-users.xml. See for details. The build is set up to use user "admin" with password "laszlo", but you can change this in ${LPS_HOME}/ If you want the defaults, you can just add the following line:

  <user name="admin"   password="laszlo" roles="admin,manager" />

The scripts in jakarta-tomcat-5.0.30/bin/* need to be executable; if you know what this means, do this:

 (Don't do this if you don't understand chmod. See your local sysadmin.) 
 chmod ugo+x jakarta-tomcat-5.0.30/bin/*

Set environment variables

The rest of these instructions require that you set several environment variables. We've created a bash setup script in [tools/trunk/env/]. You can source this script from your .bashrc, or call it interactively. If you don't use our script, your mileage may vary, but we require the following variables to be set:


For Mac, please make sure you have enough memory to run the build:

   export JAVA_OPTS="-ea -Xmx768m"

However you set these variables, you should make sure the directories exist and they're the right ones. If you can't CD to the directory you have a definite problem, and with all the version numbers you might get wrong you'll probably save yourself a lot of frustration if you run this script:

   cd $ANT_HOME
   cd $JAVA_HOME
   cd $LPS_HOME

For Cygwin, WindowsBuilderSetup shows how we set environment variables for a particular Windows machine; use it as a guide for creating your own Cygwin bash script. The number and direction of slashes and quotes is a source of difficulty, but can be fixed with a function called cygpath. As an alternative to WindowsBuilderSetup, here's a variant of the that uses cygpath to fix the slash issues and will work on cygwin: cygwin version of Read the comments in the file and call it from your .bashrc

(Note from André: You may need to remove the following line of the cygwin-version of, as it has broken my tar, so I could not create any files)

export HOME=`cygpath -w ${HOME}`

Build and run!

Start a new shell so you have all the right environment variables. Then (Windows users running Cygwin, run ant init first, before ant build, in order to copy some required jar files before the compile):

   cd $LPS_HOME
   ant build 
   ant webapp.install

If, during webapp.install, you get Connection refused: connect, that means Tomcat never started. If you get a HTTP 401 response code, it means that you failed to set up your admin user/password correctly (see above on installing Tomcat).

OS X 4.3 I found that I had to do the following:

   bash // This loads the environment variables in
   cd $LPS_HOME
   ant build
   chmod +x *
   bash // for some reason bash exited at the end of
   cd $LPS_HOME
   ant webapp.install

Then point your browser at http://localhost:8080/trunk, or, if you're running a branch or tag, http://localhost:8080/branchname

In the future, when you have updated your branch(es) with svn up, you will have to repeat this build process.

Eclipse integration

Instructions to build the Java sources from within Eclipse can be found at Build Server with Eclipse.

Flash 9 Development

Get the Flash Debug Player from Adobe's web site

The Flash debug player is needed to run the flex fdb debugger.

Download it for your platform from

Use command line 'fdb' tool to debug Flash 9 apps

The flex command line debugger, fdb, is included in the tree. Add $LPS_HOME/WEB-INF/bin to your path to find it.

You can use fdb to debug an application from the shell, or to launch and connect to the app running in a browser. For apps that use network access, it is necessary to run it in a browser or else the flash security model will prevent network communication.

Example command line session

  lzc  -g --runtime=swf9 myapp.lzx       #compile with debugging on
  fdb myapp.lzr=swf9.swf 

or else

 fdb ""

When the app loads into the browser, fdb will pause to let you set breakpoints; just enter "c" to continue

NOTE: You may need to install the Flex SDK to get fdb to work. On Mac OS X fdb expects that there is an '/usr/bin/flex/' directory. If it is not present, then this is where you should install the Flex SDK.

Generating Stack Traces in SWF9

The Flash 9 runtime can generate a debug stack trace, using the AS3 Error object.

If you have a runtime error which you have caught, you can use the getStackTrace() method to get a string containing the backtrace. Or you can generate a stack trace in your code like this

Debug.write(new Error('I want a stack trace please').getStackTrace()) )

Getting output from the Flash player's log file for debugging

Calls to trace() can be logged to a disk file, which is useful to view trace output if you are running an app in the browser without having the fdb console debugger attached.

This document tells how to set up the flash player 9 debug logging, and where to find the output file

This is useful to see flash player log output from the player running in the browser

It is also possible to launch the browser plug-in from the command line 'fdb' debugger, you can say

fdb ""

(although there is some bug that it keeps setting debug to true when it delivers the app right now)

See also

for tips on setting up logging of flash output to a disk file

You need a file named "mm.cfg"

which contains this line

ErrorReportingEnable=1 TraceOutputFileEnable=1 TraceOutputFileName=Macintosh HD:Users:hqm:flashLog.txt MaxWarnings=50

FYI, if you look carefully, it says you will find the log on the Mac in

~/Library/Preferences/Macromedia/Flash Player/Logs/flashlog.txt

Notes and Gotchas

Later Versions

Initial reports indicate that JDK 1.6 and Tomcat 5.5.23 work with Open Laszlo 3.4, with one change required to the main build file: in $LPS_HOME/build.xml, remove the space at the end of the localWar attribute in the deploy task.

Subversion Tips

There's a page of Subversion tips at SubversionTips.

Branches and Tags

If you're not working in any particular branch, then ${branch} is "trunk". There's a small asymmetry here; trunk is a sibling of branches, not a child of branches.

To work with a particular branch, do

   svn co
   export LPS_HOME=./branchname

The server is installed at http://localhost:8080/branchname

To work with a particular tag, do

   svn co
   export LPS_HOME=./tagname

The server is installed at http://localhost:8080/tagname

Checkin mail

Checkin mail is sent to the laszlo-checkins mailing list. See laszlo-checkins for subscriptions and access to the archives.

Web Access

Websvn is installed on

Mac OS X

99% of the Open Laszlo development team uses a Macintosh. Mac builds are a first-class citizen with us. Every release of OS X has included more of the tools that we need pre-installed, and even those of us who love Windows, prefer to run it on a MacBook.

Tomcat: If you installed Tomcat as root, make sure the Tomcat directories are writable; Tomcat needs to write to directories in the tree while running.


Note: it's recommended that you use the Windows-style path rather than a Cygwin one for LPS_HOME.

In Cygwin, run ant init first, before ant build, in order to copy some required jar files before the compile.

Add the Cygwin bin directory to your $PATH.

You will have an easier time typing pathnames if you install tomcat at C:\tomcat5 instead of the default location. At the end of installing tomcat 5.0.24, do NOT start the server (the default is to start it).

The LPS build system installs the Tomcat5 NT service under the name 'LPS' so you can use net stop LPS, net start LPS to start/stop the service).

When using ant in the Cygwin bash shell environment to build (i.e., 'ant build', etc.), you may on occasion, depending on which Cygwin packages you have installed, get the following 'informational' dialog box:


To my (ptw's) knowledge, this error was caused by ant/Java (a Windows app) trying to invoke Cygwin Python. Since Python is no longer needed, you should not see this error. But if you do, look for Windows tools trying to invoke Cygwin binaries as a possible cause.

The 'vendor' branch contains the 'Tomcat 5.0' directory. It is recommended that your TOMCAT_HOME bash environment variable use the Windows-style notation to point to this directory. Unfortunately, this is rather difficult to do given the space in 'Tomcat 5.0'. Therefore, the current workaround is to create a softlink to this directory like so:

ln -s "Tomcat 5.0" Tomcat5

Then use the path to 'Tomcat5' in the TOMCAT_HOME environment setting. For example:

export TOMCAT_HOME="C:/tmp/OpenLaszlo/vendor/Tomcat5"

Do NOT use Notepad to edit the shell files used in Cygwin. This will corrupt your files and cause problems. It has been suggested to download and use Vim for Windows, and that has worked well. It can be downloaded from: <http://www.vim.orgdownload.php>.


There are certain directories in the jython installed directory that need to be writable - if you install this in /usr/local as root, make sure the installed tree is world writable.

Do not install the ant rpm. In SUSE linux, one developer found the ant rpm had installed a .antrc, which overrides $ANT_HOME.

What if it doesn't work?

Cannot access an LZX file

In this case, ant build install is successful, you can see in the Tomcat Manager that the web app is running; however, when you try to access a .lzx file, the browser prompts you to download the file instead of compiling and running it. If you check out your tomcat log (in $CATALINA_HOME/logs), it shows errors like these:

2006-04-26 16:03:05 StandardContext[/svn-video]LPS: LPS_HOME is C:\laszlo\svn-video

2006-04-26 16:03:05 StandardContext[/svn-video]LPS: LPS config directory is:      C:\laszlo\svn-video\WEB-INF\lps\config

2006-04-26 16:03:05 StandardContext[/svn-video]LPS: Access is denied

	at Method)


	at org.openlaszlo.servlets.responders.ResponderLOGCONFIG.configure(Unknown Source)

	at org.openlaszlo.servlets.responders.ResponderLOGCONFIG.configureWithLPSConfig(Unknown Source)

	at org.openlaszlo.servlets.responders.ResponderLOGCONFIG.configure(Unknown Source)

	at org.openlaszlo.servlets.LZServlet.initLPS(Unknown Source)

	at org.openlaszlo.servlets.LZServlet.doGet(Unknown Source)

	at javax.servlet.http.HttpServlet.service(

	at javax.servlet.http.HttpServlet.service(

then it can't create the "work" directory in WEB-INF/lps/. Fix your permissions. This commonly happens on Windows running cygwin.

To run a nightly build, see SubversionNightlyBuilds.

For more advanced build instructions see OpenLaszlo Developer Hints.