mthl
/
texinfo


			
				
					
						
						
							123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407
							<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<!DOCTYPE html><html xmlns="http://www.w3.org/1999/xhtml" xmlns:epub="http://www.idpf.org/2007/ops" xmlns:m="http://www.w3.org/1998/Math/MathML" xmlns:pls="http://www.w3.org/2005/01/pronunciation-lexicon" xmlns:ssml="http://www.w3.org/2001/10/synthesis" xmlns:svg="http://www.w3.org/2000/svg">
  <head>
    <title>Compiling to byte-code</title>
    <link rel="stylesheet" type="text/css" href="docbook-epub.css"/>
    <link rel="stylesheet" type="text/css" href="kawa.css"/>
    <script src="kawa-ebook.js" type="text/javascript"/>
    <meta name="generator" content="DocBook XSL-NS Stylesheets V1.79.1"/>
    <link rel="prev" href="Overall-Index.xhtml" title="Index"/>
    <link rel="next" href="Syntax.xhtml" title="Syntax"/>
  </head>
  <body>
    <header/>
    <section class="sect1" title="Compiling to byte-code" epub:type="subchapter" id="Compiling">
      <div class="titlepage">
        <div>
          <div>
            <h2 class="title" style="clear: both">Compiling to byte-code</h2>
          </div>
        </div>
      </div>
      <p>All Scheme functions and source files are invisibly compiled
into internal Java byte-codes.
(A traditional interpreter is used for macro-expansion.
Kawa used to also interpret “simple” expressions in interactive mode,
but always compiling makes things more consistent, and allows for
better stack traces on errors.)
</p>
      <p>To save speed when loading large Scheme source files, you probably
want to pre-compile them and save them on your local disk.
There are two ways to do this.
</p>
      <p>You can compile a Scheme source file to a single archive file.
You do this using the <code class="literal">compile-file</code> function.
The result is a single file that you can move around and <code class="literal">load</code>
just like the <code class="literal">.scm</code> source file.  You just specify the name
of the archive file to the <code class="literal">load</code> procedure.
Currently, the archive is a "zip" archive and has extension ".zip";
a future release will probably use "Java Archive" (jar) files.
The advantage of compiling to an archive is that it is simple
and transparent.
</p>
      <p>Alternatively, you can compile a Scheme source file to a
collection of ‘<code class="literal">.class</code>’ files.
You then use the standard Java class loading mechanism to load the code.
The compiled class files do have to be installed somewhere
in the <code class="literal">CLASSPATH</code>.
</p>
      <section class="sect2" title="Compiling to a set of .class files" epub:type="division" id="Files-compilation">
        <div class="titlepage">
          <div>
            <div>
              <h3 class="title">Compiling to a set of .class files</h3>
            </div>
          </div>
        </div>
        <p>Invoking ‘<code class="literal">kawa</code>’ (or ‘<code class="literal">java kawa.repl</code>’) with
the ‘<code class="literal">-C</code>’ flag will compile
a ‘<code class="literal">.scm</code>’ source file into one or more ‘<code class="literal">.class</code>’ files:
</p>
        <pre class="screen">kawa --main -C myprog.scm
</pre>
        <p>You run it as follows:
</p>
        <pre class="screen">kawa [-d <em class="replaceable"><code>outdirectory</code></em>] [-P <em class="replaceable"><code>prefix</code></em>] [-T <em class="replaceable"><code>topname</code></em>] [--main | --applet | --servlet] -C <em class="replaceable"><code>infile</code></em> ...
</pre>
        <p>Note the ‘<code class="literal">-C</code>’ must come last, because ‘<code class="literal">Kawa</code>’ processes the
arguments and options in order,
</p>
        <p>Here:
</p>
        <div class="variablelist" epub:type="list">
          <dl class="variablelist">
            <dt class="term"><code class="literal">-C <em class="replaceable"><code>infile</code></em> ...</code>
</dt>
            <dd>
              <p>The Scheme source files we want to compile.
</p>
            </dd>
            <dt class="term"><code class="literal">-d <em class="replaceable"><code>outdirectory</code></em></code>
</dt>
            <dd>
              <p>The directory under which the resulting ‘<code class="literal">.class</code>’ files will be.
The default is the current directory.
</p>
            </dd>
            <dt class="term"><code class="literal">-P <em class="replaceable"><code>prefix</code></em></code>
</dt>
            <dd>
              <p>A string to prepend to the generated class names.
