-
Notifications
You must be signed in to change notification settings - Fork 3
/
INSTALL.txt
1090 lines (759 loc) · 33.3 KB
/
INSTALL.txt
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
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