Author: ben
Date: 2007-12-21 15:53:46 -0800 (Fri, 21 Dec 2007)
New Revision: 7661
Removed:
openlaszlo/trunk/docs/src/developers/release-management.dbk
Modified:
openlaszlo/trunk/docs/src/developers/docbook-code.dbk
openlaszlo/trunk/docs/src/developers/js2doc-local.dbk
openlaszlo/trunk/docs/src/developers/js2doc-ref.dbk
openlaszlo/trunk/docs/src/developers/licenses.dbk
openlaszlo/trunk/docs/src/developers/source-build.dbk
Log:
Change 20071221-ben-a by [EMAIL PROTECTED] on 2007-12-21 15:42:59 PST
in /Users/ben/src/svn/openlaszlo/trunk
for http://svn.openlaszlo.org/openlaszlo/trunk
Summary: Improvements to contributor-oriented chapters in devguide
Documentation:
Modified the "Source Build" chapter to be up to date for the
4.1.x build, with no python and no jython required. Updated
it with some of the more recent changes on the wiki. This chapter
is now just about as good as
http://wiki.openlaszlo.org/SubversionBuildInstructions.
Gave each chapter an id, so the html chunks have nice filenames
instead of just "ch55.html"
Removed the completely empty chapter on release management.
Modified: openlaszlo/trunk/docs/src/developers/docbook-code.dbk
===================================================================
--- openlaszlo/trunk/docs/src/developers/docbook-code.dbk 2007-12-21
23:45:29 UTC (rev 7660)
+++ openlaszlo/trunk/docs/src/developers/docbook-code.dbk 2007-12-21
23:53:46 UTC (rev 7661)
@@ -7,7 +7,7 @@
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd";>
-<chapter language="en">
+<chapter language="en" id="docbook-code">
<title>Documenting Your Code</title>
<section><title>The Basics</title>
Modified: openlaszlo/trunk/docs/src/developers/js2doc-local.dbk
===================================================================
--- openlaszlo/trunk/docs/src/developers/js2doc-local.dbk 2007-12-21
23:45:29 UTC (rev 7660)
+++ openlaszlo/trunk/docs/src/developers/js2doc-local.dbk 2007-12-21
23:53:46 UTC (rev 7661)
@@ -7,7 +7,7 @@
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd";>
-<chapter language="en">
+<chapter language="en" id="js2doc-local">
<title>Documenting Your Code</title>
<section><title>The Basics</title>
Modified: openlaszlo/trunk/docs/src/developers/js2doc-ref.dbk
===================================================================
--- openlaszlo/trunk/docs/src/developers/js2doc-ref.dbk 2007-12-21 23:45:29 UTC
(rev 7660)
+++ openlaszlo/trunk/docs/src/developers/js2doc-ref.dbk 2007-12-21 23:53:46 UTC
(rev 7661)
@@ -7,7 +7,7 @@
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd";>
-<chapter language="en">
+<chapter language="en" id="js2doc-reference">
<title>JS2Doc Reference</title>
<note>This book part is currently being drafted. Stay tuned for more
contents!</note>
Modified: openlaszlo/trunk/docs/src/developers/licenses.dbk
===================================================================
--- openlaszlo/trunk/docs/src/developers/licenses.dbk 2007-12-21 23:45:29 UTC
(rev 7660)
+++ openlaszlo/trunk/docs/src/developers/licenses.dbk 2007-12-21 23:53:46 UTC
(rev 7661)
@@ -1,7 +1,7 @@
<?xml version="1.0"?>
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd";>
-<appendix>
+<appendix id="licenses">
<title>Third-Party Software Used in this Release</title>
<segmentedlist>
<?dbhtml list-presentation="table"?>
Deleted: openlaszlo/trunk/docs/src/developers/release-management.dbk
Modified: openlaszlo/trunk/docs/src/developers/source-build.dbk
===================================================================
--- openlaszlo/trunk/docs/src/developers/source-build.dbk 2007-12-21
23:45:29 UTC (rev 7660)
+++ openlaszlo/trunk/docs/src/developers/source-build.dbk 2007-12-21
23:53:46 UTC (rev 7661)
@@ -7,16 +7,16 @@
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd";>
-<chapter language="en">
+<chapter language="en" id="source-build">
<title>Building OpenLaszlo from Source</title>
<section><title>Introduction</title>
- <para>These are the instructions for building 4.0.0 and later from source.
These instructions may also work for 3.4.x. See <ulink
url="http://wiki.openlaszlo.org/3.x_Build_Instructions";>3.x Build
Instructions</ulink> for build instructions for 3.3.x and earlier.</para>
+ <para>These are the instructions for building 4.1.x and later from source.
These instructions will not work for earlier versions. See <ulink
url="http://wiki.openlaszlo.org/3.x_Build_Instructions";>3.x Build
Instructions</ulink> for build instructions for 3.3.x and earlier. See <ulink
url="http://wiki.openlaszlo.org/SubversionBuildInstructions";>Subversion Build
Instructions</ulink> for information on building 3.4 - 4.0.x.</para>
<para>These instructions are fairly well tested, but there may be issues
with your particular setup. Please help us make it better by reporting your
experience to the laszlo-dev mailing list laszlo-dev mailing list and the
Laszlo developer forums.</para>
- <note><para>This document has been modified from it's original (wiki)
format. It has been reformatted to fit your screen.</para></note>
+ <note><para>This document has been modified from its original (wiki) format.
It has been reformatted to fit your screen.</para></note>
</section>
@@ -40,9 +40,8 @@
<para>To build OpenLaszlo, you're going to need <ulink
url="http://www.cygwin.com/";>Cygwin</ulink>. You can almost build and run
without Cygwin, but you will suffer, so perform a minimum Cygwin
installation.When you install cygwin, be sure to select installation of gcc,
subversion, and unzip.</para>
</section>
- <section><title>OS X: Developer Tools and bash</title>
- <para>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.</para>
- <para>All the shell scripts referenced here use the bash shell. That's the
default on OS X.</para>
+ <section><title>OS X: Nothing special required!</title>
+ <para>All the shell scripts referenced here use the bash shell. That's the
default on OS X. There are no other prerequisites.</para>
</section>
<section><title>Clean up Tomcat</title>
@@ -70,11 +69,7 @@
<para>You must get the Java Development Kit (JDK), not the Java Runtime
Environment (JRE).</para>
- <para><ulink url="http://java.sun.com/j2se/1.4.2/download.html";>JDK 1.4
Download Page</ulink></para>
-
<para><ulink url="http://java.sun.com/javase/downloads/index_jdk5.jsp";>JDK
1.5 Download Page</ulink></para>
-
- <para><ulink url="http://java.sun.com/javase/downloads/index.jsp";>JDK 1.6
Download Page</ulink></para>
<para>Windows: Install Java in a path with no spaces in the name. That
is,</para>
<informalexample><screen>C:\Java\jdk1.5.0_06</screen></informalexample>
@@ -83,8 +78,7 @@
<para>Be sure to set <literal>JAVA_HOME</literal> appropriately.</para>
- <para>Mac OS X (10.3 and 10.4) comes with Java 1.4.2 so there is no need
to install it. Set <literal>JAVA_HOME</literal> to
<literal>/Library/Java/Home</literal>. 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.</para>
-
+ <para>Mac OS X: Set <literal>JAVA_HOME</literal> to
<literal>/Library/Java/Home</literal>. As of mid-April 2006, OS X includes and
defaults to Java 5.0 (aka Java 1.5.0).</para>
</section>
<section><title>Get the Subversion client</title>
@@ -100,7 +94,7 @@
<variablelist>
<varlistentry><term>Windows</term>
<listitem>
- <para>There are several options. You can get the <ulink
url="http://subversion.tigris.org/downloads/svn-win32-1.4.3.zip";>.exe
binaries</ulink> directly from Tigris. For a nice GUI, we've had success with
<ulink url="http://wiki.openlaszlo.org/TortoiseSVN";>TortoiseSVN</ulink>.
Alternatively, 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 <ulink
url="http://svn.haxx.se/users/archive-2005-08/1408.shtml";>this posting</ulink>
for details.</para>
+ <para>There are several options. You can get the <ulink
url="http://subversion.tigris.org/downloads/svn-win32-1.4.3.zip";>.exe
binaries</ulink> directly from Tigris. For a nice GUI, we've had success with
<ulink url="http://wiki.openlaszlo.org/TortoiseSVN";>TortoiseSVN</ulink>. 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.
</para>
<para>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.</para>
</listitem>
</varlistentry>
@@ -200,82 +194,14 @@
</section>
<section><title>Install JavaCC</title>
- <para>JavaCC is a compiler compiler, like yacc; we use it to help build
the compiler. If you want to run the GUI installer:</para>
+ <para>JavaCC is a compiler compiler, like yacc; we use it to help build
the compiler. </para>
<informalexample><programlisting>cd $LZ_VENDOR_ROOT
-java -cp . JavaCC2_1</programlisting></informalexample>
-
- <para>It will ask you where to install to; we suggest
<literal>$LZ_INSTALLS_ROOT/javacc2.1</literal>. It will also tell you to set
<literal>~/lib/javacc2.1/bin</literal> on your path, but the
<literal>setup-lps</literal> script has taken care of this for you.</para>
-
- <para>If you would prefer the command line installer, add -c to the Java
command.</para>
-
- <informalexample><programlisting>cd $LZ_VENDOR_ROOT
java -cp . JavaCC2_1 -c</programlisting></informalexample>
- </section>
-
- <section><title>Install Jython (pre-4.1.0 only)</title>
+ <para>It will ask you where to install to; we suggest
<literal>$LZ_INSTALLS_ROOT/javacc2.1</literal>.</para>
+ </section>
- <para>Jython is a Java application that executes Python scripts. Parts of
the OpenLaszlo build pipeline are written in Python, but these have been phased
out in 4.x.</para>
-
- <informalexample><programlisting>cd $LZ_VENDOR_ROOT
-java -cp . jython-21</programlisting></informalexample>
-
- <para>Make sure "use jre" is not checked. The GUI will prompt you for the
Jython installation directory. We suggest
<literal>$LZ_INSTALLS_ROOT/jython-21</literal>.</para>
-
- <para>If you don't want to use the GUI installer, add <literal>-o
dir-to-install-to</literal>:</para>
-
- <informalexample><programlisting>java -cp . jython-21 -o
~/lib/jython-2.1</programlisting></informalexample>
-
- <para>Don't put jython in a system directory; the build will fail if the
jython process does not have write access to the jython directory.</para>
-
- <para><emphasis>NOTE: You can't use the command line installer on
Windows_XP because the installer does not understand that XP is Windows. If you
get an error about extra bytes at the end of your class file, it is because
jython has their own class loader and your Java is puking trying to verify the
non-standard class file. Downgrade your java to 1.5 and you will
win.</emphasis></para>
-
- </section>
-
- <section><title>Install Python</title>
- <variablelist>
- <varlistentry><term>Windows</term>
- <listitem>
- <para>Run the Python 2.2.2 installer, which is in
<literal>$LZ_VENDOR_ROOT/Python-2.2.2.exe</literal>. Reportedly 2.4.4 and later
do not work on Windows.</para>
- <note><para>If you get a message from the 16 bit MS-DOS Subsystem
telling you that <literal>C:\WINDOWS\system32\ntvdm.exe</literal> got an error
"while setting up the environment for the application. Choose 'Close' to
terminate the application.", it is likely because you are trying to use the
Cygwin version of Python, which just won't do. You need to arrange for the
Windows version of Python that you installed above to be found before the
Cygwin version is, either by juggling your search path or perhaps uninstalling
Cygwin Python.</para></note>
- </listitem>
- </varlistentry>
- <varlistentry><term>OS X</term>
- <listitem>OS X comes with Python installed to
<literal>/usr/bin/python</literal>. We're using 2.3.5 successfully.</listitem>
- </varlistentry>
- <varlistentry><term>Linux</term>
- <listitem>Most modern Linux distributions come with Python 2.2 or
later. The python-devel package must be installed, too. We have been using
Python 2.4.1 on Linux.</listitem>
- </varlistentry>
- </variablelist>
- </section>
-
- <section><title>Install PyXML</title>
- <variablelist>
- <varlistentry><term>Windows</term>
- <listitem>Run
<literal>vendor/PyXML-0.8.win32-py2.2.exe</literal>.</listitem>
- </varlistentry>
- <varlistentry><term>Linux and OS X</term>
- <listitem>
- <informalexample><programlisting>cd $LZ_VENDOR_ROOT
-gunzip PyXML-0.8.3.tar.gz
-tar xvf PyXML-0.8.3.tar
-cd PyXML-0.8.3
-python setup.py build
-sudo python setup.py install</programlisting></informalexample>
- <para>Note: contrary to previous reports, this step is
necessary.</para>
- <note><title>ptw's notes</title>
- <para>I install in a non-default place:</para>
- <informalexample><programlisting>sudo python setup.py install
--install-lib
/usr/local/lib/python2.3/site-packages</programlisting></informalexample>
- <para>I set the <literal>--install-lib</literal> option so that I
won't lose my local extensions if OS X updates Python. I also put the following
in my .bashrc so Python sees the local packages:</para>
- <informalexample><programlisting># we use _xmlplus, which I put
here to stay out of the /System dir
-export
PYTHONPATH=/usr/local/lib/python2.3/site-packages</programlisting></informalexample>
- </note>
- </listitem>
- </varlistentry>
- </variablelist>
- </section>
-
<section><title>Install Tomcat 5.0.30</title>
<para>The Tomcat 5.0.30 installer in our vendor directory is exactly the
same as the official Tomcat 5.0.30 release.</para>
@@ -305,37 +231,29 @@
<section><title>Set environment variables</title>
<para>The rest of these instructions require that you set several
environment variables. We've created a bash setup script in <ulink
url="http://svn.openlaszlo.org/tools/trunk/env/setup-lps.sh";>tools/trunk/env/setup-lps.sh</ulink>.
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:</para>
- <informalexample><screen>ANT_HOME, JAVA_HOME, JAVACC_HOME, JYTHON_HOME,
TOMCAT_HOME, CATALINA_HOME, LPS_HOME</screen></informalexample>
+ <informalexample><screen>ANT_HOME, JAVA_HOME, JAVACC_HOME, TOMCAT_HOME,
CATALINA_HOME, LPS_HOME</screen></informalexample>
<para>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:</para>
<informalexample><programlisting>cd $ANT_HOME
cd $JAVA_HOME
cd $JAVACC_HOME
-cd $JYTHON_HOME
cd $TOMCAT_HOME
cd $CATALINA_HOME
cd $LPS_HOME</programlisting></informalexample>
<variablelist>
<varlistentry><term>Windows/Cygwin</term>
- <listitem>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.</listitem>
- </varlistentry>
- <varlistentry><term>OS X</term>
- <listitem>
- <para>Note that in certain circumstances it can be preferable to use
Java 1.4.2 instead of Java 1.5, even on versions of OS X where Java 1.5 is the
default. The preferred technique for doing this in bash is to set JAVA_HOME as
follows:</para>
- <informalexample><programlisting>export
JAVA_HOME="/System/Library/Frameworks/JavaVM.framework/Versions/1.4.2/home/"</programlisting></informalexample>
- <para>To return to Java 1.5, reset JAVA_HOME to its original
value:</para>
- <informalexample><programlisting>export
JAVA_HOME="/Library/Java/Home"</programlisting></informalexample>
+ <listitem>For Cygwin, see <ulink
url="http://wiki.openlaszlo.org/Cygwin_version_of_setup-lps.sh";>a
cygwin-version of setup-lps.sh</ulink>. You will probably need to modify this
to fit your own particular environment.
</listitem>
- </varlistentry>
+ </varlistentry>
</variablelist>
</section>
<section><title>Install a few libraries automatically</title>
- <para>(You may need to do this step as root.)</para>
+
<informalexample><programlisting>cd $LZ_VENDOR_ROOT
svn up
cd $LZ_TOOLS_ROOT/build-tools/install-libs
ant</programlisting></informalexample>
-
+ <para>(If you have permission-denied errors, you may need to do this step as
root.)</para>
</section>
<section><title>Build and run!</title>
@@ -348,16 +266,12 @@
<variablelist>
<varlistentry><term>OS X</term>
<listitem>
- <para>OS X 10.4.3 I found that I had to do the following:</para>
- <informalexample><programlisting>bash // This loads the environment
variables in setup-lps.sh
+ <informalexample><screen>
cd $LPS_HOME
+ant tomcat.start
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</programlisting></informalexample>
+ant webapp.deploy
+</screen></informalexample>
</listitem>
</varlistentry>
</variablelist>
@@ -367,6 +281,18 @@
<section><title>Notes and gotchas</title>
<note><para>This section still needs to be copied over from the <ulink
url="http://wiki.openlaszlo.org/SubversionBuildInstructions";>wiki</ulink>.</para></note>
+ <variablelist>
+ <varlistentry>
+ <term>Compile-time Subversion Access</term>
+ <listitem> Our build system wants to talk to subversion 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
<literal>LzCanvas.versionInfoString()</literal>. Alternatively, you can say
+ <informalexample><programlisting>
+ ant -Dbuild.id=mybuildid build
+ </programlisting></informalexample>
+ to cause the build system not to query svn; but you will lose the svn
version information from <literal>versionInfoString</literal>.
+ </listitem>
+ </varlistentry>
+ </variablelist>
+
</section>
<section><title>What if it doesn't work?</title>
_______________________________________________
Laszlo-checkins mailing list
[email protected]
http://www.openlaszlo.org/mailman/listinfo/laszlo-checkins
