add a language document

TODO.md

@@ -4,38 +4,57 @@
 
 # milestones
 
-1. get c interop working:
-  - link with c / compile c code into binary alongside brolang code
-  - create bindings from c headers
-  - figure out how to represent variadic arguments
-    - proposal (from an older document):
-      ```
-      # functions with variadic arguments
-      printf :: c func(fmt []u8, args ...) int  # `...` is essentially an anonomous tuple type used in function arguments. `...` collects remaining arguments in a type inferred tuple (infer from anchor)
-      ```
-      - notes on structs and tuples from same older document:
-        ```
-        # structs carry only data, no methods, no behavior
-        Stuff :: struct {
-            first u32
-            second float
-            third [5]i32
-        }
-        
-        # tuples are just structs without field names (accessed via index: ``some_tuple.0``, ``some_tuple.1``, etc.)
-        # anonomous tuple type inferred from literal and type anchors?
-        some_tuple :: { 4, "hello" }
-        ```
-  - find out how this should co-exist with the import system
-    - maybe c header files should just be treated as individual packages
-      - that is also typically how they're used in c projects as they define an interface to a module (or package)
-      - that means that bindings should be automatically generated by the compiler when the user imports a c header file:
-        - `import "relative/path/to/some_header.h"` - wraps the c header file in a brolang package called `some_header`
-        - `other_header :: import "relative/path/to/some_header.h"` - wraps the c header file in a brolang package called `some_header` into `other_header` namespace
-        - implementation of the functions declared by the generated bindings is provided by the c implementation and requires the c implementation to be linked with the brolang binary
-      - this requires the ability to declare a "bare" function (as an interface) that is linked to the c implementation
-        ```
-        # declare the bare extern function for c interop (notice only the signature is provided, not the implementation)
-        # this should only be allowed for extern functions, i.e. `c func`
-        extern_c_sum :: c func(a, b int) int
-        ```
+1. manual c function interop
+   - separate calling convention, implementation, linkage, and link name
+   - allow bodyless `c func` declarations with exact external symbol names
+   - require concrete types in foreign signatures; inferred `int` is invalid
+   - emit LLVM `declare` for referenced foreign functions
+   - compile and link additional c sources, object files, and libraries through CLI options
+   - preserve bodyful, mangled, demand-monomorphized `c func` behavior
+   - verify end-to-end with an integer-only c function
+
+2. interop type foundation
+   - unsigned integers, floats, and target-dependent c scalar types
+   - keep binding mutability (`::` / `=`) separate from element or pointee mutability (`mut`)
+   - arrays and indexing
+     - `[N]T`: array with `N` logical elements
+     - `[N;S]T`: array with `N` logical elements followed by sentinel `S`
+   - pointers
+     - `@T` / `@mut T`: non-null single-item pointer without arithmetic
+     - `*T` / `*mut T`: non-null many-item pointer with arithmetic
+     - optional pointers represent nullable pointers
+   - slices and slicing
+     - `[]T`: pointer and length
+     - `[;S]T`: pointer and length with a sentinel invariant
+     - ordinary slices do not guarantee null termination
+   - string literals as immutable sentinel slices backed by static arrays
+   - character literals
+   - optionals with trapping unwrap and fallback operations
+   - native structs with compiler-controlled layout
+   - pointer-only `c struct` support with target c layout
+     - `Some :: c struct { ... }`: defined c-layout struct
+     - `Some :: c struct`: opaque c-layout struct
+     - defer passing c structs by value until target ABI classification exists
+
+3. restricted c header imports
+   - treat an imported header as a synthetic, file-local package namespace
+     - `import "relative/path/to/header.h"`
+     - `other :: import "relative/path/to/header.h"`
+   - import functions, typedefs, scalar types, and pointers to opaque records
+   - keep implementation linking separate from header imports
+   - cache imports by canonical header path and target/include/define configuration
+   - diagnose unsupported declarations when referenced
+   - research libclang's c API behind a replaceable c importer boundary
+
+4. c variadic calls
+   - represent c variadics as a fixed parameter count plus a variadic flag
+   - apply c default argument promotions at call sites
+   - emit LLVM c-variadic declarations and calls
+   - keep native brolang variadics and tuple design separate
+
+5. advanced c interop
+   - by-value records and unions
+   - function pointers and callbacks
+   - external variables
+   - macros and static inline functions
+   - exporting brolang functions to c