Skip to content
OpenAEC-FoundationPublic

About

No description, website, or topics provided.

Resources

Stars

5 stars

Watchers

0 watching

Forks

Latest commit

 

History

1,177 Commits

Folders and files

Repository files navigation

DynLex

A natural-language-like programming language that compiles to native code via LLVM.

UI libraries and the native/browser ribbon, Snake and editor demos live in the separate dynlex-ui repository. This compiler supplies their generic section and callback facilities.

Features

  • Pattern-based syntax that reads like English
  • Compiles to native executables via LLVM
  • Static typing with full type inference
  • Standard library written in DynLex itself
  • Named compile-time values via zero-argument replacement functions (see docs/named_compile_time_values.md)
  • VS Code extension with LSP support

CAD and BIM geometry lives in the separate dynlex-cadkernel repository.

Build

./scripts/build.sh

Requires C++23, Clang 20 or newer, CMake, Ninja, nlohmann_json, Git, and GNU binutils on ELF systems. scripts/build.sh checks out and caches the exact LLVM 23 fork recorded in metadata/LLVM_TOOLCHAIN; system LLVM installations are not used. Linked Git worktrees automatically share the primary checkout's .cache/llvm-toolchain directory. The matching LLD WebAssembly driver is built and embedded in both compilers to finalize executable modules and their memory layout. Set DYNLEX_LLVM_CACHE_DIR to use an explicit cache location instead. Build that toolchain independently with:

./scripts/build_llvm.sh native

The normal build uses -O2 while retaining debug information and compiler invariants. Use ./scripts/build.sh --debug when an unoptimized executable is needed for source-level debugging. Use ./scripts/build.sh -j1 to limit compilation to one job. -j N, --jobs N, and --jobs=N also accept a positive job count.

Tests

./scripts/test.sh
./scripts/test.sh --integration

The required suite is the compiler's short iteration gate. Its 120-second process-tree budget starts immediately after the compiler build and includes compiling and running its DynLex fixtures and auxiliary checks. No test preparation is moved ahead of that timer. Required fixture builds and non-cache compiler checks disable incremental reuse; cache regressions start with fresh test projects. --run-only skips the compiler build and keeps the same process-tree budget. C++ unit checks for numeric parsing and class layout run in the required suite and in separate Linux, macOS, and Windows CI steps. The integration suite covers larger library and application programs, additional compiler regressions, runtime behavior and tooling. It has individual check timeouts but no overall 120-second limit. Release verification runs both suites. The CAD fixtures and their verifier live in dynlex-cadkernel.

Integration compilations have a 30-second default budget (60 seconds on Windows) to include optimization of application libraries. Required fixtures retain their 10-second default (20 seconds on Windows). Fixture-specific compilation budgets still apply through compile_timeout_seconds.txt.

Browser Compiler

DynLex can be built as a browser-hosted compiler module (dynlex_web.js/.wasm) with a Monaco-based web UI. This target requires Emscripten (emcmake, emcc). The build compiles and caches a WebAssembly version of the same pinned LLVM fork with the WebAssembly and SPIR-V targets. The build uses SPIRV-Cross for shader reflection and a pinned Naga WebAssembly module to validate and translate emitted SPIR-V into WebGPU's WGSL.

Build compiler WASM artifacts and copy them into the web app:

source ~/emsdk/emsdk_env.sh
./scripts/build_web.sh

The build script uses the active Emscripten SDK and builds the exact web LLVM toolchain recorded in metadata/LLVM_TOOLCHAIN.

./scripts/build_web.sh refreshes src/web/ide/public/compiler/dynlex_web.js and src/web/ide/public/compiler/dynlex_web.wasm and src/web/ide/public/compiler/dynlex_wgsl_translator.wasm; commit those files when updating the deployed web compiler.

Run the compiler WASM smoke test:

./scripts/test_web_smoke.sh

Run the web app:

cd src/web/ide
npm install
npm run dev

Refresh the deployable static web root (web/) after IDE changes:

./scripts/build_web_root.sh

View the deployable web site (web/) locally and open it in your browser:

./scripts/view_web.sh

Web layout:

  • src/web/ide/: IDE source (Vite + Monaco)
  • web/: deployable web root (site/wiki source + built IDE assets)

The web app uses:

  • one editable /workspace/*.dl entry file plus read-only imported definitions
  • bundled stdlib from /lib/*.dl in Emscripten virtual FS
  • live debounced compile with diagnostics published by the DynLex language server
  • one persistent DynLex LSP session for completion, hover, go-to-definition, semantic tokens, document symbols, quick fixes, and DynLex instantiation selection
  • live WebGPU previews for DynLex fragment/vertex shaders opened from the homepage shader gallery
  • built-in light and dark themes
  • Run executing the latest successful emitted program WASM

Compiler WASM C ABI exports:

  • dynlex_web_init
  • dynlex_web_set_main_source
  • dynlex_web_compile_and_emit_wasm
  • dynlex_web_compile_and_emit_shader_spirv
  • dynlex_web_get_diagnostics_json
  • dynlex_web_get_output_wasm_ptr / dynlex_web_get_output_wasm_len
  • dynlex_web_get_output_wasm_base64
  • dynlex_web_get_output_shader_spirv_base64
  • dynlex_web_get_shader_uniforms_json
  • dynlex_web_get_compiler_log_json
  • dynlex_web_lsp_exchange_json

Install Dependencies

Linux (apt/dnf/pacman/zypper):

./scripts/install.sh

macOS (Homebrew):

./scripts/install.sh
if brew info llvm@20 >/dev/null 2>&1; then
  export PATH="$(brew --prefix llvm@20)/bin:$PATH"
else
  export PATH="$(brew --prefix llvm)/bin:$PATH"
fi
export PATH="$(brew --prefix rustup)/bin:$PATH"
export LIBRARY_PATH="$(brew --prefix glfw)/lib:$(brew --prefix freetype)/lib:$(brew --prefix vulkan-loader)/lib:$(brew --prefix)/lib${LIBRARY_PATH:+:$LIBRARY_PATH}"

The installer reuses tools already available on PATH and installs missing Homebrew formulae without upgrading unrelated installed packages. The Homebrew LLVM formula supplies the bootstrap Clang only; DynLex links the pinned fork built by scripts/build_llvm.sh. Native graphics use the Vulkan loader on Linux and Windows and the Vulkan loader with MoltenVK on macOS. The installer also installs the pinned Rust 1.87.0 wasm32-unknown-unknown toolchain used to build the browser's SPIR-V-to-WGSL translator.

Windows (winget):

.\scripts\install.ps1

The Windows installer also installs nlohmann_json, GLFW, FreeType, and the Vulkan loader through the pinned vcpkg manifest, then exports the package paths used by scripts/build.sh.

Usage

Compile a source file:

./build/dynlex program.dl -o program.out && ./program.out

Generated programs use -O2 by default, including terminal source and WebAssembly output. Select -O0 for unoptimized code or -O3 for additional optimization; the last optimization flag wins. -O2 does not enable fast math. For source-level debugging, use -g -O0; -g alone retains the default -O2.

Native executable builds automatically reuse results from previous invocations. To inspect the cache location and compilation work:

./build/dynlex program.dl --incremental-stats -o program.out

Unchanged source/configuration and compiler options reuse the complete compilation. Comment edits can reuse analyzed code, and diagnostic-message edits in config.dl update warnings and errors without recompiling. After code edits, unaffected parser and matcher results can be restored. Without debug information or execution tracing, eligible functions also reuse inference summaries and generated LLVM bodies at all optimization levels. Optimized native builds cache LLVM optimization by symbol groups, including the callees imported into each group. Native partitions reuse cached objects, and an unchanged executable skips linking. This mode supports native executable output. Some stages still reconstruct shared state after code edits; the LSP retains its existing compilation pipeline. The cache checks file contents (including imports and syntax configuration), compiler identity and target options. Corruption is reported as an error. Disk usage is limited to 512 MiB in the system user cache directory under dynlex/compiler. Use --cache-dir <directory> to choose a different location or --no-incremental to perform a clean build. Deleting the cache is safe and makes the next build cold. Optional statistics report frontend reuse and the numbers of reused/rebuilt objects on stderr.

Emit a native object for a definition-only library. --no-main omits the entry point and rejects executable top-level statements; exposed function declarations provide the callable C ABI. With no -o, object output is written as program.o.

./build/dynlex library.dl --emit-object --no-main

--no-main can also be combined with --emit-llvm for definition-only LLVM IR. Definition-only libraries cannot use command-line argument intrinsics, because those values are initialized by DynLex's generated entry point.

Or execute DynLex source directly. Command-line source automatically imports lib/commands.dl, which provides the standard library and command-oriented libraries such as file operations:

./build/dynlex print 3
./build/dynlex 'move "a.txt" to "b.txt"'

The outer single quotes in the second example preserve DynLex's string quotes when the source passes through the shell.

Release

Compiler/release version source of truth is metadata/VERSION.

Releases use YEAR.WEEK.REVISION, with ISO week numbers and a revision starting at zero each week. Compiler, editor extension and WGSL translator share this version. Release tags have a v prefix. The release clock uses UTC.

Create and push a release tag with the next version for the current week:

./scripts/release.sh         # or an explicit version: ./scripts/release.sh 2026.45.1

Windows MSI stores the year as an offset from 2000 (26.45.1 for public version 2026.45.1) because its first version field is limited to 255. The compiler and all source package metadata retain the full public version.

ASan Leak Check (With Third-Party Suppressions)

For sanitizer leak checks that ignore known process-lifetime allocations from third-party libraries (for example LLVM internals), use:

./scripts/asan_leak_check.sh

By default this runs build-asan/dynlex with scripts/lsan.supp.

Performance Benchmarks

Benchmark details, reproducible source programs, compiler settings, and hardware-specific results:

Times are hardware- and toolchain-dependent; run the benchmark files locally for your exact environment.

Ubuntu PPA Packaging

Launchpad packaging lives in packaging/launchpad. Use that directory for Debian metadata, source-package builds, and PPA publishing so the project root stays focused on the compiler itself.

About

No description, website, or topics provided.

Resources

Stars

5 stars

Watchers

0 watching

Forks

Releases

Packages

Used by

Contributors

Languages