source: trunk/yao/share/antlr-2.7.7/INSTALL.txt @ 1

                              A N T L R 
======================================================================

 Contents of this files is about  i n s t a l l i n g  ANTLR. If you 
 want to get some general information please checkout file  
  
                         README.txt

 which is part of this package. You may als visit "doc/index.html" for
 further information as well as http://www.antlr.org in general.

 If you want to know about the very basic steps on  u s i n g  ANTLR
 then have a look into section  

             ANTLR IS INSTALLED - WHAT'S NEXT?

 in file README.txt or in this file.  You may also follow a simple 
 mini-tutorial at

      http://www.antlr.org/article/cutpaste/index.html

 You may want to checkout also some target specific information on how
 to use ANTLR. Take a look at:

     doc/index.html           - main entry for all documentation 
     doc/runtime.html         - when using JAVA 
     doc/cpp-runtime.html     - when using C++ 
     doc/python-runtime.html  - when using Python
     doc/csharp-runtime.html  - when using C#

 If you don't have a precompiled version but rather a source code dis-
 tribution and you want to know some details on how to build and inst-
 all then you have come to the right place,

                          PLEASE READ ON

 Otherwise please skip this document! 
 

----------------------------------------------------------------------
TABLE OF CONTENTS

 * WHERE CAN I DOWNLOAD ANTLR?
 * REQUIREMENTS? 
 * BUILD AND INSTALL? BRIEF VERSION! 
 * BUILD AND INSTALL? LONG  VERSION! 
 * ANTLR IS INSTALLED - WHAT'S NEXT?
 * BUILD AND INSTALL ON WINDOWS NT/95/98/2000/XP?
 * FURTHER DETAILS ON ANTLR'S BUILD SETUP?
 * FAQ?
 * LIST OF CONFIGURED VARIABLES?
 * PLATFORMS?

______________________________________________________________________
WHERE CAN I DOWNLOAD ANTLR?

 ANTLR can be obtained from http://www.antlr.org either as
 
  * precompiled binary (RPM, MSI installer etc) 
  * source distribution (tar + zipped)

______________________________________________________________________
REQUIREMENTS?

 To get most out of ANTLR you should build ANTLR on UNIX or UNIX like 
 system. For example,  you need a bourne shell and a couple of common 
 UNIX tools like "grep", "mkdir", "cp", "rm", "sed", "cat" and "chmod". 
 
 You need also a GNU make or compatible make.

 Such a ANTLR friendly eco-system is given on Windows by having CYGWIN
 or MSYS installed. An out-of-the-box Window system may will  not work 
 for installation. 

 If you want to know on which systems ANTLR has been developed, which
 systems are known to work and known  to  fail  then please move your
 cursor down near the end of this document.

______________________________________________________________________
BUILD AND INSTALL ANTLR? BRIEF VERSION! 

 Here's a very brief summary of how to build and install ANTLR.
 
   $ cd $HOME
   $ gzip -d -c antlr-x.y.z.tar.gz | tar xvf -
   $ cd antlr-x.y.z
   $ ./configure --disable-examples
   $ make install

  Of course you can unpack ANTLR wherever you want on your machine -
  given enough space and permissions. For simplicuty, I'm just using
  $HOME and this may work for any user.
 
  ANTLR's source distribution contains lot's of examples. Making them
  can be quit longish. You may want to skip those examples if you are
  just interested in  building the core libraries. Note that examples
  are not installed.

  Python users: Note that "make install" will not add antlr.py to your
  local Python installation. This needs to be done manually by you. To
  simplify this you may the script "pyantlr.sh". Checkout this  script
  in directory "scripts" or, when installed, in directory "sbin".
 
