1 /// \page build Building From Source 2 /// 3 /// The C runtime is provided in source code form only as there are too many binary 4 /// versions to sensibly maintain binaries on www.antlr.org. 5 /// 6 /// The runtime code is provided with .sln and .vcproj files for Visual Studio 2005 and 2008, 7 /// and \b configure files for building and installation on UNIX or other systems that support this tool. If your 8 /// system is neither Windows nor \b configure compatible, then you should find it 9 /// reasonable to build the code manually (see section "Building Manually".) 10 /// 11 /// \section src Source Code Organization 12 /// 13 /// The source code expands from a tar/zip file to give you the following 14 /// directories: 15 /// 16 /// - <b>./</b> The location of the configure script and the antlr3config.h file 17 /// generated by the running the configure script.This directory also 18 /// contains the solution and project files for visual studio 2005 and 19 /// 2008. 20 /// - <b>./src</b> The location of all the C files in the project. 21 /// - <b>./include</b> The location of all the header files for the project 22 /// - <b>./doxygen</b> The location of documentation files such as the one that generates this page 23 /// - Other ancillary directories used by the build or documentation process. 24 /// 25 /// \section winbuild Building for Windows 26 /// 27 /// If you are building for Cygwin, or a similar UNIX on Windows System, follow the "Building With Configure" instructions below. 28 /// 29 /// Note that the runtime is no longer compatible with the VC6 Microsoft compiler. If you absolutely need to build with 30 /// this compiler, you can probably hack the source code to deall with the pieces that VC6 cannot handle such as the 31 /// ULL suffix for constants. 32 /// 33 /// If you wish to build the binaries for Windows using Visual Studio 2005, or 2008 you may build using the IDE: 34 /// -# Open the C.sln file 35 /// -# Select batch Build from the Build menu 36 /// -# Select all configurations and press the build button. 37 /// 38 /// If you wish or need to build the libraries from the command line, then you must 39 /// use a Windows command shell configured for access to VS2005/VS2008 compilers, such as the one that is 40 /// started from: 41 /// 42 /// <i>Start->Microsoft Visual Studio 2005->Visual Studio Tools->Visual Studio 2005 Command Prompt</i> 43 /// 44 /// There appears to be no way to build all targets at once in a batch mode from the command line, 45 /// so you may build one or all of the following: 46 /// \verbatim 47 C:\antlrsrc\code\antlr\main\runtime\C> DEVENV C.sln /Build ReleaseDLL 48 C:\antlrsrc\code\antlr\main\runtime\C> DEVENV C.sln /Build Release 49 C:\antlrsrc\code\antlr\main\runtime\C> DEVENV C.sln /Build DebugDLL 50 C:\antlrsrc\code\antlr\main\runtime\C> DEVENV C.sln /Build Debug 51 \endverbatim 52 /// 53 /// After the build is complete you will find the \c.\cDLL and \c.\cLIB files under the directory containing C.sln, 54 /// 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, 55 /// 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 56 /// \c .LIB file which you should link your projects with and a DLL. The library and names on Windows are as follows: 57 /// 58 /// \verbatim 59 - ReleaseDLL : ANTLR3C.DLL and ANTLR3C_DLL.LIB 60 - DebugDLL : ANTLR3CD.DLL and ANTLR3CD_DLL.LIB 61 - Release : ANTLR3C.LIB 62 - Debug : ANTLR3CD.LIB 63 \endverbatim 64 /// 65 /// There currently no .msi modules or other installs built for Windows, so you must place the DLLs in a directory referenced 66 /// by the PATH environment variable and make the include directory available to your project configurations. 67 /// 68 /// 69 /// \section configure Building with configure 70 /// 71 /// Before starting, make sure that you are using a source code distribution and not the source code directly from the 72 /// Perforce repository. If you use the source from the perforce tree directly, you will find that there is no configure 73 /// script as this is generated as part of the distribution build by the maintainers. If you feel the need to build from 74 /// the distribution tree then you must have all the autobuild packages available on your system and can generate the 75 /// configure script using autoreconf. If you are not familiar with these tools, then please use the tgz files in the 76 /// dist subdirectory (or downloaded from the ANTLR web site). 77 /// 78 /// The source code file should be expanded in a directory of your choice (probably your working directory) using the command: 79 /// 80 /// \verbatim 81 gzip -dc antlrtgzname.tar.gz | tar xvf - 82 \endverbatim 83 /// 84 /// 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. 85 /// 86 /// 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 87 /// <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: 88 /// \verbatim 89 ./configure --help 90 \endverbatim 91 /// 92 /// Will document the latest incarnations of these options in case this documentation is ever out of date. At this time the options are: 93 /// 94 /// \verbatim 95 --enable-debuginfo Compiles debug info into the library (default no) 96 --enable-64bit Turns on flags that produce 64 bit object code if 97 any are required (default no) 98 \endverbatim 99 /// 100 /// Unless you need 64 bit builds, or a change in library types, you will generally use the configure command without options: 101 /// 102 /// Here is a sample configure output: 103 /// 104 /// \verbatim 105 [jimi@localhost dist]$ tar zvxf libantlr3c-3.0.0-rc8.tar.gz 106 107 libantlr3c-3.0.0-rc8/ 108 libantlr3c-3.0.0-rc8/antlr3config.h 109 libantlr3c-3.0.0-rc8/src/ 110 libantlr3c-3.0.0-rc8/src/antlr3stringstream.c 111 ... 112 libantlr3c-3.0.0-rc8/antlr3config.h.in 113 \endverbatim 114 /// \verbatim 115 [jimi@localhost dist]$ cd libantlr3c-3.0.0-rc 116 \endverbatim 117 /// \verbatim 118 [jimi@localhost libantlr3c-3.0.0-rc8]$ ./configure 119 120 checking for a BSD-compatible install... /usr/bin/install -c 121 checking whether build environment is sane... yes 122 checking for a thread-safe mkdir -p... /bin/mkdir -p 123 checking for gawk... gawk 124 checking whether make sets $(MAKE)... yes 125 checking for xlc... no 126 checking for aCC... no 127 checking for gcc... gcc 128 ... 129 checking for strdup... yes 130 configure: creating ./config.status 131 config.status: creating Makefile 132 config.status: creating antlr3config.h 133 config.status: antlr3config.h is unchanged 134 config.status: executing depfiles commands 135 \endverbatim 136 /// 137 /// Having configured the library successfully, you need only make it, and install it: 138 /// 139 /// \verbatim 140 [jimi@localhost libantlr3c-3.0.0-rc8]$ make 141 \endverbatim 142 /// \verbatim 143 make all-am 144 make[1]: Entering directory `/home/jimi/antlrsrc/code/antlr/main/runtime/C/dist/libantlr3c-3.0.0-rc8' 145 /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 146 ... 147 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 148 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 149 ranlib .libs/libantlr3c.a 150 creating libantlr3c.la 151 152 (cd .libs && rm -f libantlr3c.la && ln -s ../libantlr3c.la libantlr3c.la) 153 make[1]: Leaving directory `/home/jimi/antlrsrc/code/antlr/main/runtime/C/dist/libantlr3c-3.0.0-rc8' 154 \endverbatim 155 /// \verbatim 156 [jimi@localhost libantlr3c-3.0.0-rc8]$ sudo make install 157 \endverbatim 158 /// \verbatim 159 make[1]: Entering directory `/home/jimi/antlrsrc/code/antlr/main/runtime/C/dist/libantlr3c-3.0.0-rc8' 160 test -z "/usr/local/lib" || /bin/mkdir -p "/usr/local/lib" 161 /bin/sh ./libtool --mode=install /usr/bin/install -c 'libantlr3c.la' '/usr/local/lib/libantlr3c.la' 162 /usr/bin/install -c .libs/libantlr3c.so /usr/local/lib/libantlr3c.so 163 /usr/bin/install -c .libs/libantlr3c.lai /usr/local/lib/libantlr3c.la 164 /usr/bin/install -c .libs/libantlr3c.a /usr/local/lib/libantlr3c.a 165 ... 166 /usr/bin/install -c -m 644 'include/antlr3stringstream.h' '/usr/local/include/antlr3stringstream.h' 167 ... 168 /usr/bin/install -c -m 644 'antlr3config.h' '/usr/local/include/antlr3config.h' 169 make[1]: Leaving directory `/home/jimi/antlrsrc/code/antlr/main/runtime/C/dist/libantlr3c-3.0.0-rc8' 170 171 [jimi@localhost libantlr3c-3.0.0-rc8]$ 172 \endverbatim 173 /// 174 /// You are now ready to generate C recognizers and compile and link them with the ANTLR 3 C Runtime. 175 /// 176 /// 177 /// \section buildman Building Manually 178 /// 179 /// The only step that configure performs that cannot be done 180 /// manually (without effort) is to produce the header file 181 /// \c antlr3config.h, which contains typedefs of the fundamental types 182 /// that your local C compiler supports. The easiest way to produce 183 /// this file for your system, if you cannot port \b automake and \b configure 184 /// to the system is: 185 /// 186 /// -# Run configure on a system that does support configure 187 /// -# Copy the generated \c antlr3config.h file to the target system 188 /// -# Edit the file locally and change any types that differ on this 189 /// system to the target systems. There are only a few types and you should 190 /// find this relatively easy. 191 /// 192 /// Having produced a compatible antlr3config.h file, then you should be able to 193 /// compile the source files in the \c ./src subdirectory, providing an include path 194 /// to the location of \c antlr3config.h and the \c ./include subdirectory. Something akin 195 /// to: 196 /// \verbatim 197 198 ~/C/src: cc -c -O -I.. -I../include *.c 199 200 \endverbatim 201 /// 202 /// Having produced the .o (or equivalent) files for the local system you can then 203 /// build an archive or shared library for the C runtime. 204 /// 205 /// When you wish to build and link with the C runtime, specify the path to the 206 /// supplied header files, and the path to the library that you built. 207 ///
