[armedbear-cvs] r11930 - public_html/doc
Erik Huelsmann
ehuelsmann at common-lisp.net
Fri May 22 21:46:39 UTC 2009
Author: ehuelsmann
Date: Fri May 22 17:46:35 2009
New Revision: 11930
Log:
Add documentation on the website as provided by Phil Berry (2009pb at googlemail).
Added:
public_html/doc/
public_html/doc/abcl-css.css
public_html/doc/abcl-install-with-java.html
public_html/doc/abcl-lisp-java-integration.html
public_html/doc/abcl-start.html
public_html/doc/ant-apache-org.jpg (contents, props changed)
public_html/doc/getting-started.txt
public_html/doc/javajdk.jpg (contents, props changed)
public_html/doc/javajre.jpg (contents, props changed)
Added: public_html/doc/abcl-css.css
==============================================================================
--- (empty file)
+++ public_html/doc/abcl-css.css Fri May 22 17:46:35 2009
@@ -0,0 +1,30 @@
+/* ----------------------------------------------------------------------------
+ * File: abcl-css.css
+ * ------------------------------------------------------------------------- */
+pre {
+ background-color: rgb(153, 153, 221);
+ padding: 0.25em;
+ padding-left: 5em;
+}
+
+/* ----------------------------------------------------------------------------
+ * Push all the images right, and put padding around them.
+ * ------------------------------------------------------------------------- */
+.java-image {
+ float: right;
+ padding: 0.5em;
+}
+
+/* ----------------------------------------------------------------------------
+ * The welcome message at the top of each page. Just an idea -- to be removed
+ * (both this and the HTML) if not seen as suitable.
+ * ------------------------------------------------------------------------- */
+#welcome {
+ width: 25em;
+ margin: 0.5em;
+ padding-left: 10em;
+}
+#welcome pre {
+ padding: 0.5em;
+ color: white;
+}
Added: public_html/doc/abcl-install-with-java.html
==============================================================================
--- (empty file)
+++ public_html/doc/abcl-install-with-java.html Fri May 22 17:46:35 2009
@@ -0,0 +1,630 @@
+<?xml version="1.0"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
+ "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
+<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
+<head>
+<title>Installing armedbear the Java way</title>
+<base href="">
+<link rel="stylesheet"
+ type="text/css"
+ href="abcl-css.css">
+<link rel="stylesheet"
+ type="text/css"
+ href="http://common-lisp.net/project/armedbear/style.css"/>
+</head>
+
+<body>
+<a name="top"></a>
+<div class="header"><h1>armedbear</h1></div>
+
+<a href="http://common-lisp.net/project/armedbear/">home</a>
+
+<div id="welcome">
+<pre>
+C:\temp\abcl\abcl-src-0.12.0\dist>java -jar abcl.jar
+Armed Bear Common Lisp 0.12.0
+Java 1.6.0_05 Sun Microsystems Inc.
+Java HotSpot(TM) Client VM
+Low-level initialization completed in 1.262 seconds.
+Startup completed in 4.556 seconds.
+Type ":help" for a list of available commands.
+CL-USER(1): (list 'welcome 'to 'lisp!)
+(WELCOME TO LISP!)
+CL-USER(2):
+</pre>
+</div>
+<h1>Installing the Java way</h1>
+
+<p>
+This page describes one way Java programmers can use to build an application.
+In addition to the Java development kit, which is described below, this way
+also uses a tool called Ant. Ant is a program familiar to Java developers. It
+performs the same sort of tasks that make does for C programmers, ie it
+provides a convenient means of managing the compilation and program building
+tasks that a complex application requires.
+</p>
+<p>
+Users of Java IDEs (Integrated Development Environment) such as
+<a href="http://www.eclipse.org/">Eclipse</a> or
+<a href="http://www.netbeans.org/">NetBeans</a> can build the ABCL JAR file
+within these environments. If you are using these tools you will have already
+downloaded the JDK, and these tools already have a version of Ant installed.
+See the documentation for these tools if you wish to use these to build the
+ABCL JAR file.
+</p>
+<p>
+To install ABCL from the source code as described on this page you need:
+</p>
+<ul>
+ <li>the Java runtime system, which will probably already be installed
+ on your machine;
+ </li>
+ <li>the <a href="abcl-pbdoc.html#jdk">Java development kit</a>, which
+ you have to download from Sun;
+ </li>
+ <li>and the <a href="abcl-pbdoc.html#ant">Ant</a> build tool for Java.
+ </li>
+</ul>
+
+<p>
+Once you have these pre-requisites sorted, you can then go ahead and
+<a href="#abcl">build ABCL</a>. If you wish to use Linux there are
+<a href="#linux">further steps</a> to perform.
+</p>
+<h2>The Java Runtime (JRE)</h2>
+
+<p>
+ABCL needs at least Java 1.5. How do you know if you have this or not? Well,
+for Windows users the quickest way to find out is to open a new command window
+(click <i>Start</i>, then <i>Run</i>, type <tt>cmd</tt> and click <i>OK</i>).
+At the command prompt type <tt>java -version</tt>. If you have the
+<tt>Java.exe</tt> executable in your path you will see output similar to this:
+
+<pre>
+C:\>java -version
+java version "1.6.0_11"
+Java(TM) SE Runtime Environment (build 1.6.0_11-b03)
+Java HotSpot(TM) Client VM (build 11.0-b16, mixed mode, sharing)
+</pre>
+
+<p>
+This will work because it is a version later than Java 1.5. However, if you get
+this response:
+</p>
+<pre>
+'java' is not recognized as an internal or external command,
+operable program or batch file.
+</pre>
+<p>
+It means one of two things, either you don't have Java installed, or if you do
+it is not on your path. To check which one it is type:
+</p>
+
+<pre>
+dir /s c:\java.exe
+</pre>
+<p>
+This command may take a long time to run, as it is doing a search of your hard
+drive, which may be large and have many files. (Of course you can, if you
+prefer, use the Windows search tool: <i>Start</i> -- <i>Search</i>.) A typical
+response may be:
+</p>
+<pre>
+C:\>dir /s \java.exe
+Volume in drive C is Windows
+Volume Serial Number is 7DDF-ABBD
+
+ Directory of C:\Program Files\Java\jre1.5.0_13\bin
+
+25/09/2007 19:26 49,248 java.exe
+ 1 File(s) 49,248 bytes
+
+ Directory of C:\Program Files\Java\jre1.6.0_03\bin
+
+24/09/2007 21:30 135,168 java.exe
+ 1 File(s) 135,168 bytes
+
+ Directory of C:\Program Files\Java\jre1.6.0_05\bin
+
+22/02/2008 00:23 135,168 java.exe
+ 1 File(s) 135,168 bytes
+</pre>
+<p>
+<img class="java-image" src="javajre.jpg">
+If you don't get any results then you don't have the Java runtime system
+installed. To install it go to <a href="http://java.com">java.com</a>, and
+click the big blue button that is on that page (it's not subtle, as you
+can see from the image at right!). Be aware that Java downloads are quite
+large, so if you need to install or upgrade your version of Java you should
+do this when you have access to decent Internet bandwidth.
+</p>
+<p>
+Your download will be an executable file. When you click the button there
+are full details on how to download and install the software on to your
+computer.
+</p>
+<p>
+The runtime system includes everything that you need to run a Java program.
+This means it has the core executables (eg <tt>java.exe</tt>), as well as
+all the supporting library files needed to make Java work with your
+particular operating system. However downloading the JRE alone is not
+enough...
+</p>
+<a href="#top">top</a>
+
+<a name="jdk"></a>
+<h2>The Java Development Kit (JDK)</h2>
+
+<p>
+The JDK is a different beast to the runtime environment (JRE). You need the
+JRE to actually execute Java code, and without it nothing will work. But if
+you want to go further and write your own Java programs, or compile Java
+code written by others, as we do here, then you will need more than the JRE
+-- you will need the Java development kit. The JDK gives you the basic
+tools to compile Java source code. How do you know if you have the JDK
+installed? Well again arguably the quickest way is to just search your hard
+drive for <tt>javac.exe</tt> (javac is the java compiler). If you get no
+response you don't have the JDK installed.
+</p>
+<p>
+As with the JRE the JDK is available for free from Sun. To download the
+<img class="java-image" src="javajdk.jpg">
+version you are interested in go to the Sun
+website, <a href="http://java.sun.com">java.sun.com</a>, click on the <i>Java
+SE</i> link to the right and then choose the JDK. Alternatively you can use
+their search form -- just enter "JDK". Java comes in various 'flavours': the
+SE is the Standard Edition, and is the one you want; the others are EE, which
+is the Enterprise Edition, and is used for creating web-based solutions using
+Java Bean and Servlet technologies; and ME is the Micro Edition, used to run
+Java on small devices such as phones and PDAs. [Now how cool would it be to
+have Lisp on your phone? There's a thought!]
+</p>
+
+<p>
+Make sure you download the JDK, not the JRE (unless of course you want to
+upgrade your current JRE to a different version). Sun offers the JDK with some
+of its other tools, such as NetBeans. NetBeans is an integrated development
+environment (IDE), which lets you edit your code in a window, and then run it,
+debug it, and manage your applications all within one package. There is a
+learning curve to NetBeans; it is a great IDE, but if you just want to get ABCL
+running you don't need all its bells and whistles.
+</p>
+<p>
+The JDK is even bigger than the JRE. For example, JDK 6 Update 12 is 73MB.
+Installation of the JDK follows the same process as for the JRE: save the
+executable to disk and then execute it. This does take quite some time, so
+please be patient.
+</p>
+<a href= "#top">top</a>
+
+<a name="ant"></a>
+<h2>Ant -- the Java build tool</h2>
+
+<p>
+Ant is an open source project managed by the Apache organisation, that is
+used to manage the compilation and building of larger Java projects. It's home
+<img class="java-image" src="ant-apache-org.jpg">
+page is at <a href="http://ant.apache.org">ant.apache.org</a>. To download
+this tool go to their <a href="http://ant.apache.org/bindownload.cgi">
+download</a> page. Choose the appropriate package for your platform (for
+example Windows users will select the zip archive). Extract the files from
+the package. Windows users can either user the built in feature of Windows
+explorer: double click on the zip file; in the window that pops up click
+<i>File</i> then <i>Extract All</i> (the fastest way to start Explorer:
+right-click on the <i>Start</i> button and click <i>Explore</i>).
+</p>
+<p>
+If you are on a Unix platform you can use <tt>tar</tt> to extract the files.
+As the package is a tar.gz file you can use the <tt>z</tt> option to tar to
+uncompress the archive, before extracting it. This command will both
+uncompress and extract the archive in one go (assuming, of course, that your
+archive is the 1.7.1 version of ant):
+</p>
+
+<pre>
+tar zxvf apache-ant-1.7.1-bin.tar.gz
+</pre>
+
+<p>
+The <a href="http://ant.apache.org/manual/index.html">installation
+instructions</a> are on the ant website. You should read through those to
+understand what needs to be done. The description below shows how these
+were applied when installing Ant on a Windows sytem. The first action that is
+required is to add the Ant bin directory to your system path. From a
+command prompt you can type the following commands. The first modifies the
+path variable, so the bin directory is visible from anywhere. The second
+command executes the <tt>ant</tt> executable.
+</p>
+
+<pre>
+C:\temp\ant\apache-ant-1.7.1>PATH=%PATH%;C:\temp\ant\apache-ant-1.7.1\bin
+
+C:\temp\ant\apache-ant-1.7.1>ant
+Unable to locate tools.jar. Expected to find it in C:\Program Files\Java\jre1.6.0_05\lib\tools.jar
+Buildfile: build.xml does not exist!
+Build failed
+C:\temp\ant\apache-ant-1.7.1>
+</pre>
+
+<p>
+Opps! No <tt>tool.jar</tt> file. Obviously this is part of the JDK, and
+so a quick search shows where it is. We can then set the <tt>JAVA_HOME</tt>
+and <tt>ANT_HOME</tt> environment variables and try again:
+</p>
+
+<pre>
+C:\temp\ant\apache-ant-1.7.1>dir \tools.jar /s
+ Volume in drive C has no label.
+ Volume Serial Number is 7DDF-ABBD
+ Directory of C:\Program Files\Java\jdk1.6.0_03\lib
+
+25/09/2007 00:11 12,171,847 tools.jar
+ 1 File(s) 12,171,847 bytes
+
+ Total Files Listed:
+ 3 File(s) 21,523,154 bytes
+ 0 Dir(s) 11,194,011,648 bytes free
+
+C:\temp\ant\apache-ant-1.7.1>set JAVA_HOME=C:\Program Files\Java\jdk1.6.0_03
+
+C:\temp\ant\apache-ant-1.7.1>set ANT_HOME=C:\temp\ant\apache-ant-1.7.1
+
+C:\temp\ant\apache-ant-1.7.1>ant
+Buildfile: build.xml does not exist!
+Build failed
+C:\temp\ant\apache-ant-1.7.1>ant -version
+Apache Ant version 1.7.1 compiled on June 27 2008
+C:\temp\ant\apache-ant-1.7.1>
+</pre>
+
+<p>
+Success, my build failed! (How oxymoronic is that?) Note that these changes are
+only temporary. When you exit out of the command line shell you will lose
+these settings. To preserve them for future shell sessions do this:
+</p>
+
+<ul>
+ <li>Click <i>Start</i> -- <i>Control Panel</i>;
+ </li>
+ <li>Double click the <i>System</i> item, and click on the
+ <i>Advanced</i> tab;
+ </li>
+ <li>Click the <i>Environment Variables</i> button;
+ </li>
+ <li>Find the <tt>PATH</tt> variable, and click <i>Edit</i>.
+ Move to the end of the path (click in the lower box and press
+ end), and add a semi-colon (<tt>;</tt>). Now append the path
+ to the Ant bin directory;
+ </li>
+ <li>Click the <i>New</i> system variable button, and enter the
+ variable name <tt>JAVA_HOME</tt> in the top box, with the
+ appropriate value in the lower box. Then click <i>OK</i>;
+ </li>Do the same again to set the <tt>ANT_HOME</tt> variable;
+ <li>Finally, close all the windows by clicking <i>OK</i>.
+ </li>
+</ul>
+<a href= "#top">top</a>
+
+<a name="abcl"></a>
+<h2>Build ABCL</h2>
+
+<p>
+OK, back to the build process. We are nearly there! You should change to the
+directory where you installed the ABCL source code. Once there you can run
+Ant against the <tt>build.xml</tt> file, which is the file that contains all
+the build instructions Ant needs to create the target Jar file. You specify the
+build file using the <tt>-f</tt> option. By default this file shows you a help
+message on how to use it:
+</p>
+
+<pre>
+C:\temp\ant\apache-ant-1.7.1>cd \temp\abcl\abcl-src-0.12.0
+
+C:\temp\abcl\abcl-src-0.12.0>ant -f build.xml
+Buildfile: build.xml
+
+help:
+ [echo] Main Ant targets:
+ [echo] abcl.compile
+ [echo] -- compile ABCL to C:\temp\abcl\abcl-src-0.12.0/build/classes
+ [echo] abcl.jar
+ [echo] -- create packaged C:\temp\abcl\abcl-src-0.12.0/dist/abcl.jar
+ [echo] abcl.wrapper
+ [echo] -- create executable wrapper for ABCL
+ [echo] abcl.source.zip abcl.source.tar
+ [echo] -- create source distributions in C:\temp\abcl\abcl-src-0.12.0/dist
+ [echo] abcl.clean
+ [echo] -- remove ABCL intermediate files
+ [echo] Corresponding targets for J exist, but currently aren't as well tested.
+ [echo]
+
+BUILD SUCCESSFUL
+Total time: 0 seconds
+C:\temp\abcl\abcl-src-0.12.0>
+</pre>
+
+<p>
+We want to create the JAR (Java ARchive) file. So we specify the <tt>abcl.jar</tt>
+target, hit RETURN, and wait. Note that a large proportion of the output has been
+removed from the listing below:
+</p>
+
+<pre>
+C:\temp\abcl\abcl-src-0.12.0>ant -f build.xml abcl.jar
+Buildfile: build.xml
+
+abcl.pre-compile:
+ [mkdir] Created dir: C:\temp\abcl\abcl-src-0.12.0\build
+ [mkdir] Created dir: C:\temp\abcl\abcl-src-0.12.0\build\classes
+ [echo] java.version: 1.6.0_03
+
+abcl.copy.lisp:
+ [copy] Copying 188 files to C:\temp\abcl\abcl-src-0.12.0\build\classes
+
+abcl.java.warning:
+ [echo] WARNING: Java version 1.6.0_03 not recommended.
+
+abcl.compile.java:
+ [javac] Compiling 257 source files to C:\temp\abcl\abcl-src-0.12.0\build\cla
+sses
+ [javac] Note: Some input files use unchecked or unsafe operations.
+ [javac] Note: Recompile with -Xlint:unchecked for details.
+
+abcl.fasls.uptodate:
+
+abcl.compile.lisp:
+ [java] Armed Bear Common Lisp 0.12.0 (built Mon Feb 23 2009 14:35:46 GMT)
+ [java] Java 1.6.0_03 Sun Microsystems Inc.
+ [java] Java HotSpot(TM) Client VM
+ [java] Low-level initialization completed in 0.731 seconds.
+ [java] Startup completed in 4.597 seconds.
+ [java] ; Compiling C:\temp\abcl\abcl-src-0.12.0\build\classes\org\armedbear\lisp\coerce.lisp ...
+ [java] ; (IN-PACKAGE #:SYSTEM)
+ [java] ; (DECLAIM (FTYPE # ...))
+ [java] ; (DEFUN COERCE-LIST-TO-VECTOR ...)
+ [java] ; (DECLAIM (FTYPE # ...))
+ [java] ; (DEFUN COPY-STRING ...)
+ [java] ; (DEFUN COERCE-ERROR ...)
+ [java] ; (DECLAIM (FTYPE # ...))
+ [java] ; (DEFUN COERCE-OBJECT-TO-AND-TYPE ...)
+ [java] ; (DEFUN COERCE ...)
+ [java] ; Wrote C:\temp\abcl\abcl-src-0.12.0\build\classes\org\armedbear\lisp\coerce.abcl (0.661 seconds)
+ [java] ; Compiling C:\temp\abcl\abcl-src-0.12.0\build\classes\org\armedbear\lisp\open.lisp ...
+ [java] ; (IN-PACKAGE #:SYSTEM)
+ [java] ; (DEFUN UPGRADED-ELEMENT-TYPE-BITS ...)
+ [java] ; (DEFUN UPGRADED-ELEMENT-TYPE ...)
+ [java] ; (DEFUN OPEN ...)
+ [java] ; Wrote C:\temp\abcl\abcl-src-0.12.0\build\classes\org\armedbear\lisp\open.abcl (0.641 seconds)
+ [java] ; Compiling C:\temp\abcl\abcl-src-0.12.0\build\classes\org\armedbear\lisp\dump-form.lisp ...
+ [java] ; (IN-PACKAGE "SYSTEM")
+ [java] ; (DECLAIM (FTYPE # ...))
+ [java] ; (DEFUN DUMP-CONS ...)
+ [java] ; (DECLAIM (FTYPE # ...))
+ [java] ; (DEFUN DUMP-VECTOR ...)
+ [java] ; (DECLAIM (FTYPE # ...))
+
+ ...
+ lots and lots of output here
+ ...
+
+ [java] ; (DEFMACRO WITH-SLOTS ...)
+ [java] ; Wrote C:\temp\abcl\abcl-src-0.12.0\build\classes\org\armedbear\lisp\with-slots.abcl (0.11 seconds)
+ [java] ; Compiling C:\temp\abcl\abcl-src-0.12.0\build\classes\org\armedbear\lisp\with-standard-io-syntax.lisp ...
+ [java] ; (IN-PACKAGE "SYSTEM")
+ [java] ; (DEFUN %WITH-STANDARD-IO-SYNTAX ...)
+ [java] ; (DEFMACRO WITH-STANDARD-IO-SYNTAX ...)
+ [java] ; Wrote C:\temp\abcl\abcl-src-0.12.0\build\classes\org\armedbear\lisp\with-standard-io-syntax.abcl (0.131 seconds)
+ [java] ; Compiling C:\temp\abcl\abcl-src-0.12.0\build\classes\org\armedbear\lisp\with-thread-lock.lisp ...
+ [java] ; (IN-PACKAGE "EXTENSIONS")
+ [java] ; (DEFMACRO WITH-THREAD-LOCK ...)
+ [java] ; Wrote C:\temp\abcl\abcl-src-0.12.0\build\classes\org\armedbear\lisp\with-thread-lock.abcl (0.08 seconds)
+ [java] ; Compiling C:\temp\abcl\abcl-src-0.12.0\build\classes\org\armedbear\lisp\write-sequence.lisp ...
+ [java] ; (IN-PACKAGE #:SYSTEM)
+ [java] ; (DEFUN WRITE-SEQUENCE ...)
+ [java] ; Wrote C:\temp\abcl\abcl-src-0.12.0\build\classes\org\armedbear\lisp\write-sequence.abcl (0.09 seconds)
+ [java] 283.678 seconds real time
+ [java] 71118074 cons cells
+
+abcl.compile:
+ [echo] Compiled ABCL with java version: 1.6.0_03
+
+abcl.stamp:
+
+abcl.pre-compile:
+ [echo] java.version: 1.6.0_03
+
+abcl.copy.lisp:
+
+abcl.java.warning:
+ [echo] WARNING: Java version 1.6.0_03 not recommended.
+
+abcl.compile.java:
+
+abcl.fasls.uptodate:
+
+abcl.compile.lisp:
+
+abcl.compile:
+ [echo] Compiled ABCL with java version: 1.6.0_03
+
+abcl.stamp.version:
+ [echo] Building ABCL version: 0.12.0
+
+abcl.stamp.hostname:
+ [echo] abcl.hostname: IBM-D396A533B48
+
+abcl.jar:
+ [jar] Building jar: C:\temp\abcl\abcl-src-0.12.0\dist\abcl.jar
+
+BUILD SUCCESSFUL
+Total time: 6 minutes 6 seconds
+C:\temp\abcl\abcl-src-0.12.0>
+</pre>
+<p>
+The last line of output is our target file:
+<tt>C:\temp\abcl\abcl-src-0.12.0\dist\abcl.jar</tt>. This is actually quite an
+intelligent JAR file, as it knows the name of the main Java class to run. This
+means quite a lot of the complexity of actually running the application is
+hidden from the user. So we can run the JAR file from the command line, using
+<tt>java.exe</tt> with only its <tt>-jar</tt> option:
+</p>
+
+<pre>
+C:\temp\abcl\abcl-src-0.12.0>dir C:\temp\abcl\abcl-src-0.12.0\dist\abcl.jar
+ Volume in drive C has no label.
+ Volume Serial Number is 7DDF-ABBD
+
+ Directory of C:\temp\abcl\abcl-src-0.12.0\dist
+
+23/02/2009 14:41 5,634,488 abcl.jar
+ 1 File(s) 5,634,488 bytes
+ 0 Dir(s) 11,169,034,240 bytes free
+
+C:\temp\abcl\abcl-src-0.12.0>java -jar C:\temp\abcl\abcl-src-0.12.0\dist\abcl.jar
+Armed Bear Common Lisp 0.12.0
+Java 1.6.0_05 Sun Microsystems Inc.
+Java HotSpot(TM) Client VM
+Low-level initialization completed in 2.413 seconds.
+Startup completed in 6.519 seconds.
+Type ":help" for a list of available commands.
+CL-USER(1):
+</pre>
+<p>Winner! We now have a working version of ABCL. Put the JAR file on a memory
+stick or CD and you have your own personal Lisp system available to you where
+ever you are. Now how cool is that?
+</p>
+
+<a name="linux"></a><a href="#top">top</a>
+<h2>Running ABCL on Linux</h2>
+<p>
+Because ABCL is a Java application, it should in theory be possible to run this
+on any computer where the Java Virtual Machine (JVM) is installed. However, if
+you wish to run this on Linux you need to perform the following actions to
+allow ABCL to run correctly. If you just run the JAR file, then you will find
+the arrow keys (ie up, down, left and right) do not function correctly.
+Instead, you get output as shown below (here the keys entered were, in order,
+up, right, down, and left):
+</p>
+
+<pre>
+Armed Bear Common Lisp 0.12.0
+Java 1.6.0 IBM Corporation
+IBM J9 VM
+Low-level initialization completed in 0.718 seconds.
+Startup completed in 2.411 seconds.
+Type ":help" for a list of available commands.
+CL-USER(1): ^[[A^[[C^[[B^[[D
+</pre>
+
+<p>
+Here you can see that you are not getting the correct response. You need to
+get the tool <a href="http://utopia.knoware.nl/~hlub/rlwrap/">rlwrap</a>. To
+use this you need to first install the software. Download the source code, the
+current version of which is in
+<a href="http://utopia.knoware.nl/~hlub/rlwrap/rlwrap-0.30.tar.gz">
+rlwrap-0.30.tar.gz</a>. Extract the contents to your system. For example, if
+you want to extract into <tt>/tmp</tt> save the file to somewhere on your
+system, and then run this command:
+</p>
+
+<pre>
+cd /tmp
+tar zxvf /path/to/rlwrap-0.30.tar.gz
+</pre>
+
+<p>
+In this case it will create the directory <tt>/tmp/rlwrap-0.30.tar.gz</tt>
+To perform the remaining commands you should <tt>su</tt> to root. This will then
+allow you to intall the binary in <tt>/usr/local/bin</tt>. Run the following
+commands as root:
+</p>
+<pre>
+cd /tmp/rlwrap-0.30
+./configure
+make
+make install
+</pre>
+
+
+<p>
+Now we need to create the file <tt>.abcl_completions</tt>. To do this save
+the following Lisp code to a file, say <tt>test.lisp</tt>:
+</p>
+
+<pre>
+(do-all-symbols (sym)
+ (let ((package (symbol-package sym)))
+ (cond
+ ((not (fboundp sym)))
+ ((or (eql #.(find-package :cl) package)
+ (eql #.(find-package :extensions) package)
+ (eql #.(find-package :cl-user) package))
+ (pushnew (symbol-name sym) symbols))
+ ((eql #.(find-package :keyword) package)
+ (pushnew (concatenate 'string ":" (symbol-name sym)) symbols))
+ (package
+ (pushnew (concatenate 'string
+ (package-name package)
+ ":"
+ (symbol-name sym))
+ symbols)))))
+(with-open-file (output #.(concatenate 'string
+ (getenv "HOME")
+ "/.abcl_completions")
+ :direction :output :if-exists :overwrite
+ :if-does-not-exist :create)
+ (format output "~{~(~A~)~%~}" (sort symbols #'string<)))
+(quit))
+</pre>
+
+<p>
+Now create the <tt>.abcl_completions</tt> by running this command:
+</p>
+
+<pre>
+java -jar abcl.jar --load test.lisp
+</pre>
+
+<p>
+The final <tt>(quit)</tt> ensures this Lisp command returns you to the
+command line when it completes. It creates the <tt>.abcl_completions</tt>
+file in your home directory. We still need to do one more thing, before we
+create the <tt>lisp</tt> executable. If you need to know the path to the
+<tt>abcl.jar</tt> file If you don't know what it is you can search for it:
+</p>
+
+<pre>
+find / 2>/dev/null -name abcl.jar
+</pre>
+
+<p>
+If this does not return any names, try replacing <tt>abcl.jar</tt> with
+<tt>abcl\*.jar</tt>, as the JAR file may have a version number included.
+Consider that the filename returned is <tt>/opt/abcl/abcl.jar</tt>, then we will
+need the line <tt>ABCL_JAR=/opt/abcl/abcl.jar</tt> in our script. So bearing
+this in mind, we can now create a script file that we can call
+<tt>/usr/local/bin/lisp</tt>:
+</p>
+
+<pre>
+#!/bin/sh
+ABCL_JAR=/opt/abcl/abcl.jar # Use your own path here.
+JAVA=$(which java)
+ABCL="$JAVA -server -Xrs -cp $ABCL_JAR org.armedbear.lisp.Main"
+if [ $# -eq 0 ]; then
+ exec rlwrap -b "[]()'\" " --remember -c -f ~/.abcl_completions \
+ -H ~/.abcl_history -s 1000000 $ABCL
+else
+ exec $ABCL "$@"
+fi
+</pre>
+
+<p>
+Now when you use this <tt>lisp</tt> command you will get the keystroke behaviour
+you expect.
+</p>
+
+<a href="#top">top</a>
+<a href="http://common-lisp.net/project/armedbear/">home</a>
+</body>
+</html>
Added: public_html/doc/abcl-lisp-java-integration.html
==============================================================================
--- (empty file)
+++ public_html/doc/abcl-lisp-java-integration.html Fri May 22 17:46:35 2009
@@ -0,0 +1,89 @@
+<?xml version="1.0"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
+ "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
+<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
+<head>
+<title>Installing armedbear the Java way</title>
+<base href="">
+<link rel="stylesheet"
+ type="text/css"
+ href="abcl-css.css">
+<link rel="stylesheet"
+ type="text/css"
+ href="http://common-lisp.net/project/armedbear/style.css"/>
+</head>
+
+<body>
+<a name="top"></a>
+<div class="header"><h1>armedbear</h1></div>
+
+<a href="http://common-lisp.net/project/armedbear/">home</a>
+
+<div id="welcome">
+<pre>
+C:\temp\abcl\abcl-src-0.12.0\dist>java -jar abcl.jar
+Armed Bear Common Lisp 0.12.0
+Java 1.6.0_05 Sun Microsystems Inc.
+Java HotSpot(TM) Client VM
+Low-level initialization completed in 1.262 seconds.
+Startup completed in 4.556 seconds.
+Type ":help" for a list of available commands.
+CL-USER(1): (list 'welcome 'to 'lisp!)
+(WELCOME TO LISP!)
+CL-USER(2):
+</pre>
+</div>
+<h1>Integrating Lisp into Java</h1>
+
+<p>
+This page describes you can use ABCL to integrate Lisp into a Java application.
+Why is this useful? Well, you get the best of both worlds -- you get the
+power of Java and can call upon the very large number of existing tools and
+programs that have been implemented in Java, and merge this with the incredible
+poower of Lisp. So if you have a useful Lisp application rather you no longer
+need to rewrite it in Java. Simply call the ABCL Lisp interpreter to execute
+its Lisp code.
+</p>
+
+<h2>How to compile your Java-Lisp code</h2>
+<p>
+Your Java code will use the special classes provided by ABCL to allow it to
+access the methods needed to interact with your Lisp code. This means that the
+ABCL JAR file needs to appear in your CLASSPATH. Depending on how you build
+your application will depend on the method you choose to use. The simplest
+method is to use the <tt>-cp</tt> option to the Java compiler. Alternatively
+you can set the <tt>CLASSPATH</tt> environment variable, thus simplifying the
+Java command line. Finally you may set the CLASSPATH in your IDE, or using the
+Ant <tt><classpath></tt> tag. To make this more concrete consider you
+have a Java file called <tt>myapp.java</tt>. Then if you use the <tt>javac</tt>
+command to run the Java compiler, your command may look like this (we are, of
+course, describing a Windows platform):
+</p>
+<pre>
+javac -cp c:\path\to\abcl.jar myapp.java
+</pre>
+<p>
+Of course if you have other elements in your classpath you will have to make
+the path more complex to take this into account. So, for example, if you have
+other JAR files in <tt>c:\apps\java-libs</tt>, and the JAR file
+<tt>c:\3rd-party-apps\lib\special-tools.jar</tt>, the command will have to be
+modified to look like this:
+</p>
+<pre>
+javac -cp c:\path\to\abcl.jar;c:\apps\java-libs;c:\3rd-party-apps\lib\special-tools.jar myapp.java
+</pre>
+<p>
+It is clear from the above that the command is getting more and more complex.
+As you add more classes to the commmand line so it will grow, and perhaps
+exceed the maximum command line length. The general solution to this is to
+take the class path information out of the command and store it in an
+environment variable called <tt>CLASSPATH</tt>:
+</p>
+<pre>
+set CLASSPATH=c:\path\to\abcl.jar;c:\apps\java-libs;c:\3rd-party-apps\lib\special-tools.jar
+javac myapp.java
+</pre>
+<p>
+</p>
+</body>
+</html>
Added: public_html/doc/abcl-start.html
==============================================================================
--- (empty file)
+++ public_html/doc/abcl-start.html Fri May 22 17:46:35 2009
@@ -0,0 +1,208 @@
+<?xml version="1.0"?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
+ "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
+<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
+<head>
+<title>Installing armedbear the Java way</title>
+<base href="">
+<link rel="stylesheet"
+ type="text/css"
+ href="abcl-css.css">
+<link rel="stylesheet"
+ type="text/css"
+ href="http://common-lisp.net/project/armedbear/style.css"/>
+</head>
+
+<body>
+<a name="top"></a>
+<div class="header"><h1>armedbear</h1></div>
+
+<a href="http://common-lisp.net/project/armedbear/">home</a>
+
+<div id="welcome">
+<pre>
+C:\temp\abcl\abcl-src-0.12.0\dist>java -jar abcl.jar
+Armed Bear Common Lisp 0.12.0
+Java 1.6.0_05 Sun Microsystems Inc.
+Java HotSpot(TM) Client VM
+Low-level initialization completed in 1.262 seconds.
+Startup completed in 4.556 seconds.
+Type ":help" for a list of available commands.
+CL-USER(1): (list 'welcome 'to 'lisp!)
+(WELCOME TO LISP!)
+CL-USER(2):
+</pre>
+</div>
+<h1>Starting ABCL</h1>
+
+<p>
+When you start ABCL you can pass it command line arguments. Currently (at
+version 12) it supports the following arguments:
+</p>
+
+<ul>
+ <li><tt>--noinit</tt> If you have defined an <a href="#noinit">
+ initialisation file</a> you can use this option to prevent this file
+ from being processed when the application starts.
+ </li>
+ <li><tt>--noinform</tt> <a href="#noinform">Suppresses the
+ information</a> that is normally printed when the application starts.
+ </li>
+ <li><tt>--batch</tt> See <a href="#batch">batch</a> below.
+ </li>
+ <li><tt>--eval</tt> See <a href="#eval">eval</a> below.This requires
+ an argument.
+ </li>
+ <li><tt>--load</tt> See <a href="#load">load</a> below. This requires
+ an argument.
+ </li>
+ <li><tt>--load-system-file</tt> See
+ <a href="#loadsysfile">load-system-file</a> below. This
+ requires an argument.
+ </li>
+</ul>
+
+<p>
+</p>
+
+<a name="noinform"></a>
+<h2>The --noinform option</h2>
+<p>
+The <tt>--noinform</tt> option stops the normal startup messsages from appearing.
+A normal startup will look something like this:
+</p>
+
+<pre>
+C:\temp\abcl\abcl-src-0.12.0\dist>java -jar abcl.jar
+Armed Bear Common Lisp 0.12.0
+Java 1.6.0_05 Sun Microsystems Inc.
+Java HotSpot(TM) Client VM
+Low-level initialization completed in 1.262 seconds.
+Startup completed in 4.556 seconds.
+Type ":help" for a list of available commands.
+CL-USER(1):
+</pre>
+
+<p>
+To stop the above messages from appearing simply add the <tt>--noinform</tt>
+option to the end of the comand line:
+</p>
+
+<pre>
+C:\temp\abcl\abcl-src-0.12.0\dist>java -jar abcl.jar --noinform
+CL-USER(1):
+</pre>
+
+<a name="batch"></a>
+<a href="#top">top</a>
+<h2>The --batch option</h2>
+<p>
+<i>It is currently not known what this option does.</i>
+</p>
+
+
+<a name="eval"></a>
+<a href="#top">top</a>
+<h2>The --eval option</h2>
+<p>
+<i>It is currently not known what this option does.</i>
+No idea what this does, but under Linux it seems to mess up the keystrokes.
+If you start your <a href="abcl-install-with-java.html#linux">Lisp under
+Linux</a>, the keystrokes are not recognised. Consider starting ABCL Lisp with
+this command: <tt>lisp --eval "(+ 1 2)"</tt>. When you try to use the arrow
+keys (up, right, down and left) you get:
+</p>
+
+<pre>
+[localhost ~]$ lisp --eval "(+ 1 2)"
+Armed Bear Common Lisp 0.12.0
+Java 1.6.0 IBM Corporation
+IBM J9 VM
+Low-level initialization completed in 0.639 seconds.
+Startup completed in 2.221 seconds.
+Type ":help" for a list of available commands.
+CL-USER(1): ^[[A^[[C^[[B^[[D
+</pre>
+
+
+<a name="load"></a>
+<a href="#top">top</a>
+<h2>The --load option</h2>
+<p>
+This option must be followed by a filename. It allows you to load a file when
+the Lisp system starts. Consider the following Lisp file; it conists of a
+single form:
+</p>
+
+<pre>
+(format t "Hello world")
+</pre>
+
+<p>
+If this file is saved in your home directory in Linux and is called
+<tt>test.lisp</tt>, you can load the file into Lisp with <tt>lisp --load
+~/test.lisp</tt>. Now, when Lisp starts up you will see:
+</p>
+
+<pre>
+[localhost ~]$ pwd
+/home/test-user
+[localhost ~]$ cat test.lisp
+(format t "Hello World!")
+[localhost ~]$ lisp --load ~/test.lisp
+Armed Bear Common Lisp 0.12.0
+Java 1.6.0 IBM Corporation
+IBM J9 VM
+Low-level initialization completed in 0.686 seconds.
+Startup completed in 2.325 seconds.
+Hello World!
+Type ":help" for a list of available commands.
+CL-USER(1):
+</pre>
+
+<p>
+</p>
+
+<a name="loadsysfile"></a>
+<a href="#top">top</a>
+<h2>The --load-system-file option</h2>
+<p>
+This looks for lisp files. If there is no extension it tries an extension of
+<tt>.abcl</tt>, <tt>.lisp</tt> (from <tt>Load.loadSystemFile()</tt>)
+</p>
+
+
+<a name="noinit"></a><a href="#top">top</a>
+<h2>ABCL initialisation file</h2>
+<p>
+ABCL supports an initialisation file, with the expected name of <tt>.abclrc</tt>
+The system looks for this file in the directory specified by the Java system
+property <tt>user.home</tt>. This property should point to the user's home
+directory. If this file does not exist, then for Windows users the next place
+to look for it is in the root directory of the <tt>c:</tt> drive:
+<tt>C:\.abclrc</tt>. If this does not exist, the file <tt>.ablrc</tt> in the
+user's home directory is tried next; this option is depcrecated and only exists
+for backward compatibility. You should use <tt>.abclrc</tt> instead. Finally
+if all the above fail the last filename searched for is <tt>.ablisprc</tt>.
+</p>
+
+<p>
+As an example, make sure you are in your home directory, and create a file
+called <tt>.abclrc</tt>. To demonstrate that this works enter the following
+Lisp form into this file: <tt>(setf x 3)</tt>. This will set the special
+variable <tt>x</tt> to the value 3. Now simply start Lisp, and query the
+variable <tt>x</tt>:
+</p>
+
+<pre>
+C:\temp\abcl\abcl-src-0.12.0\dist>java -jar abcl.jar
+CL-USER(1): x
+3
+</pre>
+
+<p>
+The initialisation file is loaded before any other file is loaded.
+</p>
+
+</body>
+</html>
Added: public_html/doc/ant-apache-org.jpg
==============================================================================
Binary file. No diff available.
Added: public_html/doc/getting-started.txt
==============================================================================
--- (empty file)
+++ public_html/doc/getting-started.txt Fri May 22 17:46:35 2009
@@ -0,0 +1,48 @@
+So now you have the ABCL Lisp system compiled, and can run the resulting JAR
+file to give you a Lisp prompt, what do you do with it?
+
+* First, get that JAR file onto a pendrive. You can take Lisp with you
+ where-ever you go. Now how cool is that?
+* Lisp IS NOT an artificial intelligence (AI) programming language. It IS a
+ general purpose programming language, can can, as well, do AI stuff.
+* Lisp is a refreshing alternative to the Fortran-like languages you see all
+ around you (C, C++, Java, PHP, etc). Its syntax is weird and different,
+ and very flexible (well to be honest Lisp doesn't really have any
+ syntax, which is why it is so flexible).
+* Start by trying to get into the Lisp way of programming. Try to write code
+ in Lisp instead of your current programming language. For example, try
+ to write Lisp versions of what you would do in Java.
+* Lisp is a big language, but once you have learned a small element, the rest
+ of the language will become obvious -- it has everything you need. As
+ your knowledge grows, so you will see there is an answer in Lisp. (This
+ is just like Java or C++, once you know the basics you can simply write
+ your own, or hunt down the ready-made solutions that the language has
+ -- somewhere.
+* Lisp is very flexible. You won't see this until you've been using it awhile,
+ but you will find that it is the most natural way to think through
+ solutions.
+* There are lots of Lisp textbooks around. Don't be worried if these are 20
+ years old or more. You will still say 'wow' when you see what sort of
+ things are in these books. The things you can do with functions is
+ amazing -- but you don't know this because your current languages don't
+ support it, so you don't think that way.
+* Finally, write Lisp code. Everytime you have to solve a problem in Java or
+ C++, think about how you could do it in Lisp.
+
+Java/Lisp examples.
+
+-------------------------------------------------------------------------------
+Count to 10:
+Java
+
+ for(i = 1; i < 11; i++) {
+ System.out.println("i=" + i);
+ }
+
+Lisp
+
+ (dotimes (x 10)
+ (print (1+ x)))
+
+-------------------------------------------------------------------------------
+
Added: public_html/doc/javajdk.jpg
==============================================================================
Binary file. No diff available.
Added: public_html/doc/javajre.jpg
==============================================================================
Binary file. No diff available.
More information about the armedbear-cvs
mailing list