HitSimple

HitSimple is an experimental programming language and a C++20 compiler. Its core model is "data resides in memory, and meaning comes from explicit interpretation": the same bytes can be interpreted as integers, floating-point values, strings, addresses, or structured layouts, while storage remains separate from interpretation templates.

The compiler pipeline is operational end to end:

source -> preprocessor -> lexer -> parser -> AST -> sema -> HIR -> LLVM IR -> executable

Standard.md is the authority for language semantics. The current tests validate implemented behavior; they do not replace a clause-by-clause review of the Standard.

hitsimple-language-skill.zip is a Skill for AI Agents that allows AI to learn how to write HitSimple programs

Current Status

v0.3.7 is the current Beta release with builds for:

• Linux x86_64/aarch64 tar.gz archives.
• Linux amd64/arm64 DEB packages.
• macOS arm64/x86_64 tar.gz archives.
• Fedora 44 and EL9 x86_64/aarch64 RPM packages.
• Windows x64 full/slim ZIP archives.
• A VS Code extension VSIX.

Windows builds programs only for the current Windows x64 platform, with the target ABI fixed as x86_64-w64-windows-gnu. macOS uses the current native Darwin target. The release scope excludes other UNIX platforms and does not provide cross-target hsc --target support.

On Windows and macOS, f128 uses Boost 1.85.0 cpp_bin_float as a 113-bit software backend and passes raw IEEE 754 binary128 bit patterns across runtime boundaries. Decimal conversion and binary128 encoding explicitly use roundTiesToEven; preservation and propagation of NaN payloads remain implementation-defined. Linux continues to use native LLVM fp128 and glibc interfaces.

The generated standard-library headers expose one public View contract per API. --stdlib-provider=optimized is the default. --stdlib-provider=reference selects a manifest-declared reference implementation when one exists, and uses the default provider for the remaining APIs. Provider selection happens at compile time and does not alter public semantics or the selected safety mode.

Build from Source

Requirements:

• CMake 3.24 or later.
• A C++20 compiler.
• LLVM development packages.
• Bison.
• re2c.
• Clang.

macOS builds also require Boost 1.85.0 or later. Release packages require an external Clang toolchain whose major version matches their embedded LLVM for final linking.

cmake -S . -B build
cmake --build build --parallel

The resulting compiler is build/hsc.

First Program

The repository includes examples/hello.hs:

$include <stdio.hsh>

func main() {
    new x[1]
    x %d= 42
    printf("%d\\n", x)
    return 0
}

./build/hsc examples/hello.hs -o hello
./hello

Linux Distribution Packages

The DEB installation layout is:

/usr/bin/hsc
/usr/libexec/hitsimple/hsc_mcpp
/usr/lib/hitsimple/libhitsimple_runtime.a
/usr/share/hitsimple/stdlib
/usr/share/doc/HitSimple

Install a local DEB package:

sudo apt install ./hitsimple_0.3.7_amd64.deb

Use hitsimple_0.3.7_arm64.deb on arm64. The package depends exactly on clang-18, matching its embedded LLVM 18. Debian 13's default clang is version 19, so it is not interchangeable; apt installs clang-18 as part of the package transaction. When the default Ubuntu 22.04 or Debian 12 repositories do not provide Clang 18, first configure the corresponding jammy or bookworm repository from apt.llvm.org; the DEB package does not modify system package sources.

The tar.gz archive is a relocatable directory package. Run its bin/hsc directly after extraction. The compiler locates the preprocessor, standard library, and runtime relative to its own location.

Fedora 44 and EL9 each provide x86_64/aarch64 RPM packages, for example:

sudo dnf install ./hitsimple-0.3.7-1.fc44.x86_64.rpm

EL9 uses the 1.el9 release suffix. RPM packages install to /usr/bin, /usr/libexec/hitsimple, the distribution library directory (/usr/lib64/hitsimple on x86_64/aarch64), and /usr/share/hitsimple; the system must already provide clang >= 18. They do not bundle Clang or provide a GPG signature. Fedora 44 and EL9 are the only currently supported RPM baselines.

macOS Distribution Packages

hitsimple-0.3.7-macos-arm64.tar.gz
hitsimple-0.3.7-macos-x86_64.tar.gz

After extraction, use bin/hsc directly. The package locates hsc_mcpp, the static runtime, and the standard library relative to the executable, so the extracted directory remains usable after being moved. The system must provide a Clang toolchain matching the embedded LLVM major version, selected through --clang, HITSIMPLE_CLANG, or PATH.

macOS provides only unsigned relocatable tar.gz archives; no signing, notarization, or PKG installer is provided.

Windows Distribution Packages

Full package:

hitsimple-0.3.7-windows-x86_64-full.zip

It includes hsc.exe, the standard library, the static runtime, and the pinned llvm-mingw-20240619-ucrt-x86_64 toolchain. No Visual Studio or system Clang installation is required after extraction.

Slim package:

hitsimple-0.3.7-windows-x86_64-slim.zip

The slim package requires a compatible llvm-mingw/Clang 18 installation. Toolchain lookup order is:

1. --clang <path>.
2. HITSIMPLE_CLANG.
3. toolchain/bin/clang++.exe in the full package.
4. clang-<embedded LLVM major version>.
5. clang and clang++ on PATH.

