1build(3)                            ANTLR3C                           build(3)
2
3
4

NAME

6       build - Building From Source
7
8       The C runtime is provided in source code form only as there are too
9       many binary versions to sensibly maintain binaries on www.antlr.org.
10
11       The runtime code is provided with .sln and .vcproj files for Visual
12       Studio 2005 and 2008, and configure files for building and installation
13       on UNIX or other systems that support this tool. If your system is
14       neither Windows nor configure compatible, then you should find it
15       reasonable to build the code manually (see section 'Building
16       Manually'.)
17

Source Code Organization

19       The source code expands from a tar/zip file to give you the following
20       directories:
21
22./ The location of the configure script and the antlr3config.h file
23         generated by the running the configure script.This directory also
24         contains the solution and project files for visual studio 2005 and
25         2008.
26
27./src The location of all the C files in the project.
28
29./include The location of all the header files for the project
30
31./doxygen The location of documentation files such as the one that
32         generates this page
33
34       • Other ancillary directories used by the build or documentation
35         process.
36

Building for Windows

38       If you are building for Cygwin, or a similar UNIX on Windows System,
39       follow the 'Building With Configure' instructions below.
40
41       Note that the runtime is no longer compatible with the VC6 Microsoft
42       compiler. If you absolutely need to build with this compiler, you can
43       probably hack the source code to deall with the pieces that VC6 cannot
44       handle such as the ULL suffix for constants.
45
46       If you wish to build the binaries for Windows using Visual Studio 2005,
47       or 2008 you may build using the IDE:
48
49       1.  Open the C.sln file
50
51       2.  Select batch Build from the Build menu
52
53       3.  Select all configurations and press the build button.
54
55       If you wish or need to build the libraries from the command line, then
56       you must use a Windows command shell configured for access to
57       VS2005/VS2008 compilers, such as the one that is started from:
58
59       Start->Microsoft Visual Studio 2005->Visual Studio Tools->Visual Studio
60       2005 Command Prompt
61
62       There appears to be no way to build all targets at once in a batch mode
63       from the command line, so you may build one or all of the following:
64
65          C:\antlrsrc\code\antlr\main\runtime\C> DEVENV C.sln /Build ReleaseDLL
66          C:\antlrsrc\code\antlr\main\runtime\C> DEVENV C.sln /Build Release
67          C:\antlrsrc\code\antlr\main\runtime\C> DEVENV C.sln /Build DebugDLL
68          C:\antlrsrc\code\antlr\main\runtime\C> DEVENV C.sln /Build Debug
69
70
71       After the build is complete you will find the \c.\cDLL and \c.\cLIB files under the directory containing C.sln,
72       in a subdirectory named after the /Build target. In the Release and Debug targets, you will find that there is only a \c.\cLIB archive file,
73       which you can link directly into your own projects if you wish to avoid the DLL. In \c ReleaseDLL and \c DebugDLL you will find both a
74       \c .LIB file which you should link your projects with and a DLL. The library and names on Windows are as follows:
75
76       \verbatim
77
78
79       • ReleaseDLL : ANTLR3C.DLL and ANTLR3C_DLL.LIB
80
81       • DebugDLL : ANTLR3CD.DLL and ANTLR3CD_DLL.LIB
82
83       • Release : ANTLR3C.LIB
84
85       • Debug : ANTLR3CD.LIB
86
87       There currently no .msi modules or other installs built for Windows, so you must place the DLLs in a directory referenced
88       by the PATH environment variable and make the include directory available to your project configurations.
89
90
91       \section configure Building with configure
92
93       Before starting, make sure that you are using a source code distribution and not the source code directly from the
94       Perforce repository. If you use the source from the perforce tree directly, you will find that there is no configure
95       script as this is generated as part of the distribution build by the maintainers. If you feel the need to build from
96       the distribution tree then you must have all the autobuild packages available on your system and can generate the
97       configure script using autoreconf. If you are not familiar with these tools, then please use the tgz files in the
98       dist subdirectory (or downloaded from the ANTLR web site).
99
100       The source code file should be expanded in a directory of your choice (probably your working directory) using the command:
101
102       \verbatim
103
104
105        gzip -dc antlrtgzname.tar.gz | tar xvf -
106
107       Where: <b>antlrtgzname.tar.gz</b> is of course the name of the tar when you downloaded it. You should find a \b configure script in the sub directory thus created.
108
109       The configure script accepts the usual options, such as --prefix= but the default is to build in the source directory and to place libraries in
110       <b>/usr/local/lib</b> and include files (for building your recognizers) in <b>/usr/local/include</b>. There are also a number of antlr specific options, which you may wish to utilize. The command:
111       \verbatim
112
113
114        ./configure --help
115
116       Will document the latest incarnations of these options in case this documentation is ever out of date. At this time the options are:
117
118       \verbatim
119
120
121        --enable-debuginfo Compiles debug info into the library (default no)
122       --enable-64bit Turns on flags that produce 64 bit object code if any
123       are required (default no)
124
125       Unless you need 64 bit builds, or a change in library types, you will generally use the configure command without options:
126
127       Here is a sample configure output:
128
129       \verbatim
130
131
132        [jimi@localhost dist]$ tar zvxf libantlr3c-3.0.0-rc8.tar.gz
133
134       libantlr3c-3.0.0-rc8/ libantlr3c-3.0.0-rc8/antlr3config.h
135       libantlr3c-3.0.0-rc8/src/ libantlr3c-3.0.0-rc8/src/antlr3stringstream.c
136       ... libantlr3c-3.0.0-rc8/antlr3config.h.in
137
138       [jimi@localhost dist]$ cd libantlr3c-3.0.0-rc
139
140
141       [jimi@localhost libantlr3c-3.0.0-rc8]$ ./configure
142
143       checking for a BSD-compatible install... /usr/bin/install -c
144       checking whether build environment is sane... yes
145       checking for a thread-safe mkdir -p... /bin/mkdir -p
146       checking for gawk... gawk
147       checking whether make sets $(MAKE)... yes
148       checking for xlc... no
149       checking for aCC... no
150       checking for gcc... gcc
151       ...
152       checking for strdup... yes
153       configure: creating ./config.status
154       config.status: creating Makefile
155       config.status: creating antlr3config.h
156       config.status: antlr3config.h is unchanged
157       config.status: executing depfiles commands
158
159
160       Having configured the library successfully, you need only make it, and install it:
161
162       \verbatim
163
164
165        [jimi@localhost libantlr3c-3.0.0-rc8]$ make
166
167       make  all-am
168       make[1]: Entering directory `/home/jimi/antlrsrc/code/antlr/main/runtime/C/dist/libantlr3c-3.0.0-rc8'
169       /bin/sh ./libtool --tag=CC   --mode=compile gcc -DHAVE_CONFIG_H -I. -Iinclude -Iinclude    -O2  -MT antlr3baserecognizer.lo -MD -MP -MF .deps/antlr3baserecognizer.Tpo -c -o antlr3baserecognizer.lo `test -f 'src/antlr3baserecognizer.c' || echo './'`src/antlr3baserecognizer.c
170       ...
171       gcc  -shared  .libs/antlr3baserecognizer.o .libs/antlr3basetree.o .libs/antlr3basetreeadaptor.o .libs/antlr3bitset.o .libs/antlr3collections.o .libs/antlr3commontoken.o .libs/antlr3commontree.o .libs/antlr3commontreeadaptor.o .libs/antlr3commontreenodestream.o .libs/antlr3cyclicdfa.o .libs/antlr3encodings.o .libs/antlr3exception.o .libs/antlr3filestream.o .libs/antlr3inputstream.o .libs/antlr3intstream.o .libs/antlr3lexer.o .libs/antlr3parser.o .libs/antlr3string.o .libs/antlr3stringstream.o .libs/antlr3tokenstream.o .libs/antlr3treeparser.o .libs/antlr3rewritestreams.o .libs/antlr3ucs2inputstream.o   -Wl,-soname -Wl,libantlr3c.so -o .libs/libantlr3c.so
172       ar cru .libs/libantlr3c.a  antlr3baserecognizer.o antlr3basetree.o antlr3basetreeadaptor.o antlr3bitset.o antlr3collections.o antlr3commontoken.o antlr3commontree.o antlr3commontreeadaptor.o antlr3commontreenodestream.o antlr3cyclicdfa.o antlr3encodings.o antlr3exception.o antlr3filestream.o antlr3inputstream.o antlr3intstream.o antlr3lexer.o antlr3parser.o antlr3string.o antlr3stringstream.o antlr3tokenstream.o antlr3treeparser.o antlr3rewritestreams.o antlr3ucs2inputstream.o
173       ranlib .libs/libantlr3c.a
174       creating libantlr3c.la
175
176       (cd .libs && rm -f libantlr3c.la && ln -s ../libantlr3c.la libantlr3c.la)
177       make[1]: Leaving directory `/home/jimi/antlrsrc/code/antlr/main/runtime/C/dist/libantlr3c-3.0.0-rc8'
178
179
180       [jimi@localhost libantlr3c-3.0.0-rc8]$ sudo make install
181
182
183       make[1]: Entering directory `/home/jimi/antlrsrc/code/antlr/main/runtime/C/dist/libantlr3c-3.0.0-rc8'
184       test -z '/usr/local/lib' || /bin/mkdir -p '/usr/local/lib'
185        /bin/sh ./libtool --mode=install /usr/bin/install -c  'libantlr3c.la' '/usr/local/lib/libantlr3c.la'
186       /usr/bin/install -c .libs/libantlr3c.so /usr/local/lib/libantlr3c.so
187       /usr/bin/install -c .libs/libantlr3c.lai /usr/local/lib/libantlr3c.la
188       /usr/bin/install -c .libs/libantlr3c.a /usr/local/lib/libantlr3c.a
189       ...
190        /usr/bin/install -c -m 644 'include/antlr3stringstream.h' '/usr/local/include/antlr3stringstream.h'
191       ...
192        /usr/bin/install -c -m 644 'antlr3config.h' '/usr/local/include/antlr3config.h'
193       make[1]: Leaving directory `/home/jimi/antlrsrc/code/antlr/main/runtime/C/dist/libantlr3c-3.0.0-rc8'
194
195       [jimi@localhost libantlr3c-3.0.0-rc8]$
196
197
198       You are now ready to generate C recognizers and compile and link them with the ANTLR 3 C Runtime.
199
200
201       \section buildman Building Manually
202
203       The only step that configure performs that cannot be done
204       manually (without effort) is to produce the header file
205       \c antlr3config.h, which contains typedefs of the fundamental types
206       that your local C compiler supports. The easiest way to produce
207       this file for your system, if you cannot port \b automake and \b configure
208       to the system is:
209
210       -# Run configure on a system that does support configure
211       -# Copy the generated \c antlr3config.h file to the target system
212       -# Edit the file locally and change any types that differ on this
213         system to the target systems. There are only a few types and you should
214         find this relatively easy.
215
216       Having produced a compatible antlr3config.h file, then you should be able to
217       compile the source files in the \c ./src subdirectory, providing an include path
218       to the location of \c antlr3config.h and the \c ./include subdirectory. Something akin
219       to:
220       \verbatim
221
222
223        ~/C/src: cc -c -O -I.. -I../include *.c
224
225       Having produced the .o (or equivalent) files for the local system you can then
226       build an archive or shared library for the C runtime.
227
228       When you wish to build and link with the C runtime, specify the path to the
229       supplied header files, and the path to the library that you built.
230
231Version 3.3.1                   Wed Jan 18 2023                       build(3)
Impressum