6.2 KiB
Getting started with Antlr4cpp
Here is how you can use this external project to create the antlr4cpp demo to start your project off.
- Create your project source folder somewhere. e.g. ~/srcfolder/
- Make a subfolder cmake
- Copy the files in this folder to srcfolder/cmake
- Cut below and use it to create srcfolder/CMakeLists.txt
- Copy main.cpp, TLexer.g4 and TParser.g4 to ./srcfolder/ from here
- Make a build folder e.g. ~/buildfolder/
- From the buildfolder, run
cmake ~/srcfolder; make
# minimum required CMAKE version
CMAKE_MINIMUM_REQUIRED(VERSION 3.7 FATAL_ERROR)
list(APPEND CMAKE_MODULE_PATH ${CMAKE_CURRENT_SOURCE_DIR}/cmake)
# compiler must be 11 or 14
set(CMAKE_CXX_STANDARD 11)
# required if linking to static library
add_definitions(-DANTLR4CPP_STATIC)
# using /MD flag for antlr4_runtime (for Visual C++ compilers only)
set(ANTLR4_WITH_STATIC_CRT OFF)
# add external build for antlrcpp
include(ExternalAntlr4Cpp)
# add antrl4cpp artifacts to project environment
include_directories(${ANTLR4_INCLUDE_DIRS})
# set variable pointing to the antlr tool that supports C++
# this is not required if the jar file can be found under PATH environment
set(ANTLR_EXECUTABLE /home/user/antlr-4.7.1-complete.jar)
# add macros to generate ANTLR Cpp code from grammar
find_package(ANTLR REQUIRED)
# Call macro to add lexer and grammar to your build dependencies.
antlr_target(SampleGrammarLexer TLexer.g4 LEXER
PACKAGE antlrcpptest)
antlr_target(SampleGrammarParser TParser.g4 PARSER
PACKAGE antlrcpptest
DEPENDS_ANTLR SampleGrammarLexer)
# include generated files in project environment
include_directories(${ANTLR_SampleGrammarLexer_OUTPUT_DIR})
include_directories(${ANTLR_SampleGrammarParser_OUTPUT_DIR})
# add generated grammar to demo binary target
add_executable(demo main.cpp
${ANTLR_SampleGrammarLexer_CXX_OUTPUTS}
${ANTLR_SampleGrammarParser_CXX_OUTPUTS})
target_link_libraries(demo antlr4_static)
Documentation for FindANTLR
The module defines the following variables:
ANTLR_FOUND - true is ANTLR jar executable is found
ANTLR_EXECUTABLE - the path to the ANTLR jar executable
ANTLR_VERSION - the version of ANTLR
If ANTLR is found, the module will provide the macros:
ANTLR_TARGET(<name> <input>
[PACKAGE namespace]
[OUTPUT_DIRECTORY dir]
[DEPENDS_ANTLR <target>]
[COMPILE_FLAGS [args...]]
[DEPENDS [depends...]]
[LEXER]
[PARSER]
[LISTENER]
[VISITOR])
which creates a custom command to generate C++ files from <input>
. Running the macro defines the following variables:
ANTLR_${name}_INPUT - the ANTLR input used for the macro
ANTLR_${name}_OUTPUTS - the outputs generated by ANTLR
ANTLR_${name}_CXX_OUTPUTS - the C++ outputs generated by ANTLR
ANTLR_${name}_OUTPUT_DIR - the output directory for ANTLR
The options are:
PACKAGE
- defines a namespace for the generated C++ filesOUTPUT_DIRECTORY
- the output directory for the generated files. By default it uses ${CMAKE_CURRENT_BINARY_DIR}DEPENDS_ANTLR
- the dependent target generated from antlr_target for the current callCOMPILE_FLAGS
- additional compile flags for ANTLR toolDEPENDS
- specify the files on which the command depends. It works the same wayDEPENDS
in add_custom_command()LEXER
- specify the input file is a lexer grammarPARSER
- specify the input file is a parser grammarLISTENER
- tell ANTLR tool to generate a parse tree listenerVISITOR
- tell ANTLR tool to generate a parse tree visitor
Examples
To generate C++ files from an ANTLR input file T.g4, which defines both lexer and parser grammar one may call:
find_package(ANTLR REQUIRED)
antlr_target(Sample T.g4)
do note that this command will do nothing unless the outputs of Sample
, i.e. ANTLR_Sample_CXX_OUTPUTS
gets used by some target.
Documentation for ExternalAntlr4Cpp
Including ExternalAntlr4Cpp will add antlr4_static
and antlr4_shared
as an optional target. It will also define the following variables:
ANTLR4_INCLUDE_DIRS - the include directory that should be included when compiling C++ source file
ANTLR4_STATIC_LIBRARIES - path to antlr4 static library
ANTLR4_SHARED_LIBRARIES - path to antlr4 shared library
ANTLR4_RUNTIME_LIBRARIES - path to antlr4 shared runtime library (such as DLL and SO file)
ANTLR4_TAG - branch/tag used for building antlr4 library
ANTLR4_TAG
is set to master branch by default to keep antlr4 updated. However, it will be required to rebuild after every clean
is called. Set ANTLR4_TAG
to a desired commit hash value to avoid rebuilding after every clean
and keep the build stable, at the cost of not automatically update to latest commit.
Visual C++ compiler users may want to additionally define ANTLR4_WITH_STATIC_CRT
before including the file. Set ANTLR4_WITH_STATIC_CRT
to true if ANTLR4 C++ runtime library should be compiled with /MT
flag, otherwise will be compiled with /MD
flag. This variable has a default value of OFF
. Changing ANTLR4_WITH_STATIC_CRT
after building the library may require reinitialization of CMake or clean
for the library to get rebuilt.
Examples
To build and link ANTLR4 static library to a target one may call:
include(ExternalAntlr4Cpp)
include_directories(${ANTLR4_INCLUDE_DIRS})
add_executable(output main.cpp)
target_link_libraries(output antlr4_static)
It may also be a good idea to copy the runtime libraries (DLL or SO file) to the executable for it to run properly after build. i.e. To build and link antlr4 shared library to a target one may call:
include(ExternalAntlr4Cpp)
include_directories(${ANTLR4_INCLUDE_DIRS})
add_executable(output main.cpp)
target_link_libraries(output antlr4_shared)
add_custom_command(TARGET output
POST_BUILD
COMMAND ${CMAKE_COMMAND}
-E copy ${ANTLR4_RUNTIME_LIBRARIES} .
WORKING_DIRECTORY ${CMAKE_CURRENT_BINARY_DIR})