When -o is omitted, Windows generates a.exe by default. User programs link the GCC/C++ runtime statically and should depend only on Windows system DLLs.

Compiler Usage

hsc [options] <input>...

Common commands:

hsc examples/hello.hs -o hello
hsc --checked examples/hello.hs -o hello-checked
hsc --emit-llvm examples/hello.hs -o hello.ll
hsc --emit-object examples/hello.hs -o hello.o
hsc --crate-type=staticlib path/to/library.hs -o libexample.a
hsc --clang /path/to/clang++ examples/hello.hs -o hello
hsc app.hs --c-source native/helper.c -o app
hsc app.hs --cxx-source native/wrapper.cpp -o app
hsc app.hs --cargo-manifest rust/Cargo.toml -o app
hsc --target-info

See USAGE.md for complete CLI documentation. See Standard.md for the language model, standard templates, safety semantics, and ABI contracts.

For C ABI interoperability, use explicit extern "C" declarations and exports. C++ must expose an extern "C" wrapper; Rust must export an unmangled pub extern "C" function. USAGE.md documents the supported value types and object/static-library commands. On Linux x86_64 and AArch64, hsc can also compile explicit C/C++ inputs, link objects/archives/libraries, and build one Cargo staticlib selected from Cargo JSON output. A HitSimple main is the default entry; --entry=native selects a C/C++ main for a HitSimple library. Cargo virtual workspaces require --cargo-package; Cargo and Rust never cross the ABI boundary through Rust main or the Rust ABI.

VS Code Extension

The extension source is in vscode/hitsimple/. It provides syntax highlighting, indentation, snippets, the $hsc Problem Matcher, and Build/Run/Debug Current File commands. The matcher consumes default human diagnostics, including file-level errors at the relevant input's line 1, column 1. --diagnostic-format=json is for direct CLI consumers and must not be added to extension build arguments. Debug Current File rebuilds the active .hs entry with -g -O0, then starts the native Microsoft C/C++ debugger. It does not create launch.json or override F5.

cd vscode/hitsimple
npm ci
npm test
npm run package:vsix
code --install-extension dist/hitsimple-vscode-0.3.7.vsix --force

Key settings:

Setting	Default	Purpose
hitsimple.compilerPath	hsc	Compiler executable name or path.
hitsimple.mode	unchecked	Selects unchecked, static-checked, or checked.
hitsimple.outputDirectory	.hitsimple/build	Output directory inside the workspace.
hitsimple.additionalArgs	[]	Additional arguments passed as separate argv entries; do not add --diagnostic-format=json, because $hsc consumes human diagnostics.
hitsimple.gdbPath	gdb	GDB executable name or path used by Debug Current File.
hitsimple.lldbPath	lldb	MI-compatible LLDB executable name or path used by Debug Current File on macOS; the default uses cpptools' bundled signed lldb-mi when available.
hitsimple.debugArguments	[]	Program arguments passed as separate argv entries when debugging.

Debug Current File supports native Linux x86_64/aarch64 through cppdbg with GDB, native macOS arm64/x86_64 through cppdbg with LLDB, and native Windows x64 through cppvsdbg with CodeView/PDB. It requires the Microsoft C/C++ extension (ms-vscode.cpptools); Linux also requires an executable GDB. On macOS, the default hitsimple.lldbPath uses the signed lldb-mi bundled by cpptools; a custom path must name an executable MI-compatible LLDB. Windows debug builds remove stale PDB files and require a new .pdb alongside the executable. Remote debugging, cross-target debugging, custom debug adapters, and custom launch.json configurations remain outside this command's scope.

Haskell also uses .hs. When both language extensions are installed, explicitly associate the extension in the workspace:

{
  "files.associations": {
    "*.hs": "hitsimple"
  }
}

Verification

./build/hsc_unit_tests
cmake -DBUILD_DIR=build -P cmake/RunQuietTests.cmake

VS Code Extension Host tests install ms-vscode.cpptools into an isolated extension directory. Headless Linux environments also require xvfb-run and GDB; macOS uses cpptools' bundled signed lldb-mi. Each supported native target verifies a HitSimple breakpoint, helper and main stack frames, and the value local:

cd vscode/hitsimple
xvfb-run -a npm run test:extension

Known Boundaries

• Checked mode does not yet fully track boundaries for extern globals, raw FFI addresses, or file-handle ownership/open state; null handles passed to checked file I/O are rejected.
• C compatibility is a restricted subset. C struct pass-by-value ABI supports only covered x86_64 SysV ELF layouts; Windows and Darwin reject it explicitly.
• f16 arithmetic computes through f32 before writing back. Linux f128 depends on platform binary128/glibc support; Windows and macOS use the software backend.
• mut self and ordinary mut parameters remain reserved semantics and produce explicit diagnostics.

License and Third-Party Components

HitSimple is licensed under the GNU Lesser General Public License v3.0 or later (LGPL-3.0-or-later); see LICENSE. Release packages include this license and licenses or copyright notices for used third-party components, including mcpp, LLVM/llvm-mingw, and the Boost Software License 1.0. Review those terms separately before using or redistributing them.