The default is the empty string.
</p>
            </dd>
            <dt class="term"><code class="literal">-T <em class="replaceable"><code>topname</code></em></code>
</dt>
            <dd>
              <p>The name of the "top" class - i.e. the one that contains the code
for the top-level expressions and definitions.
The default is generated from the <em class="replaceable"><code>infile</code></em> and <em class="replaceable"><code>prefix</code></em>.
</p>
            </dd>
            <dt class="term"><code class="literal">--main</code>
</dt>
            <dd>
              <p>Generate a <code class="literal">main</code> method so that the resulting "top" class can
be used as a stand-alone application. See <a class="link" href="Compiling.xhtml#Application-compilation" title="Compiling to a standalone application">Application compilation</a>.
</p>
            </dd>
            <dt class="term"><code class="literal">--applet</code>
</dt>
            <dd>
              <p>The resulting class inherits from <code class="literal">java.applet.Applet</code>,
and can be used as an applet.  See <a class="link" href="Compiling.xhtml#Applet-compilation" title="Compiling to an applet">Applet compilation</a>.
</p>
            </dd>
            <dt class="term"><code class="literal">--servlet</code>
</dt>
            <dd>
              <p>The resulting class implements <code class="literal">javax.servlet.http.HttpServlet</code>,
and can be used as a servlet in a servlet container like Tomcat.
</p>
            </dd>
          </dl>
        </div>
        <p>When you actually want to load the classes, the <em class="replaceable"><code>outdirectory</code></em>
must be in your ‘<code class="literal">CLASSPATH</code>’.
You can use the <code class="literal">require</code> syntax or the <code class="literal">load</code> function to load the code,
by specifying the top-level class, either as a file name
(relative to <em class="replaceable"><code>outdirectory</code></em>) or as a class name.
E.g. if you did:
</p>
        <pre class="screen">kawa -d /usr/local/share/java -P my.lib. -T foo -C foosrc.scm
</pre>
        <p>you can use either:
</p>
        <pre class="screen">(require my.lib.foo)
</pre>
        <p>or:
</p>
        <pre class="screen">(load "my.lib.foo")
</pre>
        <p>Using <code class="literal">require</code> is preferred as it imports the definitions
from <code class="literal">my.lib.foo</code> into the compile-time environment,
while <code class="literal">load</code> only imports the definitions into the run-time environment.
</p>
        <p>If you are compiling a Scheme source file (say ‘<code class="literal">foosrc.scm</code>’)
that uses macros defined in some other file (say ‘<code class="literal">macs.scm</code>’),
you need to make sure the definitions are visible to the compiler.
One way to do that is with the ‘<code class="literal">-f</code>’:
</p>
        <pre class="screen">kawa -f macs.scm -C foosrc.scm
</pre>
        <p>Many of the options <a class="link" href="Options.xhtml" title="Command-line arguments">described earlier</a> are
relevant when compiling.  Commonly used options include language selection,
the <code class="literal">--warn-xxx</code> options, and <code class="literal">--full-tailcalls</code>.
</p>
      </section>
      <section class="sect2" title="Compiling to an archive file" epub:type="division" id="Archive-compilation">
        <div class="titlepage">
          <div>
            <div>
              <h3 class="title">Compiling to an archive file</h3>
            </div>
          </div>
        </div>
        <p class="synopsis" kind="Procedure"><span class="kind">Procedure</span><span class="ignore">: </span><a id="idm139667879904288" class="indexterm"/> <code class="function">compile-file</code> <em class="replaceable"><code>source-file</code></em> <em class="replaceable"><code>compiled-archive</code></em></p>
        <div class="blockquote">
          <blockquote class="blockquote">
            <p>Compile the <em class="replaceable"><code>source-file</code></em>, producing a <code class="literal">.zip</code> archive
<em class="replaceable"><code>compiled-file</code></em>.
</p>
            <p>For example, to byte-compile a file ‘<code class="literal">foo.scm</code>’ do:
</p>
            <pre class="screen">(compile-file "foo.scm" "foo")
</pre>
            <p>This will create ‘<code class="literal">foo.zip</code>’, which contains
