Getting Started

Install the Hammer parser combinator library and verify your setup. Once done, you can dive into any of the protocol examples.

---

Prerequisites

Tool	Why
GCC (or any C compiler)	Compiles parsers written with Hammer
pkg-config	Locates an installed Hammer library when not using the checkout-local build
make	Most examples use Makefiles
SCons	Required to build Hammer from source

---

Installing Hammer

Hammer must be built from source. It is not in most system package managers (yet).

1. Install GCC and SCons

sudo apt install gcc scons

2. Clone and build Hammer

git clone https://github.com/riversideresearch/hammer.git
cd hammer
scons examples

This builds Hammer plus the SCons-managed examples under build/opt/. The standalone protocol examples in examples/dns, examples/ntp, and examples/tftp can link against this checkout-local build directly.

3. Optional: install Hammer system-wide

Install Hammer only if you want to compile code outside the checkout with pkg-config libhammer:

sudo scons install
sudo ldconfig    # refresh the dynamic linker cache (Linux only)

Hammer installs a pkg-config file. Check that it's found:

pkg-config --cflags --libs libhammer

You should see output like:

-I/usr/local/include -L/usr/local/lib -lhammer

If this fails, make sure scons install completed without errors and that /usr/local/lib/pkgconfig is in your PKG_CONFIG_PATH.

Note: Hammer supports RTEMS 5 on SPARC targets, including a static (no-heap) memory mode for embedded systems. If you're building for RTEMS, see Using RTEMS instead of the instructions above.

---

Including Hammer in Your Code

Every C file that uses Hammer needs these headers:

#include <hammer/hammer.h>   // Core API: h_parse, h_uint8, h_sequence, etc.
#include <hammer/glue.h>     // Convenience macros: H_RULE, H_ARULE, H_MAKE_UINT, etc.

Compiling with Hammer

For code outside the Hammer checkout, use pkg-config to get the right compiler and linker flags:

gcc -g $(pkg-config --cflags libhammer) -o my_parser my_parser.c $(pkg-config --libs libhammer)

Or in a Makefile:

CC = gcc
CFLAGS = -g $(shell pkg-config --cflags libhammer)
LDFLAGS = $(shell pkg-config --libs libhammer)

my_parser: my_parser.c
	$(CC) $(CFLAGS) -o $@ $< $(LDFLAGS)

---

Next Steps

1. Hammer Fundamentals - Understand the core concepts.
2. Protocol Examples - Pick a protocol and build a parser.