______________________________________________________________________
BUILD AND INSTALL ANTLR? LONG VERSION! 
 
 This section presents details on the build process.

 1. Unpack
 =========

 To  build  ANTLR you need to unpack ANTLR's source distribution. This 
 will create a new directory named antlr-x.y.z in your current working
 directory. Typical unpacking steps are:

   $ cd $HOME ; 
   $ gzip -d -c antlr-x.y.z.tar.gz | tar xvf -

 Here I'm unpacking ANTLR in my $HOME directory but you may unpack in
 any directory that suits you. If you have gnu tar, then you can use 
 the simpler

   $ tar xvfz antlr-x.y.z.tar.gz

 to unpack the distro.

 For the rest of this document I will use ${srcdir} as a place holder
 to name the directory containing ANTLR sources. In the example given
 above, the following would be true:

   srcdir == $HOME/antlr-x.y.z


 2. Build Directory 
 ==================
 Create a build directory and change into that directory. A build dir-
 ectory can be any directory on your system. In the very brief version
 shown above I'm using the source directory -- ${srcdir} -- as build 
 directory. However, the general way and also the better approach is
 to use a new, fresh and clean directory. If at any later stage some-
 thing goes wrong you can just remove the whole build directory and 
 start from scratch again. You can also have ${srcdir} in read-only
 mode as no files are touched or changed with this approach. This is
 not the case if ${srcdir} and build directory are equal.

   $ mkdir -p $HOME/tmp/antlr
   $ cd $HOME/tmp/antlr


 3. Configure 
 ============
 
 Building ANTLR is accomplished by the well known GNU autoconf/make 
 approach. That is  you  run  a  shell script to create specialized
 files -- usually Makefiles -- for your particular environment.

 Within the build directory run configure like


   $ ${srcdir}/configure  --prefix=${installdir}


 where ${srcdir} points to your package directory (see step 1).

 Option --prefix==${installdir} tells configure where you want to
 have ANTLR installed on your system. Using this option is not
 mandatory. If you are not using it then configure will use 

       "/usr/local"

 as default installation directory. That  is  binaries will be 
 installed in /usr/local/bin, libraries go into "/usr/local/lib" etc. 

 Note that "configure" will search your $PATH for command line tools 
 to compile Java, C++ and C# source code, execute Python etc. This  
 behaviour of configure can be changed by using command line options 
 and/or environment variables. 

 To see a list of available configure options just run
       
       ${srcdir}/configure  --help 
   


 4. Build
 ========

   $ make

 This will (hopefully) build all needed ANTLR libraries within the 
 "lib" directory. If something fails for your system, and you want to 
 submit a bug report, you may wish to include your "config.status" 
 file, your host type, operating system and compiler information, 
 make output, and anything else you think will be helpful.

 If "make" complains about unknown rules etc. then it's usually 
 because you are not running GNU make. Configure will search for a GNU
 make in $PATH and in some well known locations.  If  there's  no  GNU
 make on your system, then configure will report an error in step 3,
 otherwise the first suitable GNU  make  wins.  However, if configure
 detects that "make" is not identical with the found one, configure 
 will show a reminder message as last action. The reminder message 
 will then tell you which make your are supposed to use.



 5. Test
 =======

 You may also wish to validate the correctness of the new ANTLR by
 running regression tests. It will makes you very confident if all
 test run through:
 
   $ make test

 However, please don't panic if a test fails. In most cases it is
 rather a problem  of running the test itself than a problem with
 ANTLR. When sure about a bug let us know please. Be sure to include
 information on your system, the ANTLR version used and other relevant
 information.

 

 6. Install
 ==========

 Depending on your ${installdir} directory you may need to have
 write permission to copy files. If you gained permissions required --
 perhaps by becoming super user -- install ANTLR by


   $ make install

  Python users: Note that "make install" will NOT add antlr.py to your
  local Python installation. This needs to be done manually by you. To
  simplify this you may the script "pyantlr.sh". Checkout this  script
  in directory "scripts" or, when installed, in directory "sbin".
   
 7. Clean
 ========

 Having installed ANTLR it is save to remove source and build 
 directory.

 
 8. Enjoy!
 =========

