Build instructions¶

Dependencies¶

To build re2c from a release tarball one needs only a C++ compiler, and optionally Bash to run the tests.

To develop re2c (or to regenerate precompiled files) one also needs either CMake or Autotools (including Libtool), Bison (to rebuild parsers), rst2man (to rebuild documentation), Sphinx (to rebuild the website) and optionally Mingw and Wine (to run Windows tests on Linux). A few occasional helper scripts are written in Haskell, but they are not essential for re2c development.

Re2c is a self-hosting lexer generator, meaning that parts of its source code are written in re2c (namely, all the source .re files). Consequently, it needs an existing (and recent enough) re2c executable to rebuild these files. To bootstrap itself, re2c distributes precompiled files for each .re file. These files can be used as long as the .re files are unchanged.

Re2c has two build systems, Autotools and CMake. Both of them are maintained and tested continuously on Travis CI.

Build (Autotools)¶

To build from repository (not from a release tarball), first of all run Autotools:

$ autoreconf -i -W all

In-tree build:

$ ./configure && make && make install

Out-of-tree build:

$ mkdir .build && cd .build && ../configure && make && make install

Configure options specific to re2c (to see all options run configure --help):

--enable-debug: Enable debug checks in the re2c source code. Also enables debug options.
--enable-golang: Build re2go (identical to re2c --lang go).
--enable-libs: Build the experimental libre2c library that provides POSIX regcomp/regexec/regfree interface to re2c.
--enable-lexers: Enable regeneration of lexers from .re files (as opposed to using precompiled bootstrap files). If this option is used, RE2C_FOR_BUILD variable should contain a path to re2c executable.
--enable-docs: Enable regeneration of documentation (requires rst2man).

Cross-compile re2c for Windows (for some Mingw versions you might have to use -std=gnu++11 compiler option):

$ ./configure --host i686-w64-ming32 \
    LDFLAGS="-static -static-libstdc++ -static-libgcc"

There is a bunch of build scripts for specialized builds with Asan, Ubsan, GLIBCXX_DEBUG, etc. in the build subdirectory.

Build (CMake)¶

In-tree build (CMake puts object files in a separate subdirectory, but autogenerated files are in the source directory):

$ cmake . && cmake --build .

Out-of-tree build:

$ mkdir .build && cd .build && cmake .. && cmake --build .

CMake configuration options that are specific to re2c or have re2c-specific behaviour:

-DCMAKE_BUILD_TYPE=Debug: Enable debug checks in the re2c source code. Also enables debug options.
-DRE2C_BUILD_RE2GO=yes: Build re2go executable (an alias to re2c --lang go). Enabled by default.
-DRE2C_BUILD_LIBS=yes: Build the experimental libre2c library that provides POSIX regcomp/regexec/regfree interface to re2c.
-DRE2C_REBUILD_LEXERS=yes: Enable regeneration of lexers from .re files (as opposed to using precompiled bootstrap files). If this option is used, -DRE2C_FOR_BUILD option should be set to a path to re2c executable.
-DRE2C_REBUILD_DOCS=yes: Enable regeneration of documentation (requires rst2man).

Cross-compile re2c for Windows using Mingw:

$ cmake . -DCMAKE_TOOLCHAIN_FILE=cmake/Toolchain-cross-mingw32-linux.cmake \
    -DCMAKE_EXE_LINKER_FLAGS="-static -static-libstdc++ -static-libgcc" \
    -DBUILD_SHARED_LIBS=no

There is a bunch of build scripts for specialized builds with Asan, Ubsan, GLIBCXX_DEBUG, etc. in the build subdirectory.

Test¶

Re2c has a main test suite and a couple of small unit tests. Run them all:

$ make check

Run only the main test suite and watch the progress dumped on stdout:

$ ./run_tests.sh -j<N>

Run the main test suite with --skeleton re2c option:

$ ./run_tests.sh --skeleton

Run the test suite under Valgrind (takes some time and memory):

$ make vtests

Test mingw builds with Wine:

$ make wtests

Check the distribution:

$ make distcheck

Re2c provides a helper script build/__alltest.sh that builds and tests various re2c build flavours with Asan, Ubsan, GLIBCXX_DEBUG, etc. There is a couple of fuzz-testing Haskell scripts in the fuzz subdirectory; they are based on the QuickCheck library and can be easily modified to fuzz-test various aspects of re2c by comparing current re2c version against older versions or against other regular expression libraries.