Jcon Usage

Jcont translates Icon source files into .zip files, and links .zip files to make an executable program. Jcont is similar to icont in concept and behavior; think of a .zip file as analogous to a .u1/.u2 pair generated by icont.

Normally, jcont produces a directly executable shell script containing an embedded Zip file. Running the script executes the compiled Icon program, and arguments can be passed as usual.

The short form jcon command is analogous to the icon command. It translates, links, and executes a single source file.

Synopsis

jcont [options] file... [-x [arguments]]

jcon file.icn [arguments]

File Arguments

file.icn	Icon source file to compile and link
file.zip	Previously compiled file to link (Must be local: jcont does not search $IPATH for file.zip)
file.class	Java bytecode file (for dynamic loading) to include in output file

Options

-b	generate backwards-compatible .u1 and .u2 files; implies -c
-c	compile only: don't produce an executable
-E	preprocess only
-f d	enable debugging features (tracing, error conversion)
-h	print a usage message and exit
-j	produce a .jar file instead of an executable script
-o exe	specify output file for executable
-r	include a copy of the run-time system in the executable
-s	silent: suppress commentary
-t	compile with -f d (to allow tracing) and initialize &trace to -1
-u	list undeclared variables
-x	execute after compilation (appears after file arguments)

The following options are mainly for debugging Jcon:

-d	debug jcont: use ./jtmp for temporary files, and do not delete them when finished
-J	use Jcon-built versions of jtran and jlink, if available
-P	pessimize: don't optimize the generated Java code
-S	also generate a .jvm file listing the generated Java code
-v	verbose: echo shell commands and trace linking steps

Environment Variables

The following environment variables affect compilation and linking:

LPATH	Search path for $include directives
IPATH	Search path for link directives

The following environment variables affect execution:

CLASSPATH	Search path for Java libraries required at execution time. This is not usually needed unless the libraries have moved.
JXOPTS	Options passed to the Java interpreter that runs the program. Depending on the implementation, JXOPTS can select options such as profiling or run-time compilation to machine code.
TRACE	Initial value of the Icon keyword &trace. If set, it overrides compilation with -t.

If a Jcon program runs out of memory, Java's limits can be increased by setting JXOPTS. For example, setenv JXOPTS '-mx50m' increases the maximum space to 50 megabytes. See the Java documentation for other Java options.

Jar file output

If -j is passed to jcont, the final output file is given a .jar extension and the header is omitted to facilitate manipulation of the file as an archive. Execution is accomplished by naming the file in the CLASSPATH, along with the run-time library, and then running java:

jcont -j myprog.icn
setenv CLASSPATH myprog.jar:/myhome/jcon/bin/jcon.zip
java myprog

If the -r flag is also used, a copy of the run-time library is included in the the generated jar file. This provides a self-contained package that can be executed on any Java implementation, possibly even one of different architecture:

jcont -jr myprog.icn
java -jar myprog.jar

Caveats

java must be in the search path, and also javap if -S is used.

The -S option does not work for files containing link directives.

A compiled .zip file cannot be renamed: The file name must match the original .icn name. (However, executables can be renamed.)