______________________________________________________________________
ANTLR IS INSTALLED - WHAT'S NEXT?

 Please read "doc/getting-started.html" on what you are supposed to
 do. Here's a very brief summary for the impatient:

 ANTLR is a command line tool. To run ANTLR you need to have JAVA
 installed. The basic steps are:

  a. write a grammar file - mygrammar.g

  b. run ANTLR like

       $ CLASSPATH=<path-to>/antlr.jar

       $ java antlr.Tool mygrammar.g

  c. write a driver program using source code generated by ANTLR, ie.
     Main.java, main.cpp, Main.cs or main.py

  d. link generated code, your driver code, ANTLR's core library and
     any additional library you are using together to get an 
     executable

  f. run the executable on arbitrary input to be parsed

 For a set of standard examples have a look into directory "examples"
 and appropriate subdirectories. You may want to run make like

  $ make verbose=1

 to see which compiler is used and which flags are passed etc. You may 
 also follow a simple mini-tutorial at

      http://www.antlr.org/article/cutpaste/index.html

 if you are absolutly new to ANTLR.

______________________________________________________________________
BUILD AND INSTALL ON WINDOWS NT/95/98/2000/XP?

 There  is no difference in building and installing Windows. However,
 you are need have either Cygwin or MSYS installed. We haven't tried
 MKS yet.
 
 If you run configure with Cygwin (or MSYS) then gcj will usually be
 chosen for compiling Java and gcc for compiling C++. In most cases
 however, C# will be  automatically disabled as no compiler can be 
 found. 

 Configure is not looking up the registry to check for installed soft-
 ware. Instead, configure will just check the $PATH for known compiler
 names and also check some well know locations like "/usr/local/bin"
 etc.

 In order to make configure aware of a certain compiler or tool you
 need, make sure that your compiler or tool can be found by looking up
 $PATH. For example, Microsoft Visual C++ comes with a batch file 
 named vcvars32.bat. Just run this batch file prior of running bash to
 have "cl" in your $PATH.

 Configure knows about this compiler names:

   bcc32 cl g++        for C++
   jikes javac gcj     for Java
   csc mcs cscc        for C#
   python              for Python
   
 The order in which the names appear is also the  search order. That
 means that the whole $PATH gets searched for bcc32, then for cl and
 finally for g++.

 In  other  words, it is sufficient to have "cl" in $PATH to have it
 selected by configure, regardless whether there is g++ available or
 not. Similar, if you also have bcc32 in $PATH, then the Borland C++
 Compiler will be choosen.

 If you have more that one compiler in your $PATH and the "wrong" 
 compiler is selected - Do you have to give up on this?

 Not at all.

 In case you have more than one compiler/tool in your $PATH, you can
 tell configure which one you like to have. For example:

  --with-cxx=g++

 This  will favor g++ regardless whether there's a cl or bcc in PATH.
 You can archive the very same by

  CXX=g++ ${srcdir}/configure 

 That is by using an environment variable. Try --help for the full
 list of --with-xxx options and environment variables.

