buildrec(3)

🌸 buildrec(3) — ANTLR3C 🌸

okay bestie, gather round, because today we're learning how to actually build the C code that ANTLR hands you. this is the ANTLR3C manual, page buildrec(3), and yes we're doing this in two parts because there's a LOT. hydrate. stretch. let's go. 💅

---

✨ NAME ✨

buildrec — How to build Generated C Code

like, the entire vibe of this page. no cap.

---

🎀 Generated Files 🎀

so here's the tea: you take the antlr tool jar, you run it against a grammar file that targets the C language, and it generates files for you. which files? that depends entirely on whether your grammar file is a lexer, a parser, a combined spec, or a treeparser spec. 🦋

and listen — your grammar file name and the subject of the grammar line inside your file are expected to match. they're supposed to be besties. if they're not matching, that's on you, not on me. 🙈

throughout this page we use the generic name G for your grammar, k? so here's the full breakdown of who gets generated when:

• lexer grammar (G.g3l) → GLexer.c, GLexer.h
• parser grammar (G.g3p) → GParser.c, GParser.h
• grammar G (G.g3pl) → GParser.c, GParser.h, GLexer.c, GLexer.h
• tree grammar G; (G.g3t) → G.c, G.h

periodt. those are your files. 👑

---

🌈 the include drama (it's giving "why won't it compile")

your generated .c files reference the .h files using <G.h>, which means you must use -I. on your compiler command line. or, if you're living that Visual Studio life, include the current directory in your include paths. non-negotiable, bestie, the compiler is NOT psychic. 😭

AND, plot twist, the generated .h files reference antlr3.h — so you also need -I/path/to/antlr/include (E.g. -I /usr/local/include) to point at the standard ANTLR include files. two include paths. two. don't skip the second one and then come crying to me. 💀

---

💖 linking time (the library era)

to reference the library file at compile time — and btw you can/should only reference one — you need:

• on Unix: -L/path/to/antlr/lib (E.g. -L /usr/local/lib)
• on Visual Studio: add that path to your "Additional Library Path"

and then you actually have to specify the library:

• on Unix: use -L (E.g. -L /usr/local/lib -l antlr3c)
• on Visual Studio: add antlr3c_dll.lib to your Additional Library Dependencies

✨ iconic. ✨

---

🫶 library or executable, dealer's choice

in case it isn't obvious (and no shade if it isn't, we've all been there), the generated files may be used to produce either a library or an executable (.EXE on Windows) file. you pick. main character energy either way.

---

🚨 IMPORTANT WARNING, FR FR 🚨 if you use the shared version of the libraries, DLL or .so/.so/.a, then you must ship the library with your application, and your app must run in an environment whereby the library can be found by the runtime linker/loader. this is not a suggestion, this is load-bearing. 🛑

usually that means specifying the directory where the library lives via an environment variable. and on Windows, X:{yourwininstalldir}\system32 will be searched automatically — so that one's handled for you. lucky you. 🍓

---

okay that's part 1, don't go anywhere, there's more coming and it's just as good 👑✨

🌸 Invoking Your Generated Recognizer 🌸

okay bestie so you've got your generated files ✨ now how do you actually RUN the lexer/parser/tree parser combo?? You need a lil function (or a main) that runs the whole sequence of events: reading the input file or string ➡️ invoking the tree parser(s) ➡️ retrieving the results. There's a whole separate doc, Using the ANTLR3C C Target, with the detailed instructions if you want the deep lore, but if you just wanna get going as fast as possible, study the following code example. it's giving long but i promise it ate 🫶

// You may adopt your own practices by all means, but in general it is best
// to create a single include for your project, that will include the ANTLR3 C
// runtime header files, the generated header files (all of which are safe to include
// multiple times) and your own project related header files. Use <> to include and
// -I on the compile line (which vs2005 now handles, where vs2003 did not).
//
#include    <treeparser.h>

// Main entry point for this example
//
int ANTLR3_CDECL
main    (int argc, char *argv[])
{
    // Now we declare the ANTLR related local variables we need.
    // Note that unless you are convinced you will never need thread safe
    // versions for your project, then you should always create such things
    // as instance variables for each invocation.
    // -------------------

    // Name of the input file. Note that we always use the abstract type pANTLR3_UINT8
    // for ASCII/8 bit strings - the runtime library guarantees that this will be
    // good on all platforms. This is a general rule - always use the ANTLR3 supplied
    // typedefs for pointers/types/etc.
    //
    pANTLR3_UINT8       fName;

    // The ANTLR3 character input stream, which abstracts the input source such that
    // it is easy to privide inpput from different sources such as files, or
    // memory strings.
    //
    // For an 8Bit/latin-1/etc memory string use:
    //      input = antlr3New8BitStringInPlaceStream (stringtouse, (ANTLR3_UINT32) length, NULL);
    //
    // For a UTF16 memory string use:
    //      input = antlr3NewUTF16StringInPlaceStream (stringtouse, (ANTLR3_UINT32) length, NULL);
    //
    // For input from a file, see code below
    //
    // Note that this is essentially a pointer to a structure containing pointers to functions.
    // You can create your own input stream type (copy one of the existing ones) and override any
    // individual function by installing your own pointer after you have created the standard
    // version.
    //
    pANTLR3_INPUT_STREAM        input;

    // The lexer is of course generated by ANTLR, and so the lexer type is not upper case.
    // The lexer is supplied with a pANTLR3_INPUT_STREAM from whence it consumes its
    // input and generates a token stream as output. This is the ctx (CTX macro) pointer
    // for your lexer.
    //
    pLangLexer              lxr;

    // The token stream is produced by the ANTLR3 generated lexer. Again it is a structure based
    // API/Object, which you can customise and override methods of as you wish. a Token stream is
    // supplied to the generated parser, and you can write your own token stream and pass this in
    // if you wish.
    //
    pANTLR3_COMMON_TOKEN_STREAM     tstream;

    // The Lang parser is also generated by ANTLR and accepts a token stream as explained
    // above. The token stream can be any source in fact, so long as it implements the
    // ANTLR3_TOKEN_SOURCE interface. In this case the parser does not return anything
    // but it can of course specify any kind of return type from the rule you invoke
    // when calling it. This is the ctx (CTX macro) pointer for your parser.
    //
    pLangParser             psr;

    // The parser produces an AST, which is returned as a member of the return type of
    // the starting rule (any rule can start first of course). This is a generated type
    // based upon the rule we start with.
    //
    LangParser_decl_return      langAST;

    // The tree nodes are managed by a tree adaptor, which doles
    // out the nodes upon request. You can make your own tree types and adaptors
    // and override the built in versions. See runtime source for details and
    // eventually the wiki entry for the C target.
    //
    pANTLR3_COMMON_TREE_NODE_STREAM nodes;

    // Finally, when the parser runs, it will produce an AST that can be traversed by the
    // the tree parser: c.f. LangDumpDecl.g3t This is the ctx (CTX macro) pointer for your
    // tree parser.
    //
    pLangDumpDecl           treePsr;

    // Create the input stream based upon the argument supplied to us on the command line
    // for this example, the input will always default to ./input if there is no explicit
    // argument.
    //
    if (argc < 2 || argv[1] == NULL)
    {
        fName   =(pANTLR3_UINT8)"./input"; // Note in VS2005 debug, working directory must be configured
    }
    else
    {
        fName   = (pANTLR3_UINT8)argv[1];
    }

    // Create the input stream using the supplied file name
    // (Use antlr38BitFileStreamNew for UTF16 input).
    //
    input   = antlr38BitFileStreamNew(fName);

    // The input will be created successfully, providing that there is enough
    // memory and the file exists etc
    //
    if ( input == NULL )
    {
            ANTLR3_FPRINTF(stderr, "Unable to open file %s due to malloc() failure1\n", (char *)fName);
    }

    // Our input stream is now open and all set to go, so we can create a new instance of our
    // lexer and set the lexer input to our input stream:
    //  (file | memory | ?) --> inputstream -> lexer --> tokenstream --> parser ( --> treeparser )?
    //
    lxr     = LangLexerNew(input);      // CLexerNew is generated by ANTLR

    // Need to check for errors
    //
    if ( lxr == NULL )
    {
            ANTLR3_FPRINTF(stderr, "Unable to create the lexer due to malloc() failure1\n");
            exit(ANTLR3_ERR_NOMEM);
    }

    // Our lexer is in place, so we can create the token stream from it
    // NB: Nothing happens yet other than the file has been read. We are just
    // connecting all these things together and they will be invoked when we
    // call the parser rule. ANTLR3_SIZE_HINT can be left at the default usually
    // unless you have a very large token stream/input. Each generated lexer
    // provides a token source interface, which is the second argument to the
    // token stream creator.
    // Note tha even if you implement your own token structure, it will always
    // contain a standard common token within it and this is the pointer that
    // you pass around to everything else. A common token as a pointer within
    // it that should point to your own outer token structure.
    //
    tstream = antlr3CommonTokenStreamSourceNew(ANTLR3_SIZE_HINT, lxr->pLexer->tokSource);

    if (tstream == NULL)
    {
        ANTLR3_FPRINTF(stderr, "Out of memory trying to allocate token stream\n");
        exit(ANTLR3_ERR_NOMEM);
    }

    // Finally, now that we have our lexer constructed, we can create the parser
    //
    psr     = LangParserNew(tstream);  // CParserNew is generated by ANTLR3

    if (psr == NULL)
    {
        ANTLR3_FPRINTF(stderr, "Out of memory trying to allocate parser\n");
        exit(ANTLR3_ERR_NOMEM);
    }

    // We are all ready to go. Though that looked complicated at first glance,
    // I am sure, you will see that in fact most of the code above is dealing
    // with errors and there isn;t really that much to do (isn;t this always the
    // case in C? ;-).
    //
    // So, we now invoke the parser. All elements of ANTLR3 generated C components
    // as well as the ANTLR C runtime library itself are pseudo objects. This means
    // that they are represented as pointers to structures, which contain any
    // instance data they need, and a set of pointers to other interfaces or
    // 'methods'. Note that in general, these few pointers we have created here are
    // the only things you will ever explicitly free() as everything else is created
    // via factories, that allocate memory efficiently and free() everything they use
    // automatically when you close the parser/lexer/etc.
    //
    // Note that this means only that the methods are always called via the object
    // pointer and the first argument to any method, is a pointer to the structure itself.
    // It also has the side advantage, if you are using an IDE such as VS2005 that can do it
    // that when you type ->, you will see a list of all the methods the object supports.
    //
    langAST = psr->decl(psr);

    // If the parser ran correctly, we will have a tree to parse. In general I recommend
    // keeping your own flags as part of the error trapping, but here is how you can
    // work out if there were errors if you are using the generic error messages
    //
    if (psr->pParser->rec->errorCount > 0)
    {
        ANTLR3_FPRINTF(stderr, "The parser returned %d errors, tree walking aborted.\n", psr->pParser->rec->errorCount);

    }
    else
    {
        nodes   = antlr3CommonTreeNodeStreamNewTree(langAST.tree, ANTLR3_SIZE_HINT); // sIZE HINT WILL SOON BE DEPRECATED!!

        // Tree parsers are given a common tree node stream (or your override)
        //
        treePsr = LangDumpDeclNew(nodes);

        treePsr->decl(treePsr);
        nodes   ->free  (nodes);        nodes   = NULL;
        treePsr ->free  (treePsr);      treePsr = NULL;
    }

    // We did not return anything from this parser rule, so we can finish. It only remains
    // to close down our open objects, in the reverse order we created them
    //
    psr     ->free  (psr);      psr     = NULL;
    tstream ->free  (tstream);  tstream = NULL;
    lxr     ->free  (lxr);      lxr     = NULL;
    input   ->close (input);    input   = NULL;

    return 0;
}

and that's it bestie, that's the whole flow 💅 it looks scary at first glance but honestly most of the code above is just dealing with errors — there isn't really that much to do (isn't this always the case in C? ;-) 😭

---

okay that's a wrap on this page fr fr 💖 this is the buildrec(3) manual page from ANTLR version 3.3.1, dated Tue Jul 29 2025 00:00:00. go build something iconic with it 👑✨