SubversionBuildInstructions
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 December 14, 2007, by Benjamin Shine.
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".
Contents |
Philosophy
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/setup-lps.sh]
Prerequisites
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.
Windows
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!)
| Groups | Packages |
|---|---|
| Archive | unzip, zip |
| Base | Install everything! |
| Devel | autoconf, 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 |
| Editors | emacs, gvim, vim, |
| Interpreters | emacs, expat, gawk, libexpat0, libxml2, m4, perl, ruby |
| Libs | xmHTML, 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 |
| Net | Apache, curl, intelutils, openssh, openssl, ping, rsync |
| Perl | perl |
| Shells | bash, bash-completion, |
| System | ioperm, man, ping, rebase, util-linux |
| Utils | bzip2, cygutils, diffstat, diffutils, patch, patchutils, pcre, rebase, time, util-linux |
| Web | xmHTML, 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 developer.apple.com. 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:
Linux:
ps -o args -C java
OS X:
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
We recommend using Java 1.5.
You must get the Java Development Kit (JDK), not the Java Runtime Environment (JRE). We recommend Java 1.5.
NOTE: No one has successfully built with JDK 1.6 yet, so I don't know why we list that here. In fact, we know that you will fail trying to install Jython if you install JDK 1.6.
Windows: Install Java in a path with no spaces in the name. That is,
C:\Java\jdk1.5.0_06 (good)
not
C:\Program Files\Java\jdk1.5.0_06 (bad)
Be sure to set JAVA_HOME appropriately.
Mac OS X: comes with Java pre-installed; we recommend upgrading to Java 1.5 if you don't have it already. Set JAVA_HOME to /Library/Java/Home. As of mid-April 2006, OS X includes and defaults to Java 5.0. If you have problems, see the Gotchas section at the end of this document.
Get the Subversion client
General information on Subversion is at subversion.tigris.org. 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
svn
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.4 or later; 1.3.2 or later should work.
Windows: There are several options.
1) You can get the .exe binaries directly from Tigris.
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 -Dbuild.id=mybuildid 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. For earlier versions of OS X, the easy way is to install Subversion using the pre-built binaries. 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 http://svn.openlaszlo.org/openlaszlo/trunk openlaszlo/trunk
Note that the URL is svn.openlaszlo.org, not www.openlaszlo.org. 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 http://svn.openlaszlo.org/vendor
The tools directory, which provides customized tools written by OpenLaszlo developers, is helpful for development:
cd $HOME/src/svn svn co http://svn.openlaszlo.org/tools/trunk tools/trunk
You can check these trees out to anywhere you want. We recommend this structure:
$HOME/src/svn/
openlaszlo/
trunk/ this is LPS_HOME if you're working in trunk
tags/
branches/
branchname/ this is LPS_HOME if you're working in a branch
tools/
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/setup-lps.sh] 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/setup-lps.sh
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 http://www.info-zip.org/ for an easy and free download and install of zip and unzip.
Get ant 1.6.5
We are using ant 1.6.5. Ant 1.5.* will not work. Ant 1.7 appears to work, although you will get some warnings.
cd $LZ_INSTALLS_ROOT unzip $LZ_VENDOR_ROOT/apache-ant-1.6.5-bin.zip export ANT_HOME=$LZ_INSTALLS_ROOT/apache-ant-1.6.5
Windows-no-cygwin: use the WinZip GUI to unzip apache-ant-1.6.5-bin.zip into your lib directory.
Mac-no-unzip: If you don't have /usr/bin/unzip, you may be able to double-click on apache-ant-1.6.5-bin.zip in the finder, and drag the resulting folder into $LZ_INSTALLS_ROOT (most likely ~/lib).
Mac OS X: As of Leopard (10.5), ant 1.6.5 is pre-installed.
SUSE linux: do not install the ant rpm.
Install JavaCC
JavaCC is a compiler compiler, like yacc; we use it to help build the compiler. If you want to run the GUI installer:
cd $LZ_VENDOR_ROOT java -cp . JavaCC2_1 -c
It will ask you where to install to; we suggest $LZ_INSTALLS_ROOT/javacc2.1. It will also tell you to set ~/lib/javacc2.1/bin on your path, but the setup-lps script has taken care of this for you.
If you would prefer the gui installer, remove -c from the Java command.
When installing on Windows, be sure to install to: 'C:\cygwin\home\<your_user_name>\lib\javacc2.1'. --Sosullivan 09:17, 28 September 2007 (PDT)
Install Tomcat 5.0.30
The Tomcat 5.0.30 installer in our vendor directory is exactly the same as the official Tomcat 5.0.30 release.
Windows: Get the Tomcat 5.0.30 installer from http://archive.apache.org/dist/tomcat/tomcat-5/v5.0.30/bin/jakarta-tomcat-5.0.30.exe. 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:
cd $LZ_INSTALLS_ROOT unzip $LZ_VENDOR_ROOT/jakarta-tomcat-5.0.30.zip
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 http://tomcat.apache.org/tomcat-4.1-doc/manager-howto.html#Configuring%20Manager%20Application%20Access for details. The build is set up to use user "admin" with password "laszlo", but you can change this in ${LPS_HOME}/build.properties.
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/*
Install rhino
cp $LZ_VENDOR_ROOT/js.jar $ANT_HOME/lib/
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/setup-lps.sh]. 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:
ANT_HOME, JAVA_HOME, JAVACC_HOME, TOMCAT_HOME, CATALINA_HOME, LPS_HOME
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 $JAVACC_HOME cd $TOMCAT_HOME cd $CATALINA_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 setup-lps.sh that uses cygpath to fix the slash issues and will work on cygwin: cygwin version of setup-lps.sh. 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 setup-lps.sh, as it has broken my tar, so I could not create any files)
export HOME=`cygpath -w ${HOME}`
Install a few libraries automatically
(You may need to do this step as root.)
cd $LZ_VENDOR_ROOT svn up cd $LZ_TOOLS_ROOT/build-tools/install-libs ant
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 $TOMCAT_HOME/bin/startup.sh ant webapp.install
If, during webapp.install, you get java.net.ConnectException: 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 setup-lps.sh cd $LPS_HOME ant build cd $TOMCAT_HOME chmod +x * $TOMCAT_HOME/bin/startup.sh bash // for some reason bash exited at the end of startup.sh 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.
Flash 9 Development
Get the Flex 3 SDK, and install it on your system, whereever you prefer
http://labs.adobe.com/technologies/flex/sdk/flex3sdk.html
In a previous version, there were variables in lps.properties that said how to run the compiler. These are no longer used.
Then modify WEB-INF/lps/config/lps.properties to have the pathname for the mxmlc and compc
executables. Example:
# Where the SWF9 external library compiler lives (relative to HOME, or absolute) compiler.swf9.lib.builder=/Users/hqm/flex3/bin/compc # Where the SWF9 external application compiler lives (relative to HOME, or absolute) compiler.swf9.app.builder=/Users/hqm/flex3/bin/mxmlc
Setting the FLEX_HOME Environment Variable
Instead editing lps.properties, the FLEX_HOME environment variable must be set. FLEX_HOME refers to the top level directory of the sdk, this is a directory that contains 'bin' and 'lib' subdirectories.
When you install the new flex 3.0.0 beta sdk on OSX, you can leave the flex installation in its default location and set up this variable in your shell like this:
For Unix/Linux:
$ export FLEX_HOME="/Applications/Adobe\ Flex\ Builder\ 3/sdks/3.0.0" $ ls -l "$FLEX_HOME/bin/compc" $ ls -l "$FLEX_HOME/bin/mxmlc"
If the second two lines succeeded, then everything should work. Note that your tomcat must be started *after* setting the FLEX_HOME variable.
On Windows, environment variables are accessible via Control Panel/System/Advanced. If you get an error from Tomcat that FLEX_HOME is not defined, try rebooting your machine. Install flex to a simple directory like C:\flex3. If you use this strategy, set FLEX_HOME to "C:\flex3".
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 http://svn.openlaszlo.org/openlaszlo/branches/branchname export LPS_HOME=./branchname
The server is installed at http://localhost:8080/branchname
To work with a particular tag, do
svn co http://svn.openlaszlo.org/openlaszlo/branches/tagname 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 www.openlaszlo.org.
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.
Windows
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>.
Linux
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: java.io.IOException: Access is denied at java.io.WinNTFileSystem.createFileExclusively(Native Method) at java.io.File.createNewFile(File.java:828) 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(HttpServlet.java:697) at javax.servlet.http.HttpServlet.service(HttpServlet.java:810)
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.