______________________________________________________________________
DETAILS ON CONFIGURE?

 This section will present some further details on how you can tell
 configure to behave the way you want:


 1. Choose Language
 ==================

 ANTLR is implemented in Java and has code generator plugins for Java,
 C++, C# and Python.

 The default behaviour of configure is to check whether a suitable
 compiler or tool for a particular language is available. If not, then
 configure will show a warning  message and will automatically disable
 support for this language.

 In a very bizarre case it  is  therefore  possible  to end up  with a 
 configuration with no language support at all. Please study therefore
 configure's output whether you end up with the system you want.

 On the contrary, configure will enable, as mentioned, every target
 language with sufficient compiler/tool support. To speed up the 
 build process you may also disable languages (and configure them
 later again). This can be done by command line options:

  --disable-cxx    | --enable-cxx=no        --> disable C++ 
  --disable-java   | --enable-java=no       --> disable Java      
  --disable-csharp | --enable-csharp=no     --> disable C#
  --disable-python | --enable-python=no     --> disable Python

 Be warned that when disabling Java you can't even build ANTLR itself.
  
 
 2. Be Verbose
 =============

 A typical 'make' run  reports all kinds of actions exactly the way 
 they  get  carried out. This makes the output of a make run hard to
 read and it's difficult to keep track "where" make is right now and
 what's going on.

 ANTLR's make run has been designed to be readable. By default make 
 will report what's going on in a kind of logical way. For example,
 when compiling ANTLR itself you will see a message like

  *** compiling 209 Java file(s)

 This information is usually enough to keep track what's going on. If
 compilation fails, then the exact command line causing the problem 
 will be shown and you can study the arguments whether additional
 flags are required etc.

 However, you can tell configure to be verbose as usual by

 
  --enable-verbose


 Having enabled verbosity, the command to compile ANTLR will be shown
 similar like this (using javac):
   
  CLASSPATH=
  /opt/jdk32/142_03/bin/javac \
     -d . \
     -sourcepath /home/geronimo/src/antlrmain \
     -classpath /home/geronimo/obj/antlr-linux/lib/antlr.jar \
     Version.java \
     ANTLRParser.java \
     ...
     [[skipped 206 files]]
     ...
     /home/geronimo/src/antlrmain/antlr/debug/misc/JTreeASTPanel.java


 You have used --enable-verbose and output is too much. Do I need to
 configure again?

 No. Just run make like

  $ make verbose=0

 to turn off verbosity for this make run. You can also do this

  $ verbose=0
  $ export verbose
  $ make

 to turn verbosity off without using arguments to make.

 Of course, you can also turn verbosity on (verbose=1) in the very same
 way, regardless of what you have configured earlier.


 3. Debug Version
 ================

 A typical open source configuration sets compiler options to contain
 debug information.

 ANTLR's approach  is  a  bit  different. We believe that you want to 
 u s e  ANTLR  and  not to  d e b u g  it. In other words, we believe
 you are voting for speed.

 Therefore configure will set compiler flags that go for speed and we
 omit all flags introducing some debug information. 

 If you need to go for debug information, turn those flags on by using

  --enable-debug

 Similar to verbose discussed in the previous section you can override
 this configuration setting by using

  $ make debug=0         -- no debug information 
  $ make debug=1         -- turn debugging on
 
 without the need to reconfigure. But be aware that --enable-debug is
 just  changing  flags given to your compiler. It will not change any
 names. For  example,  the name of ANTLR's core library is libantlr.a
 (using g++) regardless of whether debug is on or off.


 4. Examples
 ===========

 You may leave out the examples just by

  --disable-examples

 Note that you can't undo this  without reconfiguration. Nevertheless,
 we recommend to configure with examples, test them and to study them
 to get a full understanding  on  how  ANTLR works and - last but not
 least - about all it's capabilities.


 5. Bootstrap
 ============

 ANTLR's parser engine (ie. the parser that accepts a grammar file) is
 written in ANTLR  itself. From a logical point of view you would need
 ANTLR  to  build ANTLR. This chicken and egg problem is solved simply
 by having generated source files enclosed in the package.

 However, if you are doing some surgery  on ANTLR's internals you need
 to have a existing ANTLR version around.

 You can tell configure about this external ANTLR version by

   --with-antlr-jar=${some-install-dir}/lib/antlr.jar

 or by

   --with-antlr-cmd=${some-tool-running-antlr}


 The former version will  add  given  jar  file to the $CLASSPATH when 
 trying to compile grammar files ( *.g).

 Very similar you  can  also use --with-antlr-cmd to provide a program
 or  shell  script  to  compile grammar files. The name of the program
 does not matter but it needs to be exectuable and it  should  support
 all flags that can be given to ANTLR (check java antlr.Tools -h).  

 NOTE:

 Bootstraping  ANTLR  with  an  external jar file or program does will 
 only taken into account if there's  no lib/antlr.jar available in the
 build directory. In other words, if you bootstraped once and you make
 changes later on ANTLR's internals, then  the  previously  build  jar
 file antlr.jar will be used - regardless of your configuration 
 options. 


 6. Which Make?
 ==============

 You need a GNU make  to  run  the build. This is especially true when
 building  ANTLR  on Windows. Nevertheless, some efforts has been done
 to lower  the  dependency on GNU make for portability reasons. But we
 are not done yet.

 If  you  have  GNU make installed on your system but it's not in your
 PATH or you want to have a special version of make, you may tell this
 configure by either

   --with-make=${list-of-candidates}

 or by using environment variable $MAKE like

   MAKE=${list-of-candidates} ${srcdir}/configure

 Which  variant  you are using is a matter of your personal taste. But
 be aware that the command line argument is overriding the environment
 variable. Consider this example:

  MAKE=x-make ${srcdir}/configure --with-make="y-make z-make"
  
 Here configure will check your $PATH for y-make and z-make bug x-make
 is ignored.

 Note that the withespace seperated ${list-of-candidates} may also
 contain absolute path names. In that case $PATH is not consulted but
 the file is directly checked for existence. Here's an example:

  MAKE='make /usr/bin/make' ${srcdir}/configure

 Here your $PATH is consulted whether a "make" exsists. Then 
 /usr/bin/make is checked for existence.

 The first make found which is then a GNU make is the one choose to be
 used to build ANTLR.

 For consistency reasons you may also use --with-makeflags or variable
 $MAKEFLAGS to  pass specific flags to make. However, this information
 is not yet used. Right now the flags used are the flags provided when
 calling make.

 7. Which Java?
 ==============

 ANTLR  has  been tested with SUN Java 1.4.x using either SUN's javac
 Java compiler, IBM's jikes or GNU's gcj. Other systems have not been 
 tested and are not expected to work.

 The default search order is 

  jikes javac gcj

 It  is  therefore sufficient to have "jikes" in your $PATH to get it
 choosen by configure - regardless whether it precedes a javac or not
 in $PATH.

 You may change this default search by providing a list of candidates
 by either

   --with-javac=${candidate-list}

 or by

   JAVAC=${candidate-list}

 The candidates should be seperated by whitespace and may be relative
 or  absolute  path  names. Only in the former case a lookup in $PATH 
 takes place.

 By default options passed to a Java compiler are those who are 
 sufficient to compile ANTLR. You may pass other flags by either

   --with-javacflags=${flags}

   JAVACFLAGS=${flags}

 In most cases you want to leave the default flags intact but rather
 add your additional flags. To support this, ANTLR's build management
 interprets ${flags} like this:

    ${flags}        STANDARD FLAGS           RESULT
    --------------+-----------------+----------------------
    + f1 f2 .. fn |     F1 .. FN    |  F1 .. FN f1 f2 .. fn 
    - f1 f2 .. fn |     F1 .. FN    |  f1 f2 .. fn F1 .. FN
    = f1 f2 .. fn |     F1 .. FN    |  f1 f2 .. fn
    f1 f2 .... fn |     F1 .. F     |  f1 f2 .. fn
    --------------+-----------------+----------------------

 In other words, you can either tell configure to append (+), to
 prepend (-) or to substitute(=) your flags. 


 Note that this is also possible when running make. For example,

   $ make JAVAC=jikes JAVACFLAGS="+ -verbose"

 would use jikes to compile regardless of what has been configured
 before. Additionally the flag "-verbose" is used.


 So far we talked about compiling Java. Let's have now a look on how
 to execute class files. By default configure searches for

   java gij

 to run Java. As discussed before it is sufficient  to  have a Java in
 $PATH to get java selected. It has also to be noted that gij is still
 in experimental stage and not fully supported now.

 As before you may also provide additional flags to Java by using 
 either

  --with-javaflags=${flags} 

 or by using environment variable

   JAVAFLAGS=${flags}

 Again, ${flags} are getting interpreted according to table shown 
 above.

 8. Which C++ Compiler?
 ======================

 The algorithm  on  how  the C++ compiler is choosen and how to pass 
 additional flags are very much the same as discussed before for the
 Java compiler.

 The default candidate list for choosing a C++ compiler is

  bcc32 cl g++                      on Windows ; and
  aCC CC xlC xlC_r g++ cxx c++      on UNIX.

 To change this list use

  --with-cxx=${candidates}

 and use

  --with-cxxflags=${flags}

 to pass additional flags to the standard compiler flags. You can also 
 use $CXX and $CXXFLAGS if you like. This  will  then  also  work when 
 running make. 


 9. Which C# Compiler?
 =====================

 The only candidate for C# as time of writing is 

  csc

 for compiling C# source code. To change this option

  --with-csharpc=${candidates}

 and use

  --with-csharpcflags=${flags}

 for providing a list of additional options. Note that ${flags} are
 getting interpreted as discussed in the previous sections.

 Instead  of  command  line  arguments to configure you may also use
 $CSHARPC and $CSHARPCFLAGS.  This  variables  are also working when 
 running make.

 10. Which Python?
 =================

 Configure is  searching for "python" in your $PATH and in some well
 known locations. If  no "python" can be found, language support for
 Python is disabled.

 You may use

  --with-python="${candidates}"

 to provide a list of Python candidates and further you may use

  --with-pythonflags="${flags}"

 to  provide  a  list of (additional) flags to be passed to Python on
 execution. Note that ${flags} is getting interpreted as discussed in
 the previous sections.

 You may also use $PYTHON and $PYTHONFLAGS instead. This variables are
 then also working when running make. Note  that  those  variable  may
 override what has been configured before without any warning.



