#LyX 1.3 created this file. For more info see http://www.lyx.org/
\lyxformat 221
\textclass linuxdoc
\language english
\inputencoding auto
\fontscheme default
\graphics default
\paperfontsize default
\spacing single 
\papersize Default
\paperpackage a4
\use_geometry 0
\use_amsmath 0
\use_natbib 0
\use_numerical_citations 0
\paperorientation portrait
\secnumdepth 3
\tocdepth 3
\paragraph_separation indent
\defskip medskip
\quotes_language english
\quotes_times 2
\papercolumns 1
\papersides 1
\paperpagestyle default

\layout Title
\added_space_top vfill \added_space_bottom vfill 
autoj - Automated Java Build System
\layout Author

Daniel Tschan
\layout Standard


\begin_inset ERT
status Collapsed

\layout Standard
<newline>
\end_inset 

 
\newline 
Copyright (c) 2004 Daniel Tschan.
\begin_inset ERT
status Collapsed

\layout Standard
<newline>
\end_inset 

 
\newline 
Permission is granted to copy, distribute and/or modify this document under
 the terms of the GNU Free Documentation License, Version 1.2 or any later
 version published by the Free Software Foundation; with no Invariant Sections,
 no Front-Cover Texts, and no Back-Cover Texts.
 A copy of the license is included in the section entitled "GNU Free Documentati
on License".
\layout Section

Introduction
\layout Standard

Autoj is an automated build system for Java based on autoconf, make, bash
 and some other GNU tools.
 It generates a configure script, classpath.in, Makefile.in and run.in from
 configure.aj and Makefile.aj (optional).
 This documentation is intented for the autoj user which usually is a Java
 developer.
\layout Section

Requirements
\layout Standard

Autoj requires at least the following software to be installed:
\layout Itemize

A UNIX like environment (Cygwin on Windows) with standard tools like rm,
 mkdir, etc.
\layout Itemize

GNU autoconf 2.13 or later
\layout Itemize

GNU automake 1.4 or later
\layout Itemize

GNU make 3.79.1 or later
\layout Itemize

GNU bash 2.03 or later
\layout Itemize

A version of the find utility
\layout Itemize

A Java compiler with a javac or jikes command line front end
\layout Standard

To make use of all autoj features you additionally need:
\layout Itemize

run (with unqualified classes): GNU find 4.1 or later
\layout Itemize

make lib: GNU wget 1.7 or later
\layout Itemize

make jar: Versions of the tar and jar utilities
\layout Itemize

make dist: A version of the tar utility and gzip 1.3.3 or later
\layout Itemize

make javadoc: A Java 2 compliant version of the javadoc utility
\layout Standard

Earlier versions may also work but have not been tested.
\layout Section

Files
\layout Subsection

configure.aj
\layout Standard

Configure.aj is used to override autoj default values and to customize the
 configuration process.
 autoj uses the following variables and default values:
\layout Description

PROJECT The name of the project.
 Default: unnamed 
\layout Description

SRCDIR Directory containing the main sources.
 Default: src
\layout Description

TESTDIR Directory containing the unit test sources.
 Default: test
\layout Description

BINDIR Directory autoj writes class and jar files to.
 Default: bin
\layout Description

LIBDIR Directory containing project dependencies, usually .jar files.
 Default: lib
\layout Description

LIBSFILE File listing the depencencies and their download locations.
 Default: libs
\layout Description

LOCALDIR This directory is added to the CLASSPATH in addition to SRCDIR,
 TESTDIR and BINDIR.
 Used for config files, images and other stuff loaded by Java code.
 Default: local
\layout Description

JAVADOCDIR Directory autoj writes the JavaDoc to.
 Default: javadoc
\layout Description

MANIFESTFILE Name of the optional manifest file.
 Default: manifest
\layout Description

TMPDIR Temporary directory used by various makefile targets.
 Default: tmp
\layout Standard

The contents of the configure.aj file are inserted into autoj's configure.in
 file just before the AC_OUTPUT macros.
 Thus it can be used to further customize the configure process.
 Any statement which is valid in configure.in or configure.ac is valid in
 configure.aj, too.
\layout Subsection

Makefile.aj
\layout Standard

This file is optional an can be used to add additional Makefile targets.
 The contents of Makefile.aj are appended to autoj's Makefile.in.
 This allows you to provide your own make rules, e.g.
 for compiling documentation.
 If Makefile.aj defines the variable CLEANFILES the 
\layout Subsection

libs
\layout Standard

The libs file lists the dependencies of a project and server locations they
 can be downloaded from.
 Each line can either contain a URL or a filename.
 A URL sets the download location for all following files until the next
 URL.
 Empty lines and lines starting with # are ignored.
 Example:
\layout Standard


\begin_inset ERT
status Collapsed

\layout Standard
<code>
\end_inset 

http://autoj.sourceforge.net/lib
\newline 
httpunit-1.4.6.jar
\newline 
junit-3.8.1.jar
\newline 

\newline 
ftp://ftp.devzone.ch/lib
\newline 
log4j-1.2.7.jar
\begin_inset ERT
status Collapsed

\layout Standard
</code>
\end_inset 


\layout Standard

