Guide ยท v0.5
Getting started
The quickstart assumes the compiler is already installed. This page is the part that usually takes the time.
What you need
- GCC 16.2 or later, with
-freflection. Clang is not tested. - CMake 3.28 or later, and Ninja or Make.
- OpenSSL and zlib development headers (
libssl-dev,zlib1g-dev), andperl, which h2o's build runs. - Network access on the first configure, to fetch h2o. Set
FETCHCONTENT_SOURCE_DIR_H2Oto a local checkout to build offline.
There are no install() rules yet, so find_package(crocket) does not work. Use FetchContent, as the quickstart does.
GCC 16.2
Ubuntu 26.04's g++-16 package is a pre-release snapshot (16-20260322). Its reflection bugs break a translation unit that mounts routes. The errors start with accessing uninitialized member 'crocket::detail::Binding::kind'.
The toolchain crocket is developed with is GCC 16.2 on Ubuntu 26.04. ./dev gcc builds that compiler into ~/.local/gcc-16.2. CI uses the image ghcr.io/sean3z/crocket-toolchain:gcc-16.2, which already has it.
Try it without a toolchain
The hello image listens on port 8000:
docker run --rm -p 8000:8000 ghcr.io/sean3z/crocket-hello:stable
curl localhost:8000/hello/Rocketeer/42That prints Hello, 42 year old named Rocketeer!. Pin :0.5.1 when you deploy it. :stable tracks the stable release. :latest tracks main.
The same route, compiled in the browser, is on Compiler Explorer (GCC 16.2, -std=c++26 -freflection). That sketch is examples/godbolt.cpp. It has no h2o.
To work on an app inside the toolchain image:
docker run --rm -it -v "$PWD:/src" -p 8000:8000 ghcr.io/sean3z/crocket-toolchain:gcc-16.2./dev run uses the dev profile, which listens on 127.0.0.1. Inside a container, build the release tree and run the binary if you need 0.0.0.0.
Dev profile
CROCKET_PROFILE=dev is for your own machine. Compared with the release defaults it:
- Puts
ApiError::detailin error bodies, including an uncaught exception'swhat(). Release never sends that. - Writes readable log lines, colored on a terminal unless
NO_COLORis set. - Prints every route at launch, and turns on
GET /__routes. - Uses a one-hour request deadline and a one-second drain.
- Binds
127.0.0.1whenserver.hostis empty, instead of0.0.0.0.
Anything other than dev or release (or unset, which means release) throws std::invalid_argument at startup.
The next page is the overview of the handler model.