______________________________________________________________________
FURTHER DETAILS ON ANTLR'S BUILD SETUP?


In allmost all cases it is assumed to be sufficient to change compiler
settings by using either --with-${lang}flags or by using ${LANG}FLAGS.

It's most likely not sufficient if you want to support a new compiler,
tool or a new operating system.

The general idea is  to  have a configured shell script for each tool 
or compiler being used rather than doing the scripting within the
Makefile itself. The reason for this is that scripting in Makefiles is
rather hard  to read and a pain to debug (for example, there's no line
information).

The configured shell scripts are to be found in subdirectory "scripts"
within the build directory. Their originals are located in 

 ${srcdir}/scripts

This scripts are known at time of writing:

 antlr.sh.in  -  runs "java antlr.Tools"
 cxx.sh.in    -  run C++ compiler
 cpp.sh.in    -  run C/C++ preprocessor (for dependencies).
 jars.sh.in   -  how to make a static library (aka jar file)(Java)
 javac.sh.in  -  run Java compiler (also when using jikes etc)
 lib.sh.in    -  how to make a static library (C++)
 link.sh.in   -  how to make a executable (C++)
 python.sh.in -  how to run python

A Makefile contains nothing more than variables and rules and in all-
most all cases (but simple exceptions)  the command behind a rule is
just executing a script.

