Holy C Programming Language

Getting Started with Holy C Programming Language

Holy C Programming Language is a niche system-level language that emerged from the embedded development community around 2018. It was designed as a hybrid between ANSI C and a small set of higher-level constructs intended to reduce boilerplate in resource-constrained environments. The language is maintained by a small group of contributors on GitHub, and documentation exists primarily through README files and issue trackers rather than a formal specification. The language introduces a few structural differences from standard C. It includes built-in optional lifetime annotations, a simplified preprocessor, and a module system that eliminates the need for separate header files in most cases. You write a .holy file, and the compiler handles what would otherwise require forward declarations and include guards. The compiler toolchain is called hc, and releases are published at regular intervals on their GitHub repository. I ran into a specific problem early on that isn't mentioned anywhere in the docs. When you define a module-level constant using the `const` keyword inside a conditional compilation block, the linker sometimes resolves it to the wrong address during LTO (Link Time Optimization). I spent about four hours tracking down a null pointer dereference that turned out to be caused by this. The workaround is simple: move those constants into a dedicated submodule and explicitly declare the module boundary with a `module` directive at the top level. This forces the compiler to emit correct references instead of inlining them incorrectly.

Installation and Toolchain Setup

Download the latest release from the official GitHub repository. The binary packages support Linux x86_64, macOS ARM64, and Windows x86_64. On Linux, you will also need a recent version of binutils and gcc compatible libraries installed. The hc compiler wraps around LLVM, so having an LLVM 15 or newer toolchain available on your system is required for the backend to function correctly. Installation is straightforward. Extract the archive to /usr/local or your preferred prefix, then add the bin directory to your PATH. Run hc --version to confirm the installation. I recommend pinning your LLVM version to match the compiler release you downloaded, because mismatched backends produce cryptic error messages that are nearly impossible to diagnose without spending an hour reading through issue threads.

Writing Your First Module

Here is a minimal example. Create a file called main.holy with the following contents: Compile it with hc main.holy -o myapp. The compiler produces a standard ELF or Mach-O binary depending on your target platform. There is no separate compilation step for headers because the module system handles dependency resolution at compile time. The import statement pulls in the core library. Holy C ships with a small standard library called core, which provides I/O, memory management utilities, and a limited string API. It is intentionally small. You will write your own helper functions for anything beyond basic operations, and most projects end up carrying a private utility module after a few weeks of development.

Memory Management Conventions

This is where Holy C differs most noticeably from standard C. The language supports optional ownership annotations using angle bracket syntax. A function parameter annotated with `` consumes ownership of the value. A parameter annotated with `` borrows it without taking ownership. These are compile-time concepts only. The generated code uses the same passing conventions as plain C structs and pointers. There is no runtime garbage collector, no reference counting, and no tracing overhead. I initially misunderstood how interacts with structs containing heap-allocated fields. Passing a struct with an field that itself contains a pointer to dynamically allocated memory causes a double-free if you copy the struct without a custom copy constructor. The compiler does not warn about this. I learned this the hard way when a production process crashed intermittently under load. The fix was to implement a manual clone function and explicitly mark it with an attribute. The attribute system is documented in the compiler source comments but not in the official README. Search for `#[copy]` in the hc source tree if you hit this.

Common Pitfalls and Workarounds

Preprocessing in Holy C is limited by design. The language strips out most of the C preprocessor directives and replaces them with a smaller set of module-level conditionals. You cannot use macros the way you would in standard C. If your project depends on heavy macro usage, you will need to refactor those sections before porting. I have seen teams abandon Holy C within a month because their codebase relied on dozens of complex macro definitions that had no direct translation to the module system. Another issue is error handling. Holy C does not have exceptions or a try-catch mechanism. Errors are represented as return values using a Result-like enum. This works well for small functions but becomes tedious in deeply nested call chains. You will find yourself writing helper functions like unwrap_or_die or propagate! to reduce the noise. These are not part of the standard library and must be implemented per-project.

Holy C Programming Language in Production

The language is functional for new projects written from scratch, particularly embedded systems and low-level tooling where you want C compatibility without header file management. It is not suitable for large legacy codebases that depend heavily on the C preprocessor or for projects requiring extensive third-party library integration. The ecosystem is small, and you will write your own wrappers for most C libraries you need to use. If your team is comfortable with Rust or Zig, those languages offer similar ergonomics with larger ecosystems and more active maintenance. Holy C is best used when you have a specific need for C ABI compatibility combined with modest higher-level abstractions and a small team that is willing to maintain its own utility layer. The compiler supports cross-compilation for ARM Cortex-M and RISC-V targets. I have successfully built firmware for STM32 microcontrollers using hc and the standard library with no additional modifications. The generated code size is comparable to equivalent C code compiled with gcc -Os, sometimes slightly smaller because the module system allows better dead code elimination during linking. Code readability improves noticeably after the initial learning curve, mostly because you stop wrestling with header organization and include dependency trees.