byte-compiled JVM <code class="literal">.class</code> files.
You can move this file around, without worrying about class paths.
To load the compiled file, you can later <code class="literal">load</code> the
named file, as in either <code class="literal">(load "foo")</code> or <code class="literal">(load "foo.zip")</code>.
This should have the same effect as
loading ‘<code class="literal">foo.scm</code>’, except you will get the faster byte-compiled versions.
</p>
          </blockquote>
        </div>
      </section>
      <section class="sect2" title="Compiling using Ant" epub:type="division" id="Compiling-using-Ant">
        <div class="titlepage">
          <div>
            <div>
              <h3 class="title">Compiling using Ant</h3>
            </div>
          </div>
        </div>
        <a id="idm139667879893216" class="indexterm"/>
        <p>Many Java projects use <a class="ulink" href="http://ant.apache.org" target="_top">Ant</a>
for building Java projects.  Kawa includes a <code class="literal">&lt;kawac&gt;</code>
Ant task that simplifies compiling Kawa source files to classes.
See the <code class="literal">build.xml</code> in the Kawa source distribution for examples.
See the <a class="ulink" href="ant-kawac.html" target="_top"><code class="literal">kawac</code> task documentation</a> for details.
</p>
      </section>
      <section class="sect2" title="Compiling to a standalone application" epub:type="division" id="Application-compilation">
        <div class="titlepage">
          <div>
            <div>
              <h3 class="title">Compiling to a standalone application</h3>
            </div>
          </div>
        </div>
        <p>A Java application is a Java class with a special method
(whose name is <code class="literal">main</code>).  The application can be invoked directly
by naming it in the Java command.
If you want to generate an application from a Scheme program,
create a Scheme source file with the definitions you need, plus
the top-level actions that you want the application to execute. 
</p>
        <p>For example, assuming your Scheme file is 
<code class="literal">MyProgram.scm</code>, you  have two ways at your disposal to 
compile this Scheme program to a standalone application:
</p>
        <div class="orderedlist" epub:type="list">
          <ol class="orderedlist" type="1">
            <li class="listitem" epub:type="list-item">
              <p>Compile
in the regular way described in the previous section, but add the
<code class="literal">--main</code> option.
</p>
              <pre class="screen">kawa --main -C MyProgram.scm
</pre>
              <p>The <code class="literal">--main</code> option will compile all Scheme programs
received in arguments to standalone applications.
</p>
            </li>
            <li class="listitem" epub:type="list-item">
              <p>Compile
in the regular way decribed in the previous section, but add the 
<code class="literal">main: #t</code> module compile option to your module.
</p>
              <pre class="screen">;; MyProgram.scm