Note that these scripts are not intended to be used  to  compile C++, 
Java etc in general. Instead this scripts are specialized for ANTLR.

For example, the script "lib.sh" has  a  very simple interface. All 
you can provide  is  a list  of object files. There is no option to
tell about the library  name  to be build. Instead the library name
is set by configure and available by using @ANTLR_LIB@ in all
configured files.

Unfortunatly, all scripts are rather complex and limiting ourselfs of
not using  shell  functions  (portability)  is not going make changes
easier.

In  general  you  should  only edit the upper part of any script till 
there's a line like "**NO  CHANGE NECESSARY BELOW THIS LINE - EXPERTS
ONLY**".


Then let's have now a closer look at cxx.sh.in. The other scripts are
very similar. I'm going to discuss here only the relevant parts - this
is open source  after  all any you may try to understand it by reading
the source code :-)

 ARGV="$*"

In general all arguments given to the script file are collected with-
in variable $ARGV. In some scripts, the very first  argument  has  a 
special meaning - usually it tells about the target to be created. In
such a case 

 TARGET

would hold the first argument given and ARGV would hold all others.

 if test -z "${CXX}" ; then
  CXX="@CXX@"
  cxx="@cxx@"
 else
  cxx="`basename $CXX`"
  cxx="`echo $cxx|sed 's,\..*$,,'`"
 fi

This script snippet checks about the compiler to be used for compiling
C++ source. Note that we have two variables,  CXX  and cxx. The former
holds usually the absolute path of  the  compiler  as  configured. The
later, cxx, contains the  logical  compiler name. The logical compiler
name is "gcc" for GNU, "cl" for Microsoft C++ etc. etc.

The logical compiler name is usually configured and available as @cxx@.
However,  a user  overrides  the  configuration  by  using environment 
variable CXX, the  logical  compiler  name is computed by removing any
extension.

