[C++] More modern CMake integration

[mcmikecreations]

Hi! This is mostly a suggestion to @hzeller @parrt @Krzmbrzl and others who worked on the C++ runtime for Antlr.
Runtime warnings aside, I was wondering why there needed to be such a complex CMake setup with ExternalProject_Add and the rest of ExternalAntlr4Cpp.cmake. I tried playing around and got a fully working example with the code below.

In it, I download ANTLR C++ Runtime and complete .jar file, then generate a lexer with it. Folder structure:

CMakeLists.txt - below
main.cpp - from example, but only the lexer part
TLexer.g4 - from example

cmake_minimum_required(VERSION 3.14)

set(ANTLR4_WITH_STATIC_CRT OFF) # using /MD flag for antlr4_runtime (for Visual C++ compilers only)
set(ANTLR_BUILD_SHARED ON) # in my case I built the shared version
set(ANTLR_TAG 4.13.1) # to specify the GitHub tag for the jar too
set(DISABLE_WARNINGS ON) # Antlr gives a few deprecation warnings for me
set(ANTLR_BUILD_CPP_TESTS OFF) # to avoid creating dist folder

set(ANTLR_EXECUTABLE "./antlr-${ANTLR_TAG}-complete.jar") # a local path for antlr.jar
if(NOT EXISTS "${ANTLR_EXECUTABLE}")
    file(
        DOWNLOAD
        "https://www.antlr.org/download/antlr-${ANTLR_TAG}-complete.jar"
        "${ANTLR_EXECUTABLE}"
    )
endif()
FetchContent_Declare(
    antlr
    GIT_REPOSITORY https://github.com/antlr/antlr4
    GIT_TAG ${ANTLR_TAG}
    SOURCE_SUBDIR "runtime/Cpp"
)
FetchContent_MakeAvailable(antlr) # populates antlr_SOURCE_DIR
include(${antlr_SOURCE_DIR}/runtime/Cpp/cmake/FindANTLR.cmake) # populates ANTLR_TARGET

antlr_target(SampleGrammarLexer TLexer.g4 LEXER PACKAGE antlrcpptest)

# add generated grammar to demo binary target
add_executable(demo main.cpp ${ANTLR_SampleGrammarLexer_CXX_OUTPUTS})

target_link_libraries(demo PRIVATE antlr4_shared)
target_include_directories(demo PRIVATE "${antlr_SOURCE_DIR}/runtime/Cpp/runtime/src" ${ANTLR_SampleGrammarLexer_OUTPUT_DIR})
target_compile_features(demo PRIVATE cxx_std_17)

# if you want to copy them to a different location and haven't specified
# CMAKE_LIBRARY_OUTPUT_DIRECTORY
# CMAKE_ARCHIVE_OUTPUT_DIRECTORY
# CMAKE_RUNTIME_OUTPUT_DIRECTORY
# set(ANTLR_RUNTIME_LIBRARIES $<TARGET_FILE:antlr4_shared> $<TARGET_LINKER_FILE:antlr4_shared>)

This example is:

1. smaller and simpler than the provided script
2. doesn't need to be updated unless .git or .jar web locations change
3. easy to select version using the tag
4. in a complex CMake setup with multiple libraries allows other targets to depend on antlr too
5. allows easy file copying using generator expressions, e.g. $<TARGET_FILE:antlr4_shared>
6. has CMAKE_BUILD_TYPE determined by the overall project build type, making debugging easier
7. correctly runs during configure and build steps

Of course, this is not the best example there can be and needs further improvements which I don't have the time for, but I feel like it has a better basis without juggling with tons of variables etc.

[Krzmbrzl]

My guess would be that the current approach was chosen with an older cmake version in mind (the example targets 3.7), which didn't have FetchContent yet.

However, I agree that using a more modern FetchContent-based approach would be much more convenient.
The only thing that we'd probably want is to use a shallow clone instead of a full one.