Install the Hammer parser combinator library and verify your setup. Once done, you can dive into any of the [protocol examples](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

```bash
sudo apt install gcc scons
```

### 2. Clone and build Hammer

```bash
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`:

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

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

```bash
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](Using-RTEMS) instead of the instructions above.

---

## Including Hammer in Your Code

Every C file that uses Hammer needs these headers:

```c
#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:

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

Or in a Makefile:

```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](Hammer-Fundamentals)** - Understand the core concepts.
2. **[Protocol Examples](Examples)** - Pick a protocol and build a parser.