Install & first run: build, boot log, first request

Overview

2.1 Intro

Deploying a new server stack, the painful part is rarely writing code — it is environment prep: Node wants nvm and node_modules, Go wants a toolchain and GOPATH, a traditional C service wants its own build pipeline. XServer's answer is to fold all of it into build time and the binary itself: at build time your GCC produces xs.exe while the TCC compiler, the full SDK headers and system library definitions are LZMA-compressed into the binary; at runtime the target machine needs nothing installed.

So "installing XServer" is really two actions: build the host once, then run a ready-made app directory (demo-single). We start with those two.

2.2 Building the host

Two prerequisites only: GCC (select with --cc) and Python 3. In the xserver repository root:

$ build.bat                # minimal variant: default
$ build.bat sqlite xtp     # compile in the SQLite and XTP2 extensions
$ build.bat --list-extensions
available extensions: sqlite, xtp

The Linux equivalent is bash build.sh sqlite xtp. The build pipeline does five things:

The last step deserves emphasis: the artifact is replaced only after a successful link. On a failed build the xs.exe in the release directory stays untouched — this "failure protection" is guarded by a dedicated test case; interrupting a build at any moment never yields a broken binary.

2.3 Running the demo, reading the log

demo-single is the complete sample app shipped in the repository (routing, templates, SQLite, controlled pages). Enter the directory and run:

$ cd release/demo-single
$ ./xs.exe
[xs] config loaded: D:\GIT\xserver\release\demo-single/xs.json (1 servers)
[xs] server 'demo' class=http 127.0.0.1:9080 tls=off enabled
[xs]   default-host 'app' path=...\wwwroot devfile=...\main.c
[xs] engine started, workers=12
[xs] script loaded: ...\main.c (2.6 KB gen 1)
[demo] database opened: ...\db\main.db
[xs] server 'demo' http bound on 127.0.0.1:9080
[xs] running, press Ctrl+C to stop

What just happened — line by line:

2.4 Making requests

Open another terminal and send the demo a few requests (all real output):

$ curl -s http://127.0.0.1:9080/json
{"server":"xs3 demo","ok":true,"host":"app"}

$ curl -s http://127.0.0.1:9080/text
demo-single ok (from includes/demo_extra.h)

$ curl -s http://127.0.0.1:9080/api/v1/items/42
{"id":42,"name":"bench-write","created":1788494894}

$ curl -s -o /dev/null -w "%{http_code}" http://127.0.0.1:9080/nope
404
$ curl -sI http://127.0.0.1:9080/json
HTTP/1.1 405 Method Not Allowed
Allow: GET

What just happened:

• /json went through the app script's Handle_JSON — building an object with xvalue and serializing it (chapter 18's topic);
• /api/v1/items/42 hit the dynamic route /api/v1/items/{id}; the captured segment 42 was looked up in SQLite (chapter 17);
• /nope matched no route and no app handler → 404;
• HEAD /json got 405 + Allow: GET — the route's method mask registered only GET, and HEAD was rejected at the method slot before reaching the handler. A real routing detail; chapter 17 covers how to handle HEAD.

2.5 Contract

• Threading: workers is fixed at startup and immutable across hot reload (changes are rejected).
• Variants: the build variant decides which symbols scripts may use — the default variant has no sqlite3_* / xtp2_*; using them fails the compile.
• Data: the demo's db/main.db is a real data file; experiment freely and rebuild the repository to restore it.

Common mistakes

./xs
bind failed
./xs          /* retry over and over, no idea who holds the port */

netstat -ano | findstr 9080
/* change xs.json's port, or kill the holder */

copy xs.exe C:\tools\
C:\tools\xs.exe      /* config load failed */

/* keep xs.json and the source directory next to the exe;
 * or pass the config path explicitly */
./xs D:\apps\myapp\xs.json

Exercises