Slopjective-C

Slopjective-C is an Objective-C 3.0 draft specification, native compiler/runtime, and validated toolchain project.

This repository now has four live surfaces that matter:

• a working draft of the Objective-C 3.0 language and runtime model,
• an in-tree native implementation under native/objc3c/,
• a checked-in standard library, tutorial, and showcase surface under stdlib/, docs/tutorials/, and showcase/,
• a large validation, packaging, release, and distribution workflow surface rooted in scripts/, tests/, and docs/runbooks/.

Current Status

The project is well past a grammar sketch.

Today it has:

• a real native objc3c compiler,
• real LLVM IR and native object emission,
• a native runtime archive and emitted runtime metadata for the object-model surface,
• a runnable subset of .objc3,
• a checked-in standard library workspace with canonical modules under stdlib/modules/,
• checked-in tutorials, migration guides, and capability-backed showcase examples,
• integrated workflow surfaces for performance, conformance, stress, external-validation, packaging, release operations, and distribution credibility,
• ongoing work to finish full runtime realization of classes, protocols, categories, properties, blocks, and ARC.

What is still incomplete:

• full live Objective-C 3.0 object-model runtime behavior,
• full property/ivar/runtime reflection closure,
• full escaping block/byref and ARC automation,
• complete runtime-backed semantics across throws/error propagation, async/task/actor concurrency, metaprogramming/property-behavior surfaces, and broader interop,
• production-strength completeness and stability claims for the full intended language/runtime envelope.

Runnable Subset

The current runnable subset is real, but it is still a subset.

What you can compile and run today:

• module declarations,
• global and local let bindings,
• fn, pure fn, and external function declarations,
• integer and boolean values,
• baseline alias surfaces such as BOOL, NSInteger, and NSUInteger,
• Objective-C-flavored signature aliases such as id, Class, SEL, Protocol, and instancetype,
• control flow:
  • if / else
  • while
  • do while
  • for
  • switch
  • break
  • continue
  • return
• arithmetic, comparison, logical, bitwise, shift, ternary, and grouping expressions,
• bracket message-send syntax through the current runtime dispatch path,
• deterministic selector/string pool and metadata-bearing object emission,
• ownership-baseline runtime behavior for supported retainable object storage.

The repo also now carries dedicated conformance and runnable-package workflows for block/ARC, concurrency, error handling, interop, metaprogramming, object-model, storage/reflection, and release-candidate validation. That means those feature families are actively modeled and validated. It does not mean every corresponding language/runtime behavior is fully complete.

What is not fully runnable yet:

• full class/protocol/category/property runtime realization,
• full property synthesis and reflective runtime consumption,
• full escaping block/byref runtime behavior,
• full ARC automation,
• complete runtime-backed closure for throws, async/await, tasks, actors, macros, property behaviors, and broader interop.

Start Here

Use the shortest path that matches what you are trying to do.

If you want to...	Start here	Then do this
understand the project	published site	read the status table and the spec map first
build or evaluate the toolchain	README.md	follow Fresh Setup, then First Working Session
inspect the checked-in stdlib surface	stdlib/README.md	then follow the core, advanced, and program runbooks
follow the runnable tutorial path	docs/tutorials/getting_started.md	compile one example first, then use the showcase surface
pick the right capability-backed example first	showcase/README.md	choose auroraBoard, signalMesh, or patchKit before reading deeper comparison text
migrate ObjC2 code or check Swift-facing migration expectations	docs/tutorials/objc2_to_objc3_migration.md	then use the broader comparison boundary only where you need it
compare ObjC3 against ObjC2, Swift, or C++ expectations	docs/tutorials/objc2_swift_cpp_comparison.md	then follow the showcase examples that back the comparison
inspect performance surfaces	docs/runbooks/objc3c_runtime_performance.md	then use the performance and compiler-throughput commands
inspect conformance, fuzz, and reporting work	docs/runbooks/objc3c_conformance_corpus.md	then use the stress, external-validation, and public-conformance workflows
inspect package, installer, and release flows	docs/runbooks/objc3c_release_foundation.md	then follow packaging channels, release operations, and distribution credibility
contribute a normal repo change	CONTRIBUTING.md	stay inside the superclean boundary and use the mapped package scripts
inspect runnable showcase examples	showcase/README.md	compile them through npm run compile:objc3c -- ... or the showcase surface check
inspect implementation boundaries	docs/objc3c-native.md	then open native/objc3c/
run exact package-script workflows	docs/runbooks/objc3c_public_command_surface.md	use the mapped npm run ... entrypoint instead of guessing
follow old spec links or archived anchors	legacy spec redirects	use this only for compatibility lookups