(module-name &lt;myprogram&gt;)
(module-compile-options main: #t)
</pre>
              <pre class="screen">kawa -C MyProgram.scm
</pre>
              <p>This way you can compile multiple Scheme programs at once, and
still control which one(s) will compile to standalone application(s).
</p>
            </li>
          </ol>
        </div>
        <p>Both methods will create a <code class="literal">MyProgram.class</code> which you can either
<code class="literal">load</code> (as described in the previous section), or invoke as an application:
</p>
        <pre class="screen">java MyProgram [<em class="replaceable"><code>args</code></em>]
</pre>
        <p>Your Scheme program can access the command-line arguments <em class="replaceable"><code>args</code></em>
by using the global variable ‘<code class="literal">command-line-arguments</code>’,
or the R6RS function ‘<code class="literal">command-line</code>’.
</p>
        <p>If there is no explicit <code class="literal">module-export</code> in a module compiled
with <code class="literal">--main</code> then no names are exported.  (The default
otherwise is for all names to be exported.)
</p>
      </section>
      <section class="sect2" title="Compiling to an applet" epub:type="division" id="Applet-compilation">
        <div class="titlepage">
          <div>
            <div>
              <h3 class="title">Compiling to an applet</h3>
            </div>
          </div>
        </div>
        <p>An applet is a Java class that inherits from <code class="literal">java.applet.Applet</code>.
The applet can be downloaded and run in a Java-capable web-browser.
To generate an applet from a Scheme program, write the Scheme
program with appropriate definitions of the functions ‘<code class="literal">init</code>’,
‘<code class="literal">start</code>’, ‘<code class="literal">stop</code>’ and ‘<code class="literal">destroy</code>’.  You must declare these
as zero-argument functions with a <code class="literal">&lt;void&gt;</code> return-type.
</p>
        <p>Here is an example, based on the scribble applet in Flanagan’s
"Java Examples in a Nutshell" (O’Reilly, 1997):
</p>
        <pre class="screen">(define-private last-x 0)
(define-private last-y 0)

(define (init) :: void
  (let ((applet (this)))
    (applet:addMouseListener
     (object (java.awt.event.MouseAdapter)
	     ((mousePressed e)
	      (set! last-x (e:getX))
	      (set! last-y (e:getY)))))
    (applet:addMouseMotionListener
     (object (java.awt.event.MouseMotionAdapter)
	     ((mouseDragged e)
	      (let ((g (applet:getGraphics))
		    (x (e:getX))
		    (y (e:getY)))
		(g:drawLine last-x last-y x y)
		(set! last-x x)
		(set! last-y y)))))))

(define (start) :: void (format #t "called start.~%~!"))
(define (stop) :: void (format #t "called stop.~%~!"))
(define (destroy) :: void (format #t "called destroy.~%~!"))
</pre>
        <p>You compile the program with the ‘<code class="literal">--applet</code>’ flag in addition to the
normal ‘<code class="literal">-C</code>’ flag:
</p>
        <pre class="screen">java kawa.repl --applet -C scribble.scm
</pre>
        <p>You can then create a ‘<code class="literal">.jar</code>’ archive containing your applet:
</p>
        <pre class="screen">jar cf scribble.jar scribble*.class
</pre>
        <p>Finally, you create an ‘<code class="literal">.html</code>’ page referencing your applet
and its support <code class="literal">jar</code>s:
</p>
        <pre class="screen">&lt;html&gt;&lt;head&gt;&lt;title&gt;Scribble testapp&lt;/title&gt;&lt;/head&gt;
&lt;body&gt;&lt;h1&gt;Scribble testapp&lt;/h1&gt;
You can scribble here:
&lt;br&gt;
&lt;applet code="scribble.class" archive="scribble.jar, kawa-2.92_invoke.jar" width=200 height=200&gt;
Sorry, Java is needed.&lt;/applet&gt;
&lt;/body&gt;&lt;/html&gt;
</pre>
        <p>The problem with using Kawa to write applets is that the Kawa <code class="literal">.jar</code>
file is quite big, and may take a while to download over a network connection.
Some possible solutions:
</p>
        <div class="itemizedlist" epub:type="list">
          <ul class="itemizedlist" style="list-style-type: disc; ">
            <li class="listitem" epub:type="list-item">
              <p>Try to strip out of the Kawa <code class="literal">.jar</code> any classes your
applet doesn’t need.
</p>
            </li>
            <li class="listitem" epub:type="list-item">
              <p>Java 2 provides a mechanism to install a <a class="ulink" href="http://java.sun.com/docs/books/tutorial/ext/basics/download.html" target="_top">download extension</a>.
</p>
            </li>
            <li class="listitem" epub:type="list-item">
              <p>Consider some alternative to applets, such as
<a class="ulink" href="http://java.sun.com/products/javawebstart/" target="_top">Java Web Start</a>.
</p>
            </li>
          </ul>
        </div>
      </section>
      <section class="sect2" title="Compiling to a native executable" epub:type="division" id="Compiling-to-executable">
        <div class="titlepage">
          <div>
            <div>
              <h3 class="title">Compiling to a native executable</h3>
            </div>
          </div>
        </div>
        <p>In the past it was possible to compile a Scheme program to native code using GCJ.
However, using GCJ with Kawa is no longer supported,
as GCJ is no longer being actively maintained.
</p>
      </section>
    </section>
    <footer>
      <div class="navfooter">
        <ul>
          <li>
            <b class="toc">
              <a href="Compiling.xhtml#Files-compilation">Compiling to a set of .class files</a>
            </b>
          </li>
          <li>
            <b class="toc">
              <a href="Compiling.xhtml#Archive-compilation">Compiling to an archive file</a>
            </b>
          </li>
          <li>
            <b class="toc">
              <a href="Compiling.xhtml#Compiling-using-Ant">Compiling using Ant</a>
            </b>
          </li>
          <li>
            <b class="toc">
              <a href="Compiling.xhtml#Application-compilation">Compiling to a standalone application</a>
            </b>
          </li>
          <li>
            <b class="toc">
              <a href="Compiling.xhtml#Applet-compilation">Compiling to an applet</a>
            </b>
          </li>
          <li>
            <b class="toc">
              <a href="Compiling.xhtml#Compiling-to-executable">Compiling to a native executable</a>
            </b>
          </li>
        </ul>
        <p>
          Up: <a accesskey="u" href="Running.xhtml">How to start up and run Kawa</a></p>
        <p>
        Previous: <a accesskey="p" href="Exiting.xhtml">Exiting Kawa</a></p>
      </div>
    </footer>
  </body>
</html>