source: doc/proposals/modules-gen-hdr/README

cfa-cppp - CForall pre-preprocessor

POC deriving header files from a compile unit's source.

Input: Aet of interdependent *.src.c files, each written as if header files are not a consideration (Java-style, definitions only), annotated with both the language additions and POC scaffolding listed below.

Key Intermediate: For each %.src.c input, %.tdcl.h, %.defn.h, %.impl.c, containing relevant true-cpp #include directives of each other, such that the resulting classic-C build of a self-sufficient set of *.impl.c files gives the demo's Output.

Output: Linked and running program

Terminology
- auto: as in C, "exported from here;" different from `extern`, which means "exported by someone else" in C
- shred: "Shredding foo.src.c" means producing the "foo" Key Intermediates from the "foo" Input.
- value: the opposite of a type, includes function
- vicious: cyclic dependency that cannot be bootstrapped with the tools under POC


To run:
    if grep -q 'cfa-cppp' Makefile; then echo ok; else echo Wrong folder; fi;
    make                                    # expect success
    hello/a.out                             # expect log of fcn calls and glb-var vals
    coop/a.out                              # expect log of chickens hatching from eggs
    akwd-val-trans/a.out                    # expect four coop-like logs of a/b calls
    make err-vicious/a.out                  # expect failure after shredding done
    make clean                              # expect success
    make hello/a.out CFLAGS=-DERR1          # expect failure after shredding done
    grep -rE 'ERR[0-9]*' --include=*.src.c  # repeat prev -DERR act / do "manual" steps
                                            # on resulting grep hits


Demos are
- (`err-` means "build is expected to fail")
- hello: valid hello-world scenario with transitive dependency
  - linear (bottom-up) build order would be fine
- coop (chickens and eggs): valid circular dependency, resolved with `import auto &`
  - "as much mutual recursion as I can cram, without going vicious"
- vicious: the bridge too far, that coop resisted crossing, a:tdefs <-> b:tdefs
  - requires an out-of-scope user's recourse, like multiple manual header fragments
  - there does not exist a C-valid order of each module's offerings obtainable by ordering based on only offering sort (e.g. type definition, value declaration) and compile unit
  - would never arise as real C code, without a split like one compile unit implementing two headers
  - key difficulty: each side has a type definition that embeds a type defined on the opposite side
- typeof: valid cicular dependency, its poential hiding in typeof
  - b:vdefs -> a:tdefs -> b:vdecls
- vicious-typeof: a vicious-cycle potential hiding in typeof, a:vdecls <-> b:vdecls
  - comments under 'vicious' apply
  - (including) expect recourse like multiple manual header fragments to resolve
- vicious*/recourse-classic
  - example of a manual header split that resolves the circularity
- vicious*/recourse-proposed
  - same split, given in a plausible headerless representation that's not demo-implemented

In scope
- module-level export vs private
- automatically handle circular dependency  (demos: valid=coop invalid=err-vicious)
- ordered dependency with transitive "re-export" (demo: hello)
- separate compilation
- structs, functions and global variables

Out of Scope
- (though believed not deal breakers for this proposal)
- quality error messages
- private struct fields, friends
- illustrating how to set up a build (current Makefile is "get it to work")
- crawling imports ("first-time gcc -MMD"), determining a build order
- interaction of these modules with preexsting CFA features (current demos are C)
- extracting shred-relevant information from C source (mocked up with scaffolding below)
- C preprocessor integration: exporting a macro, ifdef'ing a #import
- user's recourse for situations where headers are not inferrable
- typedefs
- controling visibility of types (equiv. choosing to put a struct in *.h vs *.c)
- proffering implementation (equiv. function bodies in the header, like for static-inline)
- rejecting attempt to offer something public that can't be understood without seeing something private
- relaxing declare before use
- legacy integration (demo uses printf/exit as loose declarations, main as "just define it")
- linker control (demo dumps all exports into one linker namespace)


Language additions modelled
- (The proposal is to add nicer versions of these placeholders to CFA)
- module imports (#import), where `foo` corresponds with foo.c; one of:
- `#import static foo`: this implementation depends on foo's interface
  - most common, equivaluent of #include in *.c
- `#import auto & foo`: above, plus this interface mentions types from foo's interface without relying on size information
  - relevant limitation is you can't nest those types inside types defined here
  - it's a recourse for breaking a "normal" include cycle
  - syntax parallels `forall T &` emphasizing you get enough to define functions that take imported types by reference, but not by value
  - uncommon, equiv. replacing #include with a type forward declaration or giving *.fwd.h)
- `#import auto foo`: above, plus this interface has unlimited access to foo's interface (quite common, equiv. #include in *.h)

Scaffolding for the POC
- (The proposal is to have better compile-time analysis, making these elements unnecessary)
- No single-line definitions allowed
- The first line of every user-given definition is a valid declaration, with its semicolon removed and an open-curly added
- Every user-given definition is preceded, on the adjacent line, by a `//#` directive, which is the appropriate one of:
  - `@` for an exported type
  - `$f` for an exported function
  - `$v` for an exported variable
  - `-` for anything static
- Generally, abide with the shredder being brittle on whitespace

Choice: semantics of transitive import
- Option A: To import+export a depended-upon module means re-exporting both its types and its values (functions, variables)
  - Benefit: the typical basic application of C headers works this way
- Option B: To import+export a depended-upon module means re-exporting only its types
  - I'll use those types types in my exported declarations
  - by importing me, you'll get those types so that you can use my declarations
  - if you also want its values, you'll need to import them yourself
  - Benefit: gives importers a tidier symbol table; you get implicitly only what you actually need
- Incomplete Option A used in demo:  You re-export values only with `import auto M`, but not with `import auto & M`.
  - This association is unnecessary mental complexity for a user.
  - To do either a clean option A or B requires
    - adding a third header flavour (a further split of .defn.h)
    - furthermore, option A probably needs the rules for desugaring #import into #include to become transitive
  - Left KISS / "common denominator" here
  - Present-state workaround to achieve full Option A: Extra import in demo `akwd-val-trans/over_a.src.c`
  - No option-B mockup available from present state because decision "`import auto M` re-exports values" means present state does exports that option B does not want

Eventual implementation remark
- To extract shred-relevant information from C source...
- For %.c -> %.tdcl.h
  - Ignore imports
  - Need a limp-mode parser that does not differentiate types from identifiers
  - It only has to produce the list of type names (non-recursively) exported, i.e. infer the `//# @` annotations
- For %.c -> {%.defn.h, %.impl.c}
  - On seeing `import auto foo` (or `import auto & foo`), pre-load the parser's type/id table as if `import auto & foo`, i.e. recursively consult imports, in limp mode, stopping upon a cycle (like #pragma once).
  - It's not necessary to know information in foo.defn.h to shred % accurately.
  - Today's CFA parser works and is sufficient (though overkill)
  - Parsing here only needs to enable extracting a declaration from its definition.
  - User errors, like, "You tried to pass an incomplete type by value," can come out later, while compiling %.impl.c.