Documentation boundary:

• onboarding: README.md, CONTRIBUTING.md, site/index.md
• tutorials and migration guides: docs/tutorials/
• checked-in stdlib product surface: stdlib/
• runnable examples: showcase/
• implementation narrative: docs/objc3c-native.md, docs/objc3c-native/src/*.md
• operator runbooks: docs/runbooks/
• compatibility redirects: docs/reference/legacy_spec_anchor_index.md
• machine-owned outputs, not onboarding: tmp/, artifacts/, reports/

If you are new to the repo, stay out of tmp/ and the legacy redirect index until you actually need them.

Superclean Boundary

The live repo surface is intentionally narrow.

Canonical roots:

• implementation:
  • native/objc3c/
  • scripts/
  • tests/
  • stdlib/
  • schemas/
• human-facing docs:
  • README.md
  • CONTRIBUTING.md
  • site/src/
  • docs/tutorials/
  • docs/objc3c-native/src/
  • docs/runbooks/
• user-facing example sources:
  • showcase/
• generated checked-in outputs:
  • site/index.md
  • docs/objc3c-native.md
  • docs/runbooks/objc3c_public_command_surface.md
• machine-owned outputs:
  • tmp/
  • artifacts/

Explicit non-goals for cleanup work:

• reintroducing milestone-coded command aliases or sidecar compatibility files,
• treating tmp/, artifacts/, or archived redirect material as onboarding surfaces,
• hand-editing generated outputs instead of their canonical inputs.

Repository Layout

• native/objc3c/: native compiler, lowering, runtime, and driver implementation
• stdlib/: checked-in standard library workspace and package/import contracts
• showcase/: runnable example portfolio
• docs/tutorials/: learning path and migration material
• docs/runbooks/: operator-facing workflow and validation boundaries
• schemas/: checked-in artifact/report schema contracts
• scripts/: build, validation, packaging, and publication tooling
• tests/: tooling, conformance, runtime, and stress coverage
• site/: generated public overview output
• docs/reference/legacy_spec_anchor_index.md: compatibility redirects for old anchors

Dependencies

This repository is currently easiest to use on Windows with PowerShell 7.

Minimum practical setup:

• PowerShell 7 (pwsh)
• Node.js and npm
• Python 3 with pip
• LLVM installed either at C:\Program Files\LLVM or pointed to by LLVM_ROOT

What the native build script actually expects from LLVM:

• clang++.exe
• llvm-lib.exe
• libclang.lib or clang.lib
• LLVM headers under include/

What the fuller native compile-and-run path also expects:

• llc.exe

Useful optional LLVM tools for inspection and debugging:

• llvm-readobj.exe
• llvm-objdump.exe

Python packages:

• there is no repo-wide requirements.txt at the moment
• for normal local validation, install at least:
  • pytest
  • jsonschema

Notes:

• npm scripts in this repo run through PowerShell 7 because .npmrc sets script-shell=pwsh.
• If LLVM is not installed in C:\Program Files\LLVM, set LLVM_ROOT before building.
• The build script does not install LLVM for you.

Fresh Setup

From a fresh clone on this machine:

git clone https://github.com/doublemover/Slopjective-C.git
cd .\Slopjective-C
npm ci
python -m pip install --upgrade pytest jsonschema

If LLVM is installed somewhere other than C:\Program Files\LLVM, set:

$env:LLVM_ROOT = 'D:\path\to\LLVM'

Build the native compiler and runtime archive:

npm run build:objc3c-native

Expected artifacts:

• artifacts/bin/objc3c-native.exe
• artifacts/bin/objc3c-frontend-c-api-runner.exe
• artifacts/lib/objc3_runtime.lib

First Working Session

If the goal is simply to prove the repo is alive, use this order:

1. Build the native compiler:

npm run build:objc3c-native

2. Build the public site overview:

npm run build:site

Optional generated-doc refreshes:

npm run build:docs:native
npm run build:docs:commands

3. Compile the canonical hello fixture:

npm run compile:objc3c -- tests/tooling/fixtures/native/hello.objc3 --out-dir tmp/artifacts/compilation/objc3c-native/readme-hello --emit-prefix module

4. Run the bounded default validation:

npm run test:fast

5. If you need execution smoke, set llc.exe only when it is not already on PATH:

$env:OBJC3C_NATIVE_EXECUTION_LLC_PATH = 'C:\Program Files\LLVM\bin\llc.exe'
npm run test:objc3c:execution-smoke

Native Build Surface

Use these entrypoints:

• npm run build:objc3c-native
• npm run build:objc3c-native:contracts
• npm run build:objc3c-native:full
• npm run build:objc3c-native:reconfigure

Operational facts:

• native builds run through the CMake/Ninja-backed wrapper
• the persistent build tree lives under tmp/build-objc3c-native
• published binaries and libraries live under artifacts/
• contract artifacts and summaries live under tmp/artifacts/ and tmp/reports/

For the exact backend and artifact contract, use docs/runbooks/objc3c_public_command_surface.md and docs/runbooks/objc3c_maintainer_workflows.md.

Public Command Surface

Use package scripts for normal work. The public surface is now large and purpose-specific, so use the generated appendix for the full map.

Common entrypoints by job:

• bootstrap and native compile:
  • npm run build:objc3c-native
  • npm run compile:objc3c -- ...
  • npm run test:fast
  • npm run test:smoke
  • npm run test:ci
• docs, tutorials, showcase, and stdlib:
  • npm run build:site
  • npm run build:docs:native
  • npm run build:docs:commands
  • npm run test:getting-started
  • npm run test:showcase
  • npm run test:stdlib
  • npm run test:stdlib:advanced
  • npm run test:stdlib:program
• performance and diagnostics:
  • npm run inspect:objc3c:runtime-performance
  • npm run inspect:objc3c:compiler-throughput
  • npm run test:objc3c:performance
  • npm run test:objc3c:performance-governance
  • npm run test:objc3c:developer-tooling
• conformance, stress, and public evidence:
  • npm run test:objc3c:conformance-corpus
  • npm run test:objc3c:stress
  • npm run test:objc3c:external-validation
  • npm run test:objc3c:public-conformance
• packaging, release, and distribution:
  • npm run package:objc3c-native:runnable-toolchain
  • npm run package:objc3c:channels
  • npm run test:objc3c:release-foundation
  • npm run test:objc3c:packaging-channels
  • npm run test:objc3c:release-operations
  • npm run test:objc3c:distribution-credibility

Rules:

• prefer the public npm run ... surface over direct Python or PowerShell when a wrapper already exists,
• use python scripts/objc3c_public_workflow_runner.py <internal-action> only for maintainer-only command-surface upkeep that intentionally does not consume public package-script budget, specifically build-public-command-contract, check-public-command-contract, and check-public-command-budget,
• treat native/objc3c/ as the only supported compiler implementation root,
• treat stdlib/ as the canonical checked-in standard-library root instead of inventing parallel helper trees,
• use docs/runbooks/objc3c_public_command_surface.md for the synchronized command/action/backend reference,
• use docs/runbooks/objc3c_maintainer_workflows.md for maintainer-only workflow maps.

Spec Structure

The spec is organized as a small set of cross-cutting reference documents plus the numbered language parts.

Start here:

• Published site overview
• Introduction
• Specification map
• Module metadata and ABI surface tables
• Conformance profile checklist
• Legacy spec redirects for archived anchors and compatibility links only

Language parts:

Part	Focus
Part 0	Baseline rules, terminology, and normative references
Part 1	Versioning, compatibility, and conformance claims
Part 2	Modules, namespacing, and public API surfaces
Part 3	Types, nullability, optionals, generics, and key paths
Part 4	Ownership, retainable objects, and lifetime rules
Part 5	Control flow, safety constructs, and execution behavior
Part 6	Errors, Result, and throws
Part 7	Async/await, actors, and concurrency rules
Part 8	System programming extensions and low-level features
Part 9	Performance controls and runtime dynamism boundaries
Part 10	Metaprogramming, derives, macros, and property behaviors
Part 11	Interoperability with C, C++, and Swift-facing surfaces
Part 12	Diagnostics, tooling, and conformance testing

License

No repository-wide license file is currently present. Add one before treating this as a redistributable public package.