With this example the files junit-3.8.1.jar and log4j-1.2.7.jar are downloaded
 from http://autoj.sourceforge.net/lib and log4j-1.2.7.jar is downloaded from
 ftp://ftp.devzone.ch/lib.
 HTTP and FTP URLs are supported.
\layout Subsection

classpath
\layout Standard

classpath is a helper script which is used by Makefile and run.
 It prints the path that must be appended to the 
\emph on 
CLASSPATH
\emph default 
 for this project.
 This path contains the 
\emph on 
SRCDIR
\emph default 
, 
\emph on 
TESTDIR
\emph default 
, 
\emph on 
BINDIR
\emph default 
 and 
\emph on 
LOCALDIR
\emph default 
 directories and all .jar files and directories in the 
\emph on 
LIBDIR
\emph default 
 directory.
 classpath works independent of the current working directory and can therefore
 be called from anywhere.
\layout Subsection

run
\layout Standard

The run script can be used to run a project by specifying an unqualified
 or partially qualified class name.
 It automatically sets the appropriate 
\emph on 
CLASSPATH
\emph default 
.
 run scans the 
\emph on 
SRCDIR
\emph default 
 and 
\emph on 
TESTDIR
\emph default 
 directories for .java files matching the specified class name.
 The first file found is taken and its package extracted.
 The package is used to build a fully qualified class name.
 If no matching file is found the given class name is passed to the virtual
 machine untouched.
 So the run script still runs without the source code if you use fully qualified
 class names.
 run works independent of the current working directory and can therefore
 be called from anywhere.
\layout Section

Directory structure
\layout Standard

autoj determines what to do with a file by looking at its filename and the
 directory it is in.
\layout Section

Makefile targets
\layout Standard

The Makefile generated by autoj contains the following default targets:
\layout Description

clean Removes all intermediate and binary files.
 
\series bold 
Warning:
\series default 
 This version of autoj removes the entire 
\emph on 
BINDIR
\emph default 
 and 
\emph on 
JAVADOCDIR
\emph default 
 directories, including all its content.
 So pay attention not to put any source files in there.
\layout Description

lib Synchronizes project dependencies.
 All files listed in 
\emph on 
LIBSFILE
\emph default 
 which are not present locally or which have a newer version available on
 the server are downloaded into the lib directory.
 Files in the 
\emph on 
LIBDIR
\emph default 
 directory which do not appear in the 
\emph on 
LIBSFILE
\emph default 
 file are removed.
\layout Description

javadoc Creates the JavaDoc Documentation
\layout Description

cvscheck Checks if the current cvs version can be compiled by checking it
 out into a subdirectory and trying to compile it.
\layout Description

jar Creates a jar file of the project.
\layout Description

dist Creates a source distribution tarball.
\layout Description

libdist Creates a source distribution tarball including all dependencies
 (.jar files).
\layout Description

bindist Creates a binary distribution tarball including all dependencies
 (.jar files).
\layout Standard

Distribution tarballs are compressed with gzip using the best compression
 method available.
\layout Section

JFlex support
\layout Standard

JFlex is a scanner generator for Java written in Java.
 The makefile autoj generates automatically compiles all .flex files it finds
 in the 
\emph on 
SRCDIR
\emph default 
 and the 
\emph on 
TESTDIR
\emph default 
 directories with JFlex.
 It assumes that the scanner class is named like the specification file
 with 
\begin_inset Quotes eld
\end_inset 

Scanner
\begin_inset Quotes erd
\end_inset 

 appended and that the .java file is placed in the same directory as the
 .flex file.
 E.g.
 if the specification is named Java.flex then the scanner source file should
 be named JavaScanner.java.
 The name of the scanner .java file must be known to autoj in order to threat
 it as intermediate file and to decide when to recompile the scanner.
 If the specification does not follow this rule the scanner source file
 will not be cleaned by 
\begin_inset Quotes eld
\end_inset 

make clean
\begin_inset Quotes erd
\end_inset 

 and the scanner will always be recompiled.
\layout Section

CUP support
\layout Standard

CUP is a LALR parser generator for Java written in Java.
 The makefile autoj generates automatically compiles all .cup files it finds
 in the 
\emph on 
SRCDIR
\emph default 
 and the 
\emph on 
TESTDIR
\emph default 
 directories with CUP.
 It assumes that the parser class is named like the specification file with
 
\begin_inset Quotes eld
\end_inset 

Parser
\begin_inset Quotes erd
\end_inset 

 and the symbols class or interface with 
\begin_inset Quotes eld
\end_inset 

Symbols
\begin_inset Quotes erd
\end_inset 

 appended and that the .java files are placed in the same directory as the
 .cup file.
 E.g.
 if the specification is named Java.cup then the parser source file should
 be named JavaParser.java and the symbols source file should be named JavaSymbols.
java.
 The name of the parser .java files must be known to autoj in order to threat
 them as intermediate files and to decide when to recompile the parser.
 If the specification does not follow this rule the parser source files
 will not be cleaned by 
\begin_inset Quotes eld
\end_inset 

make clean
\begin_inset Quotes erd
\end_inset 

 and the parser will always be recompiled.
\layout Section

Examples
\layout Section

GNU Free Documentation License
\layout Verbatim


\begin_inset ERT
status Collapsed

\layout Standard
@GFDL@
\end_inset 


\the_end