In a further section (similar in other scripts) we set specific flags
depending on the  l o g i c a l  compiler name.  As you can see it is
rather important to the logical name proper.

case "${cxx}" in
  gcc)
    cxxflags="-felide-constructors -pipe"
    case "${DEBUG}" in
      0)
        cxxflags="-O2 -DNDEBUG ${cxxflags}"
        ;;
      1)
        cxxflags="-g ${cxxflags} -W -Wall"
        ;;
    esac
    ;;
  cl)
    cxxflags="/nologo -GX -GR" 
  [[skipped]]
esac

In the snippet shown you can see the handling of "gcc" and "cl". Note that
the compiler flags are saved in $cxxflags and not in $CXXFLAGS. Reason
for this is that handling  of environment variable $CXXFLAGS is rather
longish due to ANTLR's  special interpretation mechanism (as discussed 
in an earlier section).

In some cases flags may depend on platform in use. In that case you may
do something like:


  case ${cxx} in
   gcc)
        case @build_os@ in
         cygwin)
             ## cygwin specific flags ..
             ;;
          sparc)
             ## sparc specific ..
             ;;
          *)
             ## all others
             ;;
        esac
   ..
  esac

Of course you can utilize here the full scripting power to set flags
required to get compilation job done.

______________________________________________________________________
FAQ?

 1. How to setup jikes boot classpath?
 =====================================

 Jikes (http://www-124.ibm.com/developerworks/oss/jikes) is just a
 Java compiler that needs to know  about  Java's core classes, ie.
 rt.jar, for a successful build of ANTLR. By default configure tries
 to locate rt.jar by searching $PATH for a java executable and 
 relative to where found, for ../jre/lib/rt.jar.

 If this search fails or if you want to pass a different Java core or
 further core libraries, you may use either option 

   --with-bootclasspath="${args}"

 or environment variable

   BOOTCLASSPATH="${args}"

 The list of arguments, ${args}, is supposed to be list of whitespace
 seperated files or directories. Configure  will  validate  that each
 argument exists and will fail  otherwise.  Besides this there are no
 further validations  done  -  you  are supposed to know what you are
 doing. Note also that  configure will not perform any search in case
 a bootclasspath is given.

 The arguments given are concatenated using platform specific argument
 seperator (ie. ";" or ":") and passed to option --bootclasspath.

 2. Can I just say "make" after having unpacked ANTLR?
 =====================================================
 
 No - as explained previously you need to run "configure" before you
 can issue a "make".

 3. How do I cleanup afterwards?
 ===============================

 You do a "make clean" to remove all object files. If  you do a "make
 distclean", then all files generated by ANTLR are  also  removed. In
 this case you need a external antlr.jar somewhere to rebuild.

 If you are using a external build directory you may just remove the
 whole directory without any harm.

 4. Is it safe to edit a Makefile?
 =================================

 In general do not edit  files  named  Makefile.  Instead edit files
 named Makefile.in. Configure or config.status will override changes
 you made in a Makefile on any run.

 5. I changed Makefile.in - what's next?
 =======================================

 Just run make again. Each Makefile contains a rule that automatically
 remakes itself if corresponding Makefile.in has changed.

 This automatic rule works fine in general.  However,  if  you change 
 Makefile/Makefile.in in such a way that make rejects it's  execution
 then you need to remake Makefile yourself.

 This can be done by

   $ cd ${builddir}
   $ ./config.status ${your-makefile}

 Here's an example. Assume that "antlr/Makefile" is corrupted. The do
 this:

   ./config.status antlr/Makefile 

 You can also issue just a 

   $ ./config.status

 In this case all configured files are regenerated.

 6. My configure has changed - what's next?
 =============================================

 You need to reconfigure each build directory to get the changes. So
 far no automatic rule has been implemented. The easiest way of being
 up-to-date is:

  $ cd ${builddir} && ./config.status --recheck && make

 7. Where do I find antlr.jar?
 =============================
 
 Have a look at "lib".  Should  be there - but it is subject of having
 enabled  Java  or not.  Note that Java gets automatically disabled if 
 there's no  sufficient  Java compiler found (warning message would be
 dumped in that case).

 8. How can I make "make" nosiy?
 ===============================

 By default make just tells you what's going on in a very brief way. 
 To change this just do this:

  $ make verbose=1

 You can also tell configure to turn verbosity on by default by using
 option

  --enable-verbose.

 Run "configure --help" for a list of options available.

 9. Am I able to run "make" in a subdirectory?
 =============================================

 Sure.

 10. Is it safe to remove configured subdirectory?
 =================================================

 In general "yes" but you want to do this only within the build tree.

 For example, let's assume that you are tired of getting standard
 examples tested. Then just move on and remove subdirectory
 "examples".


______________________________________________________________________
LIST OF CONFIGURED VARIABLES?

 ANTLRFLAGS
 ANTLR_ACTION_FILES
 ANTLR_ANTLR_FILES
 ANTLR_COMPILE_CMD
 ANTLR_CYGWIN
 ANTLR_JAR
 ANTLR_LIB
 ANTLR_MINGW
 ANTLR_NET
 ANTLR_PY
 ANTLR_TOKDEF_FILES
 ANTLR_WIN32
 ANTLR_WITH_ANTLR_CMD
 ANTLR_WITH_ANTLR_JAR
 AR
 ARFLAGS
 AS
 BOOTCLASSPATH
 CSHARPC
 CSHARPCFLAGS
 CSHARP_COMPILE_CMD
 CXX_COMPILE_CMD
 CXX_LIB_CMD
 CXX_LINK_CMD
 CYGPATH
 DEBUG
 EXEEXT
 JAR
 JARFLAGS
 JAR_CMD
 JAVA
 JAVAC
 JAVACFLAGS
 JAVAFLAGS
 JAVA_CMD
 JAVA_COMPILE_CMD
 LIBEXT
 MAKE
 OBJEXT])
 PATCHLEVEL
 PYTHON
 PYTHONFLAGS
 SUBVERSION
 VERBOSE
 VERSION
 WITH_EXAMPLES
 abs_this_builddir
 cxx
 jar
 java
 javac

______________________________________________________________________
PLATFORMS?

 ANTLR  has  been  developed  and  tested on platforms listed below. A 
 platform is considered supported and tested if basically all standard
 examples are working.

 Devel for ANTLR 2.7.5 took place on:

 i686-linux2.6.3-7mk  
   - Java 1.4.2, gcj 3.3.4, jikes 1.16, 1.17, 1.18, 1.19, 1.20, 1.21, 1.22
   - gcc 3.3.2, gcc 3.3.4
   - Python 2.3, 2.4 
   - DotGNU 0.6.0

 i686-cygwin_nt-5.1
   - Java 1.4.2, gcj 3.3.3, jikes 1.22
   - gcc 3.3.3, bcc32 5.6 (Borland C++), cl 13.10.3077 (Microsoft C++)
   - csc 7.10.6001.4 (Visual C# .NET Compiler)
   - Python 2.2, 2.3, 2.4
   - Mono 1.0.5

 ANTLR has been tested on:

 MinGW-3.1.0.1 (needs manual install of cygpath!)
  - MSys 1.0.10
  - Java 1.5.0-b64
  - gcc 3.4.1
 
 PowerPC or RS/6000:
  * powerpc-apple-darwin6.8 (MacOS 1o, "Jaguar")
    - Java 1.4.1, jikes 1.15
    - gcc 3.1
    - Python 2.2
    - Mono (?) also reported to work.   

 SPARC:
  * sparc-sun-solaris2.8
    - Java 1.4.1
    - SUN CC 5.6

 Known  n o t  to work:
 - jikes 1.13 and older due to missing classpath and bootclasspath
   options. Jikes 1.14 and 1.15 are not tested due to compilation
   problems compiling jikes itself (on Mandrake 1o).

 - Python < 2.2 will not work.

 - gcc 2.* will not work.

 - You need to have GNU make (for building).
======================================================================
             INSTALL.txt - last update January 11th, 2005