How luxlang/lux works
1. This repository is a Lux language monorepo, not a single app. The main product is the language implementation itself, plus its standard library, compiler backends, packaging tool, docs, and tests.
2. The core language/runtime lives under stdlib/source/library/lux/** and stdlib/source/documentation/lux/**. This is where the reusable foundation is organized: data structures, control abstractions, math, concurrency, I/O, FFI, web, security, and the compiler/runtime APIs.
3. The compiler pipeline is explicit in stdlib/source/library/lux/compiler/**, especially the nested language/lux phases. The major stages are analysis, synthesis, and translation, with separate modules for each stage and for compiler metadata, caches, archives, and references.
4. Target backends are a first-class boundary. Lux can translate to JVM, JavaScript, Lua, Python, Ruby, PHP, R, Common Lisp, and C++ via stdlib/source/library/lux/compiler/language/lux/phase/translation/** and stdlib/source/library/lux/target/**. Each target has its own runtime and translation rules, so architecture diagrams should show a shared frontend feeding multiple backend-specific emitters.
5. The platform entrypoints are split into host-specific projects such as lux-jvm, lux-js, lux-python, lux-lua, lux-ruby, lux-c++, lux-php, lux-cl, and lux-r. These are thin wrappers with their own project.* files and source/program.lux, used to build or launch Lux on each host platform.
6. aedifex/ is a separate Lux application in the same repo. It appears to be the build/package/dependency toolchain, with commands for build, clean, deploy, deps, install, versioning, APKs, and POM generation. Its internal boundaries are command, dependency, repository, metadata, artifact, project, profile, and runtime.
7. The aedifex data flow is repository-oriented: project input and metadata are normalized into artifacts, resolved through local/remote/origin repositories, then deployed or installed. Supporting code covers dependency status, resolution, versioning, hashing, zipping, and path handling.
8. Tests mirror the production module layout. stdlib/source/test/** and aedifex/source/test/** largely replicate the package structure of the main code, which makes the test boundary obvious: each compiler, type, repository, command, and runtime subsystem has a matching validation suite.
9. Documentation is a separate subsystem, not just comments. The repo includes the language book in documentation/book/the_lux_programming_language/**, module docs under stdlib/source/documentation/**, and a broad bookmark/knowledge-base tree under documentation/bookmark/**. These are part of the developer experience and language specification surface.
10. The repository also contains editor/tooling integration and bootstrap scripts. lux-mode/ is the Emacs mode, and shell/lux.sh / shell/lux.bat are the cross-platform launch wrappers. These are auxiliary, but they matter for how users interact with the compiler and tools.
11. CI is GitHub Actions based. .github/workflows/test.yml runs the test workflow, and .github/workflows/setup_aedifex/action.yml suggests the build pipeline provisions the aedifex tool as part of setup. So the repo’s automation boundary is centered on compiling/testing Lux code and exercising the package tool.
12. Overall architecture: Lux source is written in .lux, parsed by compiler entrypoints, processed through a multi-phase compiler core, then emitted to one of several target runtimes. Around that core sit the standard library, the package/dependency manager (aedifex), platform-specific launchers, tests, and documentation.
Main entry points: target.lux Targets · compiler.lux Compiler · lux.lux Stdlib · aedifex.lux Aedifex
Components 31
Lux core
Standard library, language APIs, and compiler internals.
- Stdlib · Main Lux standard library and reusable language foundation.
stdlib/source/library/lux.lux - Control · Control abstractions such as IO, lazy, state, region, and scope.
stdlib/source/library/lux/control/io.lux - Data · Collections, text, format, and other foundational data types.
stdlib/source/library/lux/data/text.lux - Meta · Language reflection, code, module, and provenance APIs.
stdlib/source/library/lux/meta.lux - Compiler · Shared compiler core and language-specific compilation pipeline.
stdlib/source/library/lux/compiler.lux - Analysis · Semantic analysis and type-driven program understanding.
stdlib/source/library/lux/compiler/language/lux/analysis.lux - Synthesis · Intermediate representation construction before backend translation.
stdlib/source/library/lux/compiler/language/lux/synthesis.lux - Translation · Backend emission stage that lowers Lux to target runtimes.
stdlib/source/library/lux/compiler/language/lux/translation.lux - Compiler meta · Archives, caches, CLI, I/O, and packager support for builds.
stdlib/source/library/lux/compiler/meta.lux - Targets · Target-specific runtime definitions used by the compiler backends.
stdlib/source/library/lux/target.lux - JVM · JVM target data structures, bytecode, and runtime support.
stdlib/source/library/lux/target/jvm/bytecode.lux - JavaScript · JavaScript target runtime and code generation helpers.
stdlib/source/library/lux/target/js.lux - Python · Python target runtime and code generation helpers.
stdlib/source/library/lux/target/python.lux - Lua · Lua target runtime and code generation helpers.
stdlib/source/library/lux/target/lua.lux - Ruby · Ruby target runtime and code generation helpers.
stdlib/source/library/lux/target/ruby.lux - PHP · PHP target runtime and code generation helpers.
stdlib/source/library/lux/target/php.lux - R · R target runtime and code generation helpers.
stdlib/source/library/lux/target/r.lux - Common Lisp · Common Lisp target runtime and code generation helpers.
stdlib/source/library/lux/target/common_lisp.lux - C++ · C++ target runtime and code generation helpers.
stdlib/source/library/lux/target/c++.lux
Tooling
Package manager, launchers, editor integration, and CI.
- Aedifex · Build, dependency, deployment, and packaging application.
aedifex/source/program/aedifex.lux - Commands · CLI commands for build, clean, deps, install, deploy, test, and versioning.
aedifex/source/program/aedifex/command.lux - Dependencies · Dependency resolution, status, and deployment flow.
aedifex/source/program/aedifex/dependency.lux - Repositories · Local, origin, and remote repository boundaries.
aedifex/source/program/aedifex/repository.lux - Hosts · Thin platform-specific entrypoints for launching or building Lux.
lux-jvm/source/program.lux - CI · GitHub Actions workflows that run tests and provision Aedifex.
.github/workflows/test.yml
Docs
Language book, module docs, and knowledge base.
- Language book · The Lux programming language book and specification narrative.
documentation/book/the_lux_programming_language/index.md - Module docs · Reference documentation generated from stdlib modules.
stdlib/source/documentation/lux.lux - Bookmarks · Broad curated documentation and research tree.
documentation/bookmark.md
Tests
Validation suites mirroring the production layout.
- Stdlib tests · Production-mirroring tests for the Lux standard library and compiler.
stdlib/source/test/lux.lux - Aedifex tests · Validation suites for the package tool and repository workflow.
aedifex/source/test/aedifex.lux - Host tests · Platform wrapper and host-specific validation coverage.
lux-r/source/test/program.lux
Connections 36
- Stdlib → Control: exports · Core library includes control abstractions.
- Stdlib → Data: exports · Core library includes data foundations.
- Stdlib → Meta: exports · Core library includes meta and reflection APIs.
- Stdlib → Compiler: contains · The stdlib also hosts compiler-facing APIs and internals.
- Compiler → Analysis: phase · Frontend semantic analysis.
- Compiler → Synthesis: phase · Intermediate synthesis stage.
- Compiler → Translation: phase · Backend translation stage.
- Compiler → Compiler meta: services · Compiler metadata, archives, caches, and packager support.
- Analysis → Synthesis: feeds · Analysis produces input for synthesis.
- Synthesis → Translation: feeds · Synthesis produces input for translation.
- Translation → Targets: emits to · Translation lowers into target runtimes.
- Targets → JVM: backend · JVM backend boundary.
- Targets → JavaScript: backend · JavaScript backend boundary.
- Targets → Python: backend · Python backend boundary.
- Targets → Lua: backend · Lua backend boundary.
- Targets → Ruby: backend · Ruby backend boundary.
- Targets → PHP: backend · PHP backend boundary.
- Targets → R: backend · R backend boundary.
- Targets → Common Lisp: backend · Common Lisp backend boundary.
- Targets → C++: backend · C++ backend boundary.
- Aedifex → Commands: orchestrates · CLI command layer drives tool behavior.
- Aedifex → Dependencies: orchestrates · Dependency resolution and deployment pipeline.
- Aedifex → Repositories: orchestrates · Repository abstractions support resolution and publishing.
- Dependencies → Repositories: resolves through · Dependencies are resolved via repository boundaries.
- Repositories → Commands: used by · Commands trigger repository operations.
- Hosts → Compiler: boots · Host entrypoints bootstrap Lux compilation and execution.
- Hosts → Targets: selects · Each host wraps a specific runtime/target combination.
- Language book → Stdlib: documents · The book explains the language and its standard library.
- Module docs → Stdlib: documents · Module-level documentation mirrors stdlib structure.
- Bookmarks → Language book: supports · Reference bookmarks complement the book and specification.
- Stdlib tests → Compiler: validates · Tests mirror compiler and stdlib modules.
- Aedifex tests → Aedifex: validates · Tests cover tool commands, dependency flow, and repositories.
- Host tests → Hosts: validates · Host wrapper tests check launch/build entrypoints.
- CI → Stdlib tests: runs · CI executes the stdlib and compiler test suite.
- CI → Aedifex tests: runs · CI executes Aedifex validation.
- CI → Hosts: builds · CI also exercises host-specific packaging and setup.