works

CLAUDE.md

@@ -0,0 +1,117 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Project Overview
+
+This repository contains a Docker-based build system for creating statically-linked C++ executables using Alpine Linux and musl libc. It consists of:
+
+1. **dropshell-build-base**: A comprehensive C++ development base image with Drogon web framework and database support
+2. **dropshell-build**: A multi-stage Docker build system that uses the base image to compile C++ projects
+3. **ipdemo**: A sample application demonstrating the build system
+
+## Key Commands
+
+### Building the Base Image
+```bash
+cd build-base
+./build.sh
+```
+This creates the `gitea.jde.nz/public/dropshell-build-base:latest` Docker image with all dependencies.
+
+### Building a Project
+```bash
+./build.sh
+```
+This builds the project defined in `build.sh` (default: ipdemo) and outputs the binary to `output/`.
+
+### Testing the Built Binary
+```bash
+./test.sh
+```
+Runs the compiled binary from `output/` directory.
+
+### Environment Variables
+- `CMAKE_BUILD_TYPE`: Set to "Debug" or "Release" (default: Debug)
+- `PROJECT`: The project name to build (default: ipdemo)
+
+## Architecture and Design
+
+### Build System Structure
+
+The build system uses a two-stage approach:
+
+1. **Base Image** (`dropshell-build-base`): Contains all dependencies compiled from source with static linking:
+   - C++ compiler toolchain with ccache and mold linker
+   - Libraries: OpenSSL, jsoncpp, PostgreSQL, MariaDB, MySQL, SQLite3, cURL, c-ares
+   - Drogon web framework with full database support
+   - All libraries built with `-fPIC` for static linking
+
+2. **Project Build** (`Dockerfile.dropshell-build`): Multi-stage build that:
+   - Uses build cache mounts for faster rebuilds
+   - Runs cmake_prebuild.sh for custom pre-build steps
+   - Generates version information dynamically
+   - Produces a single static binary in a scratch container
+
+### CMake Configuration
+
+The CMakeLists.txt enforces static linking through:
+- `CMAKE_EXE_LINKER_FLAGS` with `-static` flag
+- `CMAKE_FIND_LIBRARY_SUFFIXES` set to `.a`
+- `BUILD_SHARED_LIBS` forced to OFF
+- Custom library paths from the base image
+
+Important: Projects must set CMAKE_PREFIX_PATH and explicitly link PostgreSQL libraries:
+```cmake
+# Set paths for libraries before finding Drogon
+set(CMAKE_PREFIX_PATH ${CMAKE_PREFIX_PATH} 
+    /usr/local/jsoncpp
+    /usr/local/openssl-musl
+    /usr/local/pgsql
+    # ... other library paths
+)
+
+# Additional PostgreSQL libraries needed for static linking
+set(POSTGRESQL_EXTRA_LIBS
+    /usr/local/pgsql/lib/libpgcommon.a
+    /usr/local/pgsql/lib/libpgport.a
+)
+```
+
+### Project Structure for New Applications
+
+New C++ projects should follow this structure:
+```
+project-name/
+├── CMakeLists.txt      # Based on ipdemo example
+├── cmake_prebuild.sh   # Optional pre-build script
+└── src/
+    ├── main.cpp        # Application entry point
+    └── version.hpp.in  # Version template
+```
+
+### Adding New Projects
+
+To build a different project:
+1. Create a directory with the project structure above
+2. Modify `build.sh` to set `PROJECT="your-project-name"`
+3. Run `./build.sh` to build
+
+### Static Linking Details
+
+The system ensures complete static linking by:
+- Using Alpine Linux's musl libc
+- Building all dependencies with `--enable-static --disable-shared`
+- Setting `-fPIC` for position-independent code
+- Using mold linker with `-static` flag
+- Configuring CMake to prefer `.a` libraries
+
+### Database Support
+
+Applications can use:
+- PostgreSQL via libpq at `/usr/local/pgsql/`
+- MySQL via client library at `/usr/local/mysql/`
+- MariaDB via connector at `/usr/local/mariadb-connector-c/`
+- SQLite3 at `/usr/local/sqlite3/`
+
+All database libraries are statically linked into the final binary.