#+OPTIONS: toc:t num:nil
* The Core Philosophy
-This project moves away from "techno-idiosyncratic" directory names (like ~source~, ~bin~, or ~src~) in favor of names that describe the *fundamental invariants* of the files they contain.
+This project distinguishes files based on fundamental **invariants** (properties) rather than arbitrary file types[cite: 889, 890]. This creates a clear semantic structure:
+- **Provenance**: Who created this file?
+- **Capability**: What is the file's primary function in the system? [cite: 890, 891]
-We distinguish files based on two properties:
-1. **Provenance**: Who created this file?
-2. **Capability**: What can the system do with this file?
-
-**The Golden Rule:**
-- **God, Artists, and SQL** (and Developers) *create* things.
-- **Factories** (Build Systems) *make* things.
+**The Golden Rule:** God and Artists (Developers) *create* things; Factories (Build Systems) *make* things[cite: 892].
* Directory Structure Overview
#+BEGIN_SRC text
developer/
-├── authored/ # (The Truth) Human-written code.
-├── loadable/ # (The Entry Points) Script links & architecture-independent runners.
-├── scratchpad/
-│ └── loadable/ # (The Heavy Machinery) Compiled binaries. Ignored by Git.
-└── tool/ # (The Factory) Build scripts and orchestrators.
+├── authored/ # (The Logic) Human-written source code.
+├── loadable/ # (Capability) Agnostic Entry Points.
+├── scratchpad/ # (Transient) Intermediates, Objects.
+└── tool/ # (The Factory) Build scripts.
+
+release/
+├── loadable/ # (Capability) Shared, Agnostic Release Entry Points.
+├── local_build/ # (Action/Locality) Architecture-specific binaries.
#+END_SRC
-* Detailed Definitions
+* Detailed Invariants
** ~developer/authored/~
-This directory contains the *primary truth* of the project.
-- **Invariant:** Every file here is written by a human author (the Artist).
-- **Rule:** Build scripts generally have *read-only* access to this directory. They should never modify files here.
-- **Contents:** C source files (~*.c~), Python modules (~*.py~), Header files (~*.h~).
+- **Invariant:** Primary Logic Source (Code). Every file here is written by a human author[cite: 898, 899].
+- **Rule:** Scripts must treat this directory as read-only. This replaces the old `cc/` and `python3/` source directories.
** ~developer/loadable/~
-This directory contains the *entry points* for the system.
-- **Invariant:** Files here possess the property of being "loadable" (runnable) by the user or the OS.
-- **Contents:**
- - Symlinks to interpreted code (e.g., links to ~../authored/CLI.py~).
- - Shell wrappers.
- - Architecture-independent runners.
+- **Invariant:** Architecture-Agnostic Entry Points. Files here possess the property of being executable by the user[cite: 902].
+- **Contents:** Symlinks to interpreted code, shared scripts, and wrappers that are safe to commit[cite: 903].
** ~developer/scratchpad/loadable/~
-This directory contains the *machine-generated* executables.
-- **Invariant:** These files are derived/synthesized by the factory (Make).
-- **Rule:** This directory is **ignored by Git**. It prevents binary blobs and architecture-specific files from polluting the repository.
-- **Contents:** Compiled C binaries, object files, and temporary build artifacts.
-
-* Workflow Examples
-
-** Scenario A: Working with C (Compiled)
-1. **Author:** You write ~my_program.c~ in ~developer/authored/~.
-2. **Build:** You run ~tool/make~.
-3. **Result:** The compiler reads ~authored/my_program.c~ and synthesizes a binary at ~developer/scratchpad/loadable/my_program~.
- - *Note:* This binary is transient. If you delete ~scratchpad/~, it can be rebuilt.
-
-** Scenario B: Working with Python (Interpreted)
-1. **Author:** You write ~my_script.CLI.py~ in ~developer/authored/~.
-2. **Setup:** You (or a setup script) create a semantic link.
-3. **Result:** A link exists at ~developer/loadable/my_script~ pointing to the authored file.
- - *Note:* This makes the script "loadable" from the system path without moving the source of truth.
-
-* The Release Process
-When the project is ready for distribution, the release script collects items from both sources:
-- It takes the *logic* from ~authored~.
-- It takes the *binaries* from ~scratchpad/loadable~.
-- It places them into the final ~$REPO_HOME/release/~ sub directories for the end-user.
-It is common that the developer customizes the release script.
+- **Invariant:** Machine-Generated Executables (Intermediate). This is the transient output location during development[cite: 904].
+- **Rule:** This directory is **ignored by Git** and houses compiled binaries and libraries derived by the build system[cite: 905, 906].
+
+** ~release/local_build/~
+- **Invariant:** Local Action Required.
+- **Rule:** This directory is added to the `.gitignore` in the release directory. Its presence signals to a new developer: **"You must perform a local build to populate this directory with machine-specific executables."**
+- **Contents:** Final binaries are copied here by the release script from the `scratchpad/`[cite: 915].
+ <
--- /dev/null
+Ah oui. Donc ..
+
+This is what I would like you to do. Start over on the core code.
+
+1. there is git ignore class.
+
+A 'discern' function is any function that is given a project path and a relative path into the project, and then returns either 'Accept' or 'Ignore'.
+
+The git ignore class holds a discern function stack. Said stack is initialized with a triple. the first of the pair is a discernment function that always returns 'Accept'. The second in the triple is a project path, and the third a relative path to a directory where said .gitignore was found.
+
+Initially the stack is empty.
+
+Said class has a method called `check` that returns either 'Accept' or 'Ignore'.
+
+When traversing a project tree, typically Harmony, or <other>, the traversing function will send each (<project>, <rel>, <information>) triple to the `check` method of the git ignore class instance. For our program we have one such instance.
+
+The `check` method: 1) if the discern stack i snot empty, `check` calls the discern functions on the ignore function stack, if any of them returns 'Ignore' the `check` method immediately returns 'Ignore'. 2) if all `discern` function returns `Accept`, and the node name is '.gitignore', then:
+2.1 the top of the discern stack path is checked and compared to the path to the node given to `check`. If the path is the same, then we have a strange error, we have seen two files called .gitignore in the same directory. I guess we go buy a lottery ticket.
+2.1 the path to the node is sent to then sent to `parse_gitignore` function which returns a discern function. That functino as part of the triple, is pushed onto the git ignore instance's discern function stack.
+
+When ever the traversing function pops back up, it calls the classe's 'pop' function which pops the top off of the git ignore instance's discern function stack.
+
+A note about the gitignore file parser: currently (see to-do list) it returns one of two dicern functions. If the relative path is empty, i.e. we are at the top of the project, then it returns a discern function that returns Accept. If the relative path is not empty, it returns a discern function that always returns 'Ignore'.
+
+2. The <other> subset Harmony checker:
+
+2.1 First traverse the entire Harmony tree. That is the tree that has the tool directory the checker is running from.
+
+For each node in the Harmony tree:
+2.1.1 check if it is to be ignored, if so skip it
+2.1.2 take said node's relative path and use it as a key for a new entry in the 'skeleton dictionary'. Make the entry value 'information' about its node.
+
+A node's 'information' includes: modification date, and its type being file or directory or something else, and if it is a leaf node or not in the tree. (surely 'make_information' is a separate function). If the 'checksum' command is given, then the node's checksum becomes part of information. (new command)
+
+
+2.2 traverse the <other> tree and make two sets:
+2.2.1 an 'ignored' set, of the relative paths to ignored files. This will require making a git ignore class instance and calling the proper methods while doing a traversal.
+2.2.2 look up the relative path to the <other> node in the skeleton dictionary
+2.2.2.1 if lookup information says the <other> node corresponds to a leaf node in the skeleton, do not descend into this node.
+2.2.2.2 if the lookup into the skeleton dictionary fails, add this node to the 'addendum' list.
+
+
+2.2 traverse the skeleton dictionary entries
+
+for each entry:
+2.2.1 Check if the relative path is in the <other> gitignored set.
+2.2.1.1 If so add it to the 'present_but_ignored' list. Continue to the next entry. Otherwise:
+2.2.1.2 Use the relative path (the dictionary key) to extend the <other> project path to get an <other> node path.
+2.2.1.2.1 check if such a node exists (likely either a file or a directory it is exists)
+2.2.2.2.1.1 If there is not an <other> node found: add said relative path to the 'missing' list, and continue to the next entry. Otherwise:
+2.2.2.2.1.2 If the skeleton dictionary information says it is a leaf node in the skeleton, but it is not a leaf node in <other> then send this directory node to the addendum descender function. (The addendum descender function then descends from said <other> node, while appending all node relative paths discovered into the addendum list.)
+2.2.2.2.1.3 If the <other> node has a more recent modification time add its relative path to the 'newer' list. If it is older add it to the 'older' list. If it is the same age, and the 'checksum' command has been given, compare the checksums. If they differ, then add the relative path to the 'different' list.
+
+3. Make reports. Each report we are to generate corresponds to a command name. We will need additional commands to cover the additional lists I described in this spec. The 'all' command will generate all the reports, of course.
--- /dev/null
+skeleton_diff — Harmony skeleton vs <other> spec
+===============================================
+
+0. Context
+0.1 Harmony is the authoritative skeleton.
+0.2 Each Harmony derived project (“<other>”) starts as a clone of Harmony.
+0.3 Over time:
+ 0.3.1 Harmony evolves.
+ 0.3.2 Individual projects evolve.
+ 0.3.3 Some improvements flow back to Harmony, some do not.
+0.4 The goal is to detect and reason about drift between Harmony and <other>
+ using a clear, explicit model of:
+ 0.4.1 The Harmony skeleton (authoritative source of structure).
+ 0.4.2 The <other> tree (authoritative source of what actually exists).
+ 0.4.3 Git ignore semantics (even if approximated at first).
+ 0.4.4 Node level information (type, mtime, leaf status, checksum).
+
+1. GitIgnoreDiscern class
+1.1 A “discern” function
+ 1.1.1 Signature: discern(project_root, rel_path, info) -> "Accept" | "Ignore".
+ 1.1.2 rel_path is a Path relative to project_root.
+ 1.1.3 info is node information (see section 2.3).
+1.2 GitIgnoreDiscern instance
+ 1.2.1 Holds a “discern function stack”.
+ 1.2.2 Each entry in the stack is a triple:
+ (discern_function, project_root_path, rel_dir_path_of_gitignore)
+ 1.2.3 The stack is initialized empty.
+1.3 check method
+ 1.3.1 Input: (project_root, rel_path, info).
+ 1.3.2 Behavior:
+ 1.3.2.1 If the discern stack is not empty:
+ - Iterate from top to bottom (or bottom to top, but chosen and
+ documented) calling each discern function.
+ - If any discern returns "Ignore", then check returns "Ignore".
+ 1.3.2.2 If all discern functions return "Accept", then:
+ - If the node name is ".gitignore", we handle it specially
+ (see 1.4).
+ - Otherwise, return "Accept".
+1.4 Handling ".gitignore"
+ 1.4.1 When check sees a node whose name is ".gitignore":
+ 1.4.1.1 The path of the directory that contains this .gitignore is rel_dir.
+ 1.4.1.2 For now we do not attempt to detect “two .gitignore files in the
+ same directory”; that would indicate a malformed filesystem.
+ 1.4.1.3 We call parse_gitignore(project_root, rel_dir) which returns a
+ discern function.
+ 1.4.1.4 We push (discern_function, project_root, rel_dir) onto the
+ discern function stack.
+ 1.4.1.5 check returns "Accept" for the .gitignore file itself.
+1.5 pop method
+ 1.5.1 The tree traversal logic must call a pop method whenever it pops
+ back up from a directory that had a .gitignore.
+ 1.5.2 pop removes the top triple from the discern function stack.
+1.6 parse_gitignore approximation
+ 1.6.1 For now (heuristic phase):
+ 1.6.1.1 If rel_dir is empty (we are at the project root):
+ - Return a discern function that always returns "Accept".
+ 1.6.1.2 If rel_dir is not empty:
+ - Return a discern function that always returns "Ignore" for
+ any node under that directory (except the .gitignore itself).
+ 1.6.2 Future work (TODO):
+ 1.6.2.1 Properly parse .gitignore content.
+ 1.6.2.2 Build discern functions that implement the documented
+ semantic of .gitignore patterns.
+
+2. Harmony dictionary (“skeleton dictionary”)
+2.1 Traversal
+ 2.1.1 Traverse the entire Harmony tree.
+ 2.1.2 This is the tree that contains the tool directory skeleton_check is
+ running from, or equivalently the tree rooted at $REPO_HOME.
+ 2.1.3 The traversal:
+ 2.1.3.1 Maintains a GitIgnoreDiscern instance.
+ 2.1.3.2 For each node encountered:
+ - Build rel_path, the path relative to Harmony root.
+ - Build info (see 2.3).
+ - Call gitignore.check(HARMONY_ROOT, rel_path, info).
+ - If "Ignore", skip the node (and if it is a dir, do not descend).
+ - If "Accept", proceed.
+2.2 Skeleton dictionary
+ 2.2.1 For each accepted node:
+ - Use rel_path as a dictionary key.
+ - Store a NodeInfo object as the value.
+ 2.2.2 All rel_paths in this dictionary are part of the “skeleton”.
+2.3 Node information (“information”)
+ 2.3.1 Fields:
+ 2.3.1.1 path_type: "file" | "dir" | "other".
+ 2.3.1.2 mtime: numeric modification timestamp.
+ 2.3.1.3 is_leaf_flag: bool, true if the node is a leaf in the tree.
+ 2.3.1.4 checksum: optional checksum (string or bytes) when enabled.
+ 2.3.2 Leaf definition:
+ 2.3.2.1 For directories: a dir is a leaf if there are no child nodes
+ recorded beneath it (no children in the dictionary).
+ 2.3.2.2 For files and “other”: they are trivially leaves as far as
+ the tree structure is concerned.
+2.4 Checksum mode
+ 2.4.1 If the “checksum” command has been given:
+ 2.4.1.1 NodeInfo includes a checksum of file contents.
+ 2.4.1.2 For non files, checksum may be None.
+ 2.4.2 Computing checksums is optional and may be expensive.
+
+3. <other> traversal and ignored set
+3.1 Traversal of <other>
+ 3.1.1 We traverse the <other> tree (project root = other_root).
+ 3.1.2 We use a *separate* GitIgnoreDiscern instance for <other>.
+ 3.1.3 For each node:
+ 3.1.3.1 Compute rel_path relative to other_root.
+ 3.1.3.2 Compute NodeInfo for that node.
+ 3.1.3.3 Call gitignore.check(other_root, rel_path, info).
+3.2 Ignored set
+ 3.2.1 If gitignore.check says "Ignore":
+ 3.2.1.1 Do not descend into that node if it is a directory.
+ 3.2.1.2 Add rel_path to the “ignored” set for <other>.
+ 3.2.2 If gitignore.check says "Accept":
+ 3.2.2.1 Do descend into directories.
+ 3.2.2.2 Do *not* add this rel_path to the “ignored” set.
+3.3 Skeleton lookup while traversing <other>
+ 3.3.1 For each accepted <other> node:
+ 3.3.1.1 Look up rel_path in the skeleton dictionary.
+ 3.3.1.2 Cases:
+ a) Found in skeleton_dict:
+ - skeleton_info = skeleton_dict[rel_path].
+ - If skeleton_info.is_leaf_flag is True and the
+ <other> node is a directory, then:
+ * This directory corresponds to a skeleton leaf.
+ * Do not descend further in the *outer* traversal.
+ * Let the addendum descender handle any deeper nodes.
+ b) Not found in skeleton_dict:
+ - Add rel_path to the “addendum seed” list (see 4.1.3).
+ - Descend normally; deeper nodes are also addendum candidates.
+
+4. Comparing skeleton_dict and <other>
+4.1 Lists to construct
+ 4.1.1 missing_list
+ - Paths that exist in skeleton_dict but do not exist in <other>
+ (and are not in the ignored set for <other>).
+ 4.1.2 present_but_ignored_list
+ - Paths that exist in skeleton_dict, and whose rel_path appears
+ in the <other> ignored set.
+ 4.1.3 addendum_list
+ - Paths that exist in <other> but not in skeleton_dict.
+ - This may be built by:
+ a) While traversing <other>, for any accepted node whose
+ rel_path is not in skeleton_dict, add it to addendum_list.
+ b) Additionally, when we find an <other> directory node that
+ corresponds to a skeleton leaf directory, an “addendum
+ descender” may be called starting from that node to gather
+ all project specific material under that subtree into
+ addendum_list.
+ 4.1.4 newer_list
+ - For nodes where rel_path exists in both skeleton_dict and
+ <other>, and both are files:
+ - If mtime(other) > mtime(skeleton), add rel_path to newer_list.
+ 4.1.5 older_list
+ - As above, but mtime(other) < mtime(skeleton).
+ 4.1.6 different_list (checksum mode)
+ - If checksums are available and mtime(other) == mtime(skeleton),
+ but checksum(other) != checksum(skeleton), add rel_path to
+ different_list.
+
+4.2 Detailed skeleton dictionary scan
+ 4.2.1 For each entry in skeleton_dict:
+ 4.2.1.1 Let rel_path be the key, skeleton_info the value.
+ 4.2.1.2 If rel_path is in <other> ignored set:
+ - Add rel_path to present_but_ignored_list.
+ - Continue to next skeleton entry.
+ 4.2.1.3 Construct other_path = other_root / rel_path and see if it exists.
+ a) If other_path does not exist:
+ - Add rel_path to missing_list.
+ - Continue.
+ b) If skeleton_info.is_leaf_flag is True and the
+ other_path is a directory:
+ - This is a subtree under a skeleton leaf.
+ - Call the addendum descender on other_path to
+ gather project specific additions.
+ - Continue after that.
+ c) If both sides are files:
+ - Compare mtimes and optional checksums and update
+ newer_list, older_list, different_list.
+
+5. Commands and reports
+5.1 Commands correspond to reports or combined analyses:
+ 5.1.1 environment
+ - Print environment, including REPO_HOME and useful Harmony variables.
+ 5.1.2 structure
+ - Use skeleton_dict and <other> to report missing directories and
+ structural drift.
+ - Interpret “between” vs “below” using skeleton leaf boundaries:
+ - Missing nodes under skeleton directories indicate incomplete
+ adoption in <other>.
+ - Extra nodes under skeleton leaf directories indicate “below”
+ project additions.
+ 5.1.3 import
+ - Use newer_list.
+ - Print cp commands to copy from <other> into Harmony.
+ - Do not execute the commands.
+ 5.1.4 export
+ - Use older_list.
+ - Print cp commands to copy from Harmony into <other>.
+ - Do not execute the commands.
+ 5.1.5 suspicious
+ - Use addendum_list plus knowledge of expected zones:
+ - Ignore developer/, tester/, release/ (user owned).
+ - Ignore tool/ and tool_shared/ (tool zones).
+ - Anything else that is not in skeleton_dict and not in
+ user owned or tool zones is suspicious.
+ 5.1.6 addendum
+ - Report project specific additions under tool/ and tool_shared/
+ that are not in skeleton_dict.
+ - Essentially a filtered view of addendum_list.
+ 5.1.7 checksum
+ - Enable checksum mode and produce different_list in addition to
+ newer_list and older_list.
+ - May be a standalone command, or a modifier to import/export.
+ 5.1.8 present_but_ignored
+ - Report skeleton paths that exist in Harmony but are ignored by
+ <other>’s gitignore semantics.
+ 5.1.9 all
+ - Run the complete suite: environment, structure, import, export,
+ suspicious, addendum, present_but_ignored, checksum (if enabled).
+5.2 “files” is not a user facing command
+ 5.2.1 The “files” step is internal: it is the comparison over
+ skeleton_dict and <other> that builds newer_list, older_list,
+ different_list.
+ 5.2.2 import/export use its results.
+
+6. Safety guarantees
+6.1 No writes
+ 6.1.1 The program does not modify files.
+ 6.1.2 It only prints suggested commands and reports.
+6.2 Time based comparison
+ 6.2.1 Newer vs older is based on mtime. If clocks are misleading,
+ results need manual judgment.
+6.3 Git integration
+ 6.3.1 The tool assumes Harmony is under git so old versions exist even
+ after cp operations.
+6.4 Exit status
+ 6.4.1 0 on success (even if differences are found).
+ 6.4.2 Non zero on argument errors or internal failures (e.g. invalid
+ project path).
--- /dev/null
+#+TITLE: 01 - Workflow and Build Contract
+#+AUTHOR: RT
+#+OPTIONS: toc:2 num:nil
+
+* 1. Core Build Principles (The Contract)
+This contract minimizes complexity and ensures reproducibility[cite: 1033].
+
+** 1.1 Invariant: Read-Only Authored Trees
+- **Authored Trees** (=developer/authored/=) are read-only to all scripts[cite: 1052].
+- **Write Area (SCRATCHPAD):** All synthesis, intermediates, binaries, and kbuild outputs must be directed to =developer/scratchpad/=[cite: 1035, 1052].
+
+** 1.2 Orchestration
+- **Invocation:** Builds are invoked from the =$REPO_HOME/developer= directory[cite: 1038].
+- **Public Targets:** The orchestrator (=developer/tool/makefile=) exposes the main targets (~all~, ~lib_cli~, ~kmod~, ~clean~)[cite: 1041]. Build domains (like ~target_lib_cli.mk~) are independent and reusable[cite: 1036].
+
+** 1.3 Discovery
+Artifacts are discovered automatically by suffix (e.g., ~*.lib.c~, ~*.cli.c~, ~*.mod.c~)[cite: 1034, 1049].
+
+* 2. Project Roles and Workflow
+The workflow is divided into small and big loops based on distinct roles[cite: 1302].
+
+** 2.1 Roles
+- **Developer:** Translates specs into code, evolving the =authored= tree[cite: 1307].
+- **Tester:** Runs the regression suite and verifies release candidates[cite: 1308, 1309].
+- **Toolsmith:** Maintains the skeleton and shared tools[cite: 1301].
+- **Project Manager:** Confirms readiness to cut a release branch[cite: 1312].
+
+** 2.2 Release Flow (The Little Loop)
+=$REPO_HOME/release= holds *current candidates under test*[cite: 1306]. Developers implement features and promote candidates for testers to exercise[cite: 1307, 1308].
+
+** 2.3 The Big Loop (Release Branch)
+When candidates are functional, a **release branch** (=release_v<n>=) is cut from the =core_developer_branch=[cite: 1312]. Core development continues on the moving head[cite: 1324].
+
+* 3. Release Promotion and Targets
+Promotion is an **explicit copy step** (via the Python release script)[cite: 1076].
+
+** 3.1 Source Targets (The Old Convention Update)
+- Source files previously read from =developer/cc/=[cite: 1039, 1058].
+- **NEW SOURCE:** The build system now sources files from **=developer/authored/=**.
+
+** 3.2 Output Targets (The New Convention)
+The release script must now reconcile the developer's output with the shared repository structure:
+
+| Content Type | Developer Origin | Release Target | Invariant |
+| :--- | :--- | :--- | :--- |
+| **Binaries/Kmod** | scratchpad/loadable | **release/local_build/** | Architecture-Specific, IGNORED |
+| **Agnostic Scripts** | developer/loadable | **release/loadable/** | Shared, TRACKED |
--- /dev/null
+#+TITLE: RT Code Format Guide
+#+AUTHOR: Thomas Walker Lynch
+#+DATE: 2025-02-28
+#+OPTIONS: toc:nil
+
+# perhaps add rules about main functions being merely wrappers that pack arguments, call the reall business function, and then unpack results from the business function perhaps to print, and to set the main return value.
+
+* Introduction
+
+The RT Code Format is intended to apply across languages, and thus the rules are agnostic to the language being code. The RT Code format produces a dense output so as to make room
+for longer identifier names and to put more code on that tiny screen of your laptop so you can work in a cafe. The rules focus on indentation, naming conventions, enclosure spacing, and unique handling of commas.
+
+* RT Formatting Should Be Applied After Any Other Formatting
+
+Many formatting tools apply automatic spacing and alignment adjustments before finalizing code. One common example is Preemptive Enclosure Adjustment (PEA), where spaces are added or removed inside enclosures automatically. This can cause conflicts with RT Formatting rules.
+
+RT Formatting should be applied as a **final step** to resolve such conflicts:
+- RT rules **override** PEA rules where they differ.
+- Where there is no conflict, existing formatting remains unchanged.
+- This ensures consistency when AI-generated code is reformatted.
+
+Common formatting conflicts:
+- **Indentation:** PEA favors 4-character indentation, whereas RT Formatting enforces 2-character indentation.
+ This allows for more liberal indentation use and keeps statements compact.
+- **Comma Placement:** RT Formatting treats the comma as a **syntactic append operator**.
+- **Parentheses, Brackets, and Braces:** AI should follow the **exception detection procedure** for enclosure spacing.
+- **Operator Formatting:** Certain operators require **specific spacing rules**.
+- **Short Statements:** `if`, `while`, and similar constructs follow the **Short Stuff Rule** for single-line clauses.
+
+* Naming Conventions
+
+1. **Namespaces and types** use *PascalCase*.
+2. **Functions and variables** use *snake_case*.
+3. **Ordered collections** use `_list` as a suffix (e.g., `node_list`), even if the language does not have a `List` type.
+
+Examples:
+#+BEGIN_SRC c
+mouse_count
+test_LabelList_0 // Function testing LabelList (a class/type)
+Thomas_Walker_Lynch
+#+END_SRC
+
+* Binary Operators
+
+ There is no space around multiply and divide binary operators.
+
+ There is one space around all other operators.
+
+* Assignment
+
+ Two types of assignment:
+
+ 1. sampling assignment, `=` inside `if`, `while`, etc.
+ 2. single statement assignment
+
+ No space around sampling assignment `=`.
+
+Example:
+#+BEGIN_SRC c
+if( result=some_condition() ){ // Sampling assignment, no spaces
+ process(result);
+}
+a = b + c; // Regular assignment with spaces
+#+END_SRC
+
+* No space before Newline
+
+There is never space before an unquoted newline.
+
+* Enclosure
+
+Enclosed text is found after an opening enclosure punctuation symbol,
+and before the matching closing punctuation symbol.
+
+- `(...)` (parentheses)
+- `{...}` (braces)
+- `[...]` (square brackets)
+- `<...>` (angle brackets)
+
+It is common to find enclosures as part of language statements. For example:
+#+BEGIN_SRC c
+if(i<10)
+#+END_SRC
+Here the enclosed text is `i<10`.
+
+As another example:
+#+BEGIN_SRC c
+while(true)
+#+END_SRC
+Here the enclosured text is `true`.
+
+Enclosures are also found in expressions. For example:
+#+BEGIN_SRC c
+ 3*(2 + 4)
+#+END_SRC
+Here the enclosed text is `2 + 4`.
+
+There can be multiple enclosures in a given statement, depending on the language, or in a given expression. For example:
+#+BEGIN_SRC c
+ (1 +3)*(2 + 4)
+#+END_SRC
+Here there are two enclosures `(1 + 3)` and `(2 + 4)`. The first enclosure encloses the text `1 + 3` while the second encloses `(2 + 4)`.
+
+In RT formatting, there is no native space before or after the enclosure punctuation. There can be space due to other rules, such as the space around the plus operator. For example:
+#+BEGIN_SRC c
+ (1*3) + (2*4)
+#+END_SRC
+Here the space around the enclosure punctuation belongs to the operator, rather than to the enclosure punctuation.
+
+Enclosed text can hold further enclosed text. This is 'nesting' of enclosures.
+
+Because enclosure nesting can run deep, we have allowed for one exception to the no space enclosure punctuation rule. Follow these steps:
+
+** Line-by-Line Formatting
+
+Enclosure formatting is applied **per line**, without scanning beyond that line.
+
+- **Virtual Closure Rule:**
+ At the **end of a line**, any still-open enclosure punctuation is treated as **closed** for formatting purposes.
+
+- **Virtual Opening Rule:**
+ At the **start of a new line**, any **orphaned closing punctuation** found there is treated as **belonging to the current line**.
+
+
+** Procedure for Identifying Enclosure Exceptions
+
+1. The language is not Lisp.
+2. The enclosure meets **all** of the following conditions:
+ - It opens and closes on a **single line**.
+ - It contains at least **one nested enclosure** inside.
+ - It is not found in the enclosed text of other enclosure on that line.
+3. If these conditions hold, **apply the exception**:
+ - Insert **one space** after the opening enclosure punctuation.
+ - Insert **one space** before the closing enclosure punctuation.
+
+**Example of a qualifying enclosure:**
+#+BEGIN_SRC c
+if( (x == 3 || y < 5) && z ){
+ process_data();
+}
+#+END_SRC
+
+Here, `( (x == 3 || y < 5) && z )` qualifies for spacing adjustment.
+
+**Example of a non-qualifying enclosure:**
+#+BEGIN_SRC c
+if(y < 5){
+ process_data();
+}
+#+END_SRC
+
+Since no enclosure on this line meets the conditions, **no additional spaces** are added.
+
+** Adjacency
+When two enclosures appear side by side (like `)(` or `}{`), there is *no space* between them.
+
+* Commas
+
+The **comma rule** is one of the most distinctive and recognizable aspects of RT Code Formatting.
+
+1. **One space before the comma** (e.g., `a ,b`).
+2. **No space after the comma** (e.g., `a ,b`).
+3. **Line break before the comma when breaking lines**, but **no line break after the comma**.
+
+Examples:
+#+BEGIN_SRC c
+a
+,b
+#+END_SRC
+
+When function arguments get too long, break lines as follows:
+#+BEGIN_SRC c
+result = some_function(
+ first_argument
+ ,second_argument_with_longer_name
+ ,third_argument
+);
+#+END_SRC
+
+✔ **This ensures consistency and maintains readability.**
+
+* Short Stuff Rule
+
+For **`if`**, **`for`**, and **`while`** statements that introduce a *single-line* clause with no `else`, if the **condition and clause together fit within one line, they should **remain on a single line without braces**. Say when about ≤40 characters, though this is not strictly ≤40 characters — it depends on complexity and formatting. If the condition and action are simple, or perhaps fit a parallel construct with other short stuff, they should stay inline.
+
+
+
+
+
+Example:
+#+BEGIN_SRC c
+if( x > 0 ) return x;
+while( has_next() ) process_next();
+#+END_SRC
+
+
--- /dev/null
+<!DOCTYPE html>
+<html lang="en">
+<head>
+ <meta charset="UTF-8">
+ <meta name="viewport" content="width=device-width, initial-scale=1.0">
+ <link href="https://fonts.googleapis.com/css2?family=Noto+Sans+JP&display=swap" rel="stylesheet">
+ <title>RT C coding conventions</title>
+ <style>
+ body {
+ font-family: 'Noto Sans JP', Arial, sans-serif;
+ background-color: hsl(0, 0%, 0%);
+ color: hsl(42, 100%, 80%);
+ padding: 2rem;
+ }
+ .page {
+ padding: 3rem;
+ margin: 1.25rem auto;
+ max-width: 46.875rem;
+ background-color: hsl(0, 0%, 0%);
+ box-shadow: 0 0 0.625rem hsl(42, 100%, 50%);
+ }
+ h1 {
+ font-size: 1.5rem;
+ text-align: center;
+ color: hsl(42, 100%, 84%);
+ text-transform: uppercase;
+ margin-top: 1.5rem;
+ }
+ h2 {
+ font-size: 1.25rem;
+ color: hsl(42, 100%, 84%);
+ text-align: center;
+ margin-top: 2rem;
+ }
+ h3 {
+ font-size: 1.125rem;
+ color: hsl(42, 100%, 75%);
+ margin-top: 1.5rem;
+ }
+ p, li {
+ color: hsl(42, 100%, 90%);
+ text-align: justify;
+ margin-bottom: 1rem;
+ }
+ code {
+ font-family: 'Courier New', Courier, monospace;
+ background-color: hsl(0, 0%, 25%);
+ padding: 0.125rem 0.25rem;
+ color: hsl(42, 100%, 90%);
+ }
+ </style>
+</head>
+
+<body>
+<div class="page">
+ <header>
+ <h1>Reasoning Technology (RT) C file control structure</h1>
+ <p>© 2024 Thomas Walker Lynch - All Rights Reserved.</p>
+ </header>
+
+ <h2>Introduction</h2>
+
+ <p>This document summarizes some of the coding conventions used in RT C projects. Discussed here are conventions for integrated header designs, ad hoc namespaces, and a structured approach to source file extensions. The document also outlines the associated build process using a standardized makefile.</p>
+
+ <h2>Header file integration</h2>
+
+ <p>RT C projects adopt an innovative approach by integrating headers directly into source files. This ensures consistency between interfaces and implementations, eliminating mismatches. Each file contains both an interface and an implementation section, gated by preprocessor directives.</p>
+
+ <p>Each RT C source file integrates its header directly into the source file. This locality makes header content easier to maintain as everything is found in a single file. It also eliminates the need to maintain two files for each module.</p>
+
+ <h3>Each file has two sections</h3>
+ <ul>
+ <li><strong>Interface section:</strong> Contains declarations, macros, and <code>#includes</code> needed for the interface. Ensures consistency by defining the interface exactly once, even when the file is included multiple times.</li>
+ <li><strong>Implementation section:</strong> Contains function definitions and additional includes needed for the implementation. This section is compiled only when the file is used as an implementation.</li>
+ </ul>
+
+ <p>Each section is turned on and off with the CPP macro <code>FACE</code>.</p>
+
+ <h3>Example</h3>
+ <pre><code>
+// If not an FACE, then an IMPLEMENTATION
+#ifndef FACE
+ #define MyModule·IMPLEMENTATION
+ // Ensures included files are processed for their interfaces.
+ #define FACE
+#endif
+
+// Define the interface exactly once.
+#ifndef MyModule·FACE
+#define MyModule·FACE
+ // Interface-only includes go here.
+ void MyModule·function();
+#endif
+
+#ifdef MyModule·IMPLEMENTATION
+ // Additional includes for implementation go here.
+ #include <stdio.h>
+ void MyModule·function() {
+ printf("Hello, World!\n");
+ }
+#endif
+ </code></pre>
+
+ <h3>Explanation</h3>
+ <p>The example above demonstrates the structure and purpose of each block:</p>
+ <p><strong>First block:</strong> Ensures that the file operates correctly based on the value of <code>FACE</code>. If <code>FACE</code> is undefined, it defines <code>MyModule·IMPLEMENTATION</code> to enable the implementation section and sets <code>FACE</code> to ensure subsequent includes process interface sections.</p>
+ <p><strong>Second block:</strong> Defines the interface, including declarations and interface-specific includes. The <code>#ifndef MyModule·FACE</code> macro ensures the interface is defined exactly once, regardless of how many times the file is included.</p>
+ <p><strong>Third block:</strong> Contains implementation-specific includes and function definitions. Guarded by <code>MyModule·IMPLEMENTATION</code>, it is only included when compiling the implementation.</p>
+ <p>Interface includes are placed in the interface block, ensuring they are available wherever the interface is used. Implementation includes are isolated in the implementation block, minimizing unnecessary dependencies in other files.</p>
+
+ <h2>Namespace conventions</h2>
+ <p>RT projects use ad hoc namespaces to maintain clarity and prevent naming conflicts. This is achieved by prefixing exported identifiers with a module-specific name followed by the <code>·</code> (cdot) character.</p>
+
+ <h3>Conventions</h3>
+ <ul>
+ <li><strong>Prefix:</strong> The module name serves as the prefix, ensuring all identifiers are unique across the program.</li>
+ <li><strong>Separator:</strong> The <code>·</code> character visually separates the prefix from the identifier name, maintaining readability and avoiding conflicts.</li>
+ </ul>
+
+ <h3>Example</h3>
+ <pre><code>
+void Server·run();
+ </code></pre>
+
+ <h2>Source file extensions</h2>
+ <p>RT projects use standardized extensions to distinguish between library and command-line interface (CLI) source files:</p>
+ <ul>
+ <li><strong><code>.lib.c</code>:</strong> Files implementing library functions.</li>
+ <li><strong><code>.cli.c</code>:</strong> Files implementing command-line tools.</li>
+ </ul>
+
+ <p>The <code>.lib.c</code> files compile into libraries, while <code>.cli.c</code> files compile into standalone executables. The makefile processes these files automatically, ensuring a clear separation of functionality.</p>
+
+ <h3>Build process</h3>
+ <p>The build process follows these steps:</p>
+ <ol>
+ <li><strong>Dependency generation:</strong> Run <code>make dependency</code> to create dependencies. This step is only required when the dependency structure changes.</li>
+ <li><strong>Compilation:</strong> Run <code>make cli</code> to compile CLI sources and link them against the library. The makefile automatically manages targets and dependencies.</li>
+ </ol>
+
+ <h2>Benefits</h2>
+ <ul>
+ <li><strong>Consistency:</strong> Integrated headers ensure interface and implementation are always in sync.</li>
+ <li><strong>Modularity:</strong> Each file encapsulates its interface and implementation, reducing coupling.</li>
+ <li><strong>Clarity:</strong> Ad hoc namespaces and standardized extensions improve readability and organization.</li>
+ <li><strong>Efficiency:</strong> The makefile automates builds, minimizing errors and streamlining development.</li>
+ </ul>
+
+ <h2>Conclusion</h2>
+ <p>This document outlines the conventions and practices for writing and building RT C projects. By integrating headers, adopting namespaces, and standardizing extensions, RT ensures its projects are robust, modular, and easy to maintain.</p>
+</div>
+</body>
+</html>
--- /dev/null
+#+TITLE: Reasoning Technology (RT) C file control structure
+#+AUTHOR: Thomas Walker Lynch
+#+OPTIONS: toc:2 num:nil
+#+LANGUAGE: en
+
+* Introduction
+This document summarizes coding conventions used in RT C projects: integrated header designs, ad hoc namespaces, and a structured approach to source file extensions. It also outlines the associated build process using a standardized makefile.
+
+* Header file integration
+RT C projects integrate the header directly into the source file. Each file contains both interface and implementation sections, gated by preprocessor directives. This keeps interface and implementation in sync and avoids maintaining two files.
+
+** Each file has two sections
+- *Interface section*: declarations, macros, and =#include= needed for the interface. Defined exactly once even with multiple inclusion.
+- *Implementation section*: function definitions and any additional includes needed for the implementation. Only compiled when used as an implementation.
+
+Each section is toggled by the CPP macro =FACE=.
+
+** Example
+#+BEGIN_SRC c
+// If not an FACE, then an IMPLEMENTATION
+#ifndef FACE
+ #define MyModule·IMPLEMENTATION
+ // Ensures included files are processed for their interfaces.
+ #define FACE
+#endif
+
+// Define the interface exactly once.
+#ifndef MyModule·FACE
+#define MyModule·FACE
+ // Interface-only includes go here.
+ void MyModule·function();
+#endif
+
+#ifdef MyModule·IMPLEMENTATION
+ // Additional includes for implementation go here.
+ #include <stdio.h>
+ void MyModule·function() {
+ printf("Hello, World!\n");
+ }
+#endif
+#+END_SRC
+
+** Explanation
+- *First block*: If =FACE= is undefined, define =MyModule·IMPLEMENTATION= and set =FACE= so subsequent includes expose interfaces.
+- *Second block*: Define the interface exactly once via =#ifndef MyModule·FACE=.
+- *Third block*: Implementation-only includes and definitions guarded by =MyModule·IMPLEMENTATION=.
+
+* Namespace conventions
+RT projects use ad hoc namespaces: exported identifiers are prefixed with a module name and the =·= (cdot) separator for clarity and to avoid collisions.
+
+** Conventions
+- *Prefix*: module name.
+- *Separator*: =·= visually separates prefix from identifier.
+
+** Example
+#+BEGIN_SRC c
+void Server·run();
+#+END_SRC
+
+* Source file extensions
+Standardized extensions distinguish library from CLI sources:
+- =.lib.c= :: library implementations
+- =.cli.c= :: command-line tools
+
+=.lib.c= compiles into libraries; =.cli.c= into executables. The makefile auto-detects and builds accordingly.
+
+** Build process
+1. *Dependency generation*: =make dependency= (only when dependency graph changes).
+2. *Compilation*: =make cli= builds CLI targets and links with the library.
+
+* Benefits
+- *Consistency*: integrated headers keep interfaces and implementations aligned.
+- *Modularity*: each file encapsulates interface + implementation.
+- *Clarity*: namespaces + extensions improve readability.
+- *Efficiency*: standardized makefile reduces build friction.
+
+* Conclusion
+Following these conventions yields robust, modular C projects with predictable builds.
--- /dev/null
+
+Bash is inconsistent about returning the name of the running script in
+all scenarios (sourced, executed directly, from with in a function called
+by another function).
+
+1.
+
+BASH_SOURCE[0] was used because $0 did not work with sourced scripts (a
+fact that is leveraged for detecting when in a sourced script).
+
+2.
+
+However, this did not work in all scenarios:
+
+ read -r -d '' script_afp_string <<'EOF'
+ realpath "${BASH_SOURCE[0]}" 2>/dev/null
+ EOF
+
+ script_afp(){
+ eval "$script_afp_string"
+ }
+
+ export script_afp_string
+ export -f script_afp
+
+When `script_afp` was exported, used in another file, and used within a function
+in that other file, it reported `environment` for the script name at
+BASH_SOURCE[0]. In various call scenarios the actual script name appears at
+BASH_SOURCE[1] or even at BASH_SOURCE[2].
+
+3.
+
+As a stable alternative to having a script_afp function, place this line
+at the top of scripts that use the `script_XX` functions, or at the top
+of all scripts:
+
+ script_afp=realpath "${BASH_SOURCE[0]}"
+
+Then use $script_afp as a string within other functions. It will have stable
+value no matter the call structure.
--- /dev/null
+<!DOCTYPE html>
+<html lang="en">
+<head>
+ <meta charset="UTF-8">
+ <meta name="viewport" content="width=device-width, initial-scale=1.0">
+ <link href="https://fonts.googleapis.com/css2?family=Noto+Sans+JP&display=swap" rel="stylesheet">
+
+ <title>Directory Structure Description</title>
+<style>
+ html {
+ font-size: 16px; /* This will be the base for rem units */
+ }
+
+ body {
+ font-family: 'Noto Sans JP', Arial, sans-serif;
+ background-color: hsl(0, 0%, 0%);
+ color: hsl(42, 100%, 80%);
+ padding: 2rem;
+ margin: 0;
+ }
+
+ .page {
+ padding: 1.25rem; /* 20px */
+ margin: 1.25rem auto; /* 20px */
+ max-width: 46.875rem; /* 750px */
+ background-color: hsl(0, 0%, 0%);
+ box-shadow: 0 0 0.625rem hsl(42, 100%, 50%); /* 10px */
+ }
+
+ ul, li {
+ font-size: 1rem; /* Keeping default font size */
+ list-style-type: none;
+ }
+
+ li::before {
+ content: "📁 ";
+ margin-right: 0.3125rem; /* 5px */
+ }
+
+ li {
+ margin-bottom: 0.3125rem; /* 5px */
+ }
+
+ .description {
+ margin-left: 0.625rem; /* 10px */
+ color: hsl(42, 100%, 75%);
+ }
+
+ code {
+ font-family: 'Courier New', Courier, monospace;
+ background-color: hsl(0, 0%, 25%);
+ color: hsl(42, 100%, 90%);
+ padding: 0.125rem 0.25rem; /* 2px 4px */
+ border-radius: 0.1875rem; /* 3px */
+ font-size: 90%;
+ }
+
+ h1 {
+ text-align: center;
+ color: hsl(42, 100%, 84%);
+ text-transform: uppercase;
+ margin-bottom: 1.25rem; /* 20px */
+ }
+
+ h2 {
+ color: hsl(42, 100%, 84%);
+ text-transform: uppercase;
+ margin-top: 2.5rem; /* 40px */
+ }
+
+ p {
+ color: hsl(42, 100%, 90%);
+ margin-bottom: 1.25rem; /* 20px */
+ text-align: justify;
+ }
+</style>
+
+</head>
+<body>
+
+ <div class="page">
+ <h1>Directory Naming</h1>
+
+ <h2>Reference</h2>
+
+ <ul>
+ <li>Harmony/<span class="description">aka REPO_HOME, top level owned by the project administrator.</span></li>
+ <ul>
+ <li>developer/ <span class="description">Workspace for the developer. Has the source code, build scripts, and development-specific tools.</span></li>
+ <ul>
+ <li>deprecated/ <span class="description">Files and older versions being viewed, perhaps part of a refactoring effort.</span></li>
+ <li>document/ <span class="description">Documentation on developing and building the project.</span></li>
+ <li>javac/ <span class="description">Java source files for compilation.</span></li>
+ <li>jvm/ <span class="description">Compiled Java bytecode files for the project, typically a jar for a Java project.</span></li>
+ <li>scratchpad/ <span class="description">Temporary storage typically for intermediate files created during build.</span></li>
+ <li>shell/ <span class="description">Shell scripts intended to be part of the project release. (These are not tools.)</span></li>
+ <li>tool/ <span class="description">Tools created by the developer, used for development tasks.</span></li>
+ </ul>
+ <li>document/ <span class="description">General documentation about the project.</span></li>
+ <li>release/ <span class="description">Release candidate for testing. Becomes the release on the release branch.</span></li>
+ <li>scratchpad/ <span class="description">Temporary storage for project administration tasks.</span></li>
+ <li>tester/ <span class="description">Workspace for the tester. Has the test bench, tests, and test scripts.</span></li>
+ <ul>
+ <li>document/ <span class="description">Test-specific documentation.</span></li>
+ <li>javac/ <span class="description">The tests of the test bench sources.</span></li>
+ <li>tool/ <span class="description">Tools needed for testing and managing the test environment.</span></li>
+ </ul>
+ <li>tool/ <span class="description">Project administration specific tools.</span></li>
+ <li>tool_shared/ <span class="description">Tools shared across project roles.</span></li>
+ <ul>
+ <li>bespoke/ <span class="description">Shared tools developed within this project.</span></li>
+ <li>customized/ <span class="description">Modified versions of third-party tools adapted for the project.</span></li>
+ <li>document/ <span class="description">Documentation related to shared tools and setup.</span></li>
+ <li>third_party/ <span class="description">Shared tools sourced from third-party vendors or open-source projects. These have their own independent licenses,</span></li>
+ </ul>
+ <li>LICENSE.txt <span class="description">The project license detailing usage and distribution terms.</span></li>
+ <li>README.md <span class="description">A general overview and introduction to the project.</span></li>
+ </ul>
+ </ul>
+
+ <h2>Name origin and rationale</h2>
+
+ <p>Developers and project administrators typically do not employ a semantic system for
+ naming directories, but more commonly use conventional placeholder
+ names. The intended purpose of files in a directory with a placeholder
+ name then must be inferred from experience or inspection of the files, or
+ learned from documents or other people.</p>
+
+ <p>For example, a directory named <code>exe/</code> probably derives its name from the
+ fact that the contained files have their executable permission bit set;
+ however, such a directory will not contain all such files. There might
+ even be some files in an <code>exe/</code> directory that do not have their
+ executable permission bit set. The two concepts being an <code>exe/</code> file
+ (i.e. being a file in an <code>exe/</code> directory) and being an executable file
+ are not identical. The actual intended meaning of being an <code>exe/</code> file
+ will sometimes be that the contained files are applications available to a
+ user, or that they are tools available for use in a project.
+ </p>
+
+ <p>The directory names in this project resulted from an exploration of a
+ property-based file system. In such a system a number of files and
+ agents are defined. Then we can ask questions about their relationships.
+ Files with a relationship to the developer are collected, and this
+ becomes the <code>developer/</code> directory. In a similar manner we get the
+ directories, <code>tester/</code>, and <code>javac/</code>. In this latter case the
+ agent is a compiler rather than a role.
+ </p>
+
+ <p>When attempting to apply the <code>is-for</code> property in practice it
+ became apparent that using this sole property was insufficient. Consider
+ the directories <code>deprecated/</code> and <code>scratchpad/</code>. There is no
+ <em>Mr. Deprecated</em> or <em>Mr. Scratchpad</em> who the contained
+ files are for. (And this conclusion is not for the lack of trying. Even
+ mythological beings did not suffice as agents.) Rather than being for an
+ agent, the files collected in such a directory have in common a state of
+ being that was imposed upon them by decree. Perhaps the developer, has
+ decreed that a file is now deprecated, or a build script has decreed that
+ it is a scratchpad file. Such decrees are typically more dynamic than the
+ relationship properties. Also, these properties are disconnected from the
+ contents of the file. When, for example, a file has the property of being
+ for the java compiler, we gain some information about its contents. In the
+ universe of possible messages sent through a file, such a file will
+ contain text that is proposed to be java syntax conforming. In contrast,
+ when we learn that a file is <code>deprecated/</code> we gain no
+ information about the contents of the file, because any file can
+ be <code>deprecated</code>, independent of its contents.
+ </p>
+
+ <p>To understand a directory name within this system, one can imagine
+ reading said name as part of a sentence that integrates the
+ property. Consider two property names: <code>is-a</code>
+ and <code>is-for</code>. For example, "Each file in
+ the <code>document/</code> directory <code>is-a</code> document," or "Each
+ file in the <code>developer/</code> directory <code>is-for</code> the
+ developer." Although the property name is not carried over from the
+ property based file system to the conventional file system, we can
+ typically infer what it must have been. (It is beyond the scope of
+ discussion here, but in actuality, property based file system collections
+ are defined by predicates. Each predicate is given a file's properties and
+ relationships as arguments, then resolves to true if and only if the file
+ belongs to the collection. Now wouldn't that be interesting if we instead
+ derived a probability?)
+ </p>
+
+ <p>It is uncommon for a property value to be plural. While it is not
+ disallowed, it rarely occurs in practice. This is true independent of
+ whether we are discussing a relationship property or a state
+ property. Hence when we make a file collection based on a shared property,
+ then carry that over as a directory name in a conventional file system,
+ the resulting directory name will often be singular. This pattern can be
+ observed in the case of the <code>document/</code> directory, as shown in
+ the prior paragraph.
+ </p>
+
+ </div>
+
+</body>
+</html>
--- /dev/null
+# Empty Directory Sentinels
+
+- We use `.githolder` to keep potentially empty dirs in Git.
+- `.githolder` is marked `export-ignore` in `.gitattributes` so it won’t appear in release archives.
--- /dev/null
+
+The project is originally configured to be used with Emacs as an IDE. The tools
+can all be run from a shell inside of emacs. Even when using an IDE what the
+shell environment scripts and tools do should be understood.
+
+I have added a working IntelliJ IDEA configuration, so if you want a modern IDE
+it is probably best to go with this. See ItelliJ_IDEA.txt in this directory.
+
+I've not run Eclipse on the project, if you do, perhaps you can update the notes
+here. These things will probably increase your odds of making it work:
+ 1. open a shell
+ 2. cd to Ariadne, and source the env_developer
+ 3. run the tool 'distribute_source'
+ 3. run eclipse from the command line
+ 4. give eclipse the 'scratchpad' directory as its source
+
+Be sure to run `release` after development to update what the tester sees.
+
+Do the analogous steps if you contribute as a 'tester'. I.e. from
+the shell source env_tester instead. Also, you will need to add
+distribute_source to tester/tool, as it is currently not there.
+
--- /dev/null
+
+System requirements:
+
+dnf install libX11-devel libXpm-devel libjpeg-devel libpng-devel libtiff-devel
+dnf install gtk3-devel giflib-devel gnutls-devel
+dnf install ncurses-devel texinfo
+dnf install libacl-devel libattr-devel libgccjit libgccjit-devel
+
+# install and build script:
+
+cd "$REPO_HOME"/tool_shared/third_party
+mkdir -p emacs/{src,build,bin}
+
+# We sought stability, and now this. What can I say? It has 'visual-wrap-prefix-mode'.
+pushd upstream
+curl -L -O https://alpha.gnu.org/gnu/emacs/pretest/emacs-30.0.92.tar.xz
+popd
+
+tar -xf upstream/emacs-30.0.92.tar.xz -C emacs/src --strip-components=1
+
+# need to clear the environment
+env -i bash
+
+pushd emacs/src
+./configure --prefix="$REPO_HOME"/tool_shared/third_party/emacs
+
+ I gather this warning is unavaoidable?
+ "configure: WARNING: Your version of Gtk+ will have problems with"
+
+
+# replace nproc with number of processors:
+make -j$(nproc)
+
+# make install installs locally due to the `--prefix` option `./configure` above
+make install
+make clean
+
+popd
+rm -r emacs/{src,build}
+
+# Find emacs in the emacs/in directory. Be sure to add it to the path
+# in the tool_shared/bespoke/env file:
+# PATH="$REPO_HOME/tool_shared/third_party/emacs/bin:$PATH"
+
+
--- /dev/null
+
+This file describes the local install and configuration of IntelliJ_IDEA for
+the project with the RT project skeleton.
+
+Project development has been done with ItelliJ and with Emacs. Perhaps
+someone will add more about Eclipse to the install_Eclipse.txt page.
+
+--------------------------------------------------------------------------------
+Some notes
+
+'project directory' - the directory with the .git file in it. Called
+$REPO_HOME in RT scripts. Called $PROJECT_DIR$ in IntelliJ file paths.
+
+'module directory' - for RT projects examples include
+`~/Ariadne/developer' `~/Ariadne/tester`. These are independent build
+environments.
+
+IntelliJ automatic scanning:
+
+ When selecting `new project` or `new module` the fist time IntelliJ will
+ go off and scan directories.
+
+ My advice, ** uncheck anything it scans ** then hit next. If you
+ don't hit next, the `new project` or `new module won't be made.
+
+IntelliJ paths on forms:
+
+ I tried using $PROJECT_DIR$ as a variable standing for the project
+ directory, as this was suggested by an AI. However IntelliJ simply
+ made a directory with the literal variable name. Recommendation:
+ don't use it.
+
+ Also tried using $REPO_HOME, as that was defined in the environment
+ IntelliJ was run from. Nope, the environment that idea was invoked
+ from seems to be thrown away.
+
+ `~` for the home directories does work. There is one blessing.
+
+ When a file or directory path has a blank on a form, there will be a
+ file navigator icon at the far right in the blank. It does not show
+ when the form is not scrolled all the way to the right. The browser
+ tool starts from either `/home` or at `/` (the root of the file
+ sytem) rather than at the top of the project.
+ It inserts absolute path names.
+
+ It seems everything is based on absolute paths, so it will be
+ interesting to see what happens when people download a repo
+ with `.imp` files in it ...
+
+A GUI bug:
+
+ There is a Gnome Linux bug where the drop down menu can stay on top no matter
+ what other window, application, or what virtual desktop a person is on. You
+ must go back to the IDEA application window and hit <escape> to make it go
+ away.
+
+The [OK] button at the bottom of dialogs:
+
+ This closes the dialog.
+
+ To apply changes hit [Apply].
+
+ [OK] will not save what is on the dialog if [Apply] would fail, but
+ it still closes it.
+
+--------------------------------------------------------------------------------
+To install ItelliJ
+
+ Download the tar file from
+ `https://www.jetbrains.com/idea/download/?section=linux`
+ into the
+ `$REPO_HOME/tool_shared/third_party/upstream`
+ directory.
+
+ Expand it into
+ `$REPO_HOME/tool_shared/third_party`
+
+ cd into the expanded directory, into `bin`, then `chmod u+x` and run `idea_inst`.
+
+ set the env path to include
+ `$REPO_HOME/tool_shared/third_party/idea-IC*/bin`
+
+ The executable is called `idea`.
+
+ Consider setting a desktop short cut. Consider instead installing it in your
+ own bin directory. Easily done, just move the directory created by the tar
+ file expansion there.
+
+ I prefer a user mode install, as there is no reason this tool should need
+ admin privileges.
+
+--------------------------------------------------------------------------------
+Startup
+
+ ./tool_shared/third_party/idea-IC-243.21565.193/bin/idea &
+
+ Shows: Welcome screen
+ select "Open" as Ariadne already exists
+
+ Shows: Open File or Project Browser
+ In top dialog box put full path to project directory.
+
+ Hit [OK] at the bottom. Unlikely, but might be scrolled off the bottom of the screen.
+
+ Shows: main window
+ Appears after hitting OK from the "Open File or Project" [ok].
+
+ Has a tool bar at the top. There is a double meat hamburger menu icon
+ at the left. Hitting this will replace the top bar with a vertical
+ menu for drop down menus.
+
+ Careful, after the hamburger icon is pressed, the first drop down
+ menu instantly appears. Slide over to get the other drop downs.
+ Don't click, slide!
+
+ Under tool bar:
+ Far left is an icon bar. Then a file browser. And then a big box
+ describing hot keys.
+
+--------------------------------------------------------------------------------
+Configuration
+
+If you cloned the Ariadne project, the modules will already be configured, and
+also probably some of the run configuration will already be configured.
+
+If you add a project, or modules, know that is possible to go back and
+change settings, except perhaps for the Project directory, I've not tried
+that yet.
+
+It will on occasion add directories. I have multiple language setup with
+source in javac. Though the directory 'src' is not in the configuration,
+IntelliJ like to create it then refuse to delete it, so after configuring I
+then go back and delete it with `rmdir`. Sometimes it shows in the file
+browser though it is not there.
+
+ -------------
+ Setup Project
+ Hamburger icon > File dop-down > Project Structure > Project
+
+ select project SDK from disk:
+ ~/Ariadne/tool_shared/third_party/jdk-11
+
+ -------------
+ Setup Modules
+
+ Hamburger icon > File dop-down > Project Structure > Modules
+
+ Shows: "Project Structure" dialog
+
+ Hit the '+' option that shows at the top of the second panel. There is
+ no description of what it does. Mouse over just says 'add'. It is
+ there with a couple of other icons. After modules are added they will
+ be listed in this panel.
+
+ New Module.
+
+ Dialog pop-up
+
+ Name: developer
+
+ Location: This will be the project directory. As examples,
+ ~/Ariadne or ~/Harmony.
+
+ Dependencies, there will then be a drop down.
+
+ Sometimes is suggests the "Project SDK" at the top. If so select that.
+
+ Sometimes it allows select from disk, is so enter ~/<project>/tool_shared/third_party/.
+
+ Other times it shows a discovered directory that is the same as
+ the one I suggest browsing to.
+
+ Careful, the module won't be made until hitting [Create] at the bottom.
+
+ As far as I can tell you can't get this panel again, rather delete and add
+ a new module if you need to change the entries.
+
+ Shows: "Project Structure" dialog, again, now the third panel with
+ information about the developer module. Third panel shows three
+ choices: [Source] [Paths] [Dependencies]
+
+ [Sources] comming up with the source dialog is the default, but that does
+ not mean the [Sources] button has been pushed.
+
+ With Sources there are two panels.
+
+ In second panel, on right side, the module root should show at the top.
+ Under if it lists any sources, use the button at the far right of the
+ listing to x it out anything that IntelliJ has automatically added.
+
+ The first panel now shows a file browser for the module.
+
+ Select the `javac` directory with a single click. Then, and only
+ after, look immediately the directory lists and click on [Sources]
+
+ When the [Source] button on the sources dialog has been
+ pushed it will turn colors and gain a border when pushed. The
+ [Sources] button must be pushed, or selected source
+ directories will not be applied. Selecting a directory and
+ hitting [OK] will not save anything, and will close the
+ dialog.
+
+ "Source Folders" will now appear in the second panel. The
+ javac folder will be listed. Hhit: [apply] at the
+ bottom. [apply] will then turn colors to show that there is
+ nothing more to apply.
+
+
+ Slide over to [Paths]
+ Copmiler Output
+ select [Use Module Compile Output Path]
+ Output Path: $PROJECT_DIR$/developer/scratchpad
+ Test Path: $PROJECT_DIR$/developer/test
+
+ leave the exclude output checkbox, that means to exclude from repo
+ and from indexing for search
+
+ hit: [apply] at the bottom
+
+ Add the `log` directory to [Resources], if you have one.
+
+ After setting 'scratchpad' as the output directory on the [paths]
+ configuration form, and leaving `scratchpad` as excluded via
+ the checkbox. You can not then on the Sources form add
+ `scratchpad` to the 'Excluded' list. Though it is excluded, it
+ does not show there.
+
+ After hitting [OK] the dialog disappears. Go back and check that everything
+ you set is there. It seems common that for some reason, perhaps the order
+ of hitting buttons, that settings are not there when going back.
+
+--------------------------------------------------------------------------------
+Integrating programs from the project
+
+ -------------
+ Local tests and tools.
+
+ This section is for adding an external tool, for example `tester/tool/make`, which
+ builds Harmony tests.
+
+ Hamburger> Run > edit configurations
+ Shows Run/Debug configurations dialog
+ Upper left hit '+'
+ Shows drop down
+ choose [Shell Script] second from bottom
+ Shows dialog, for example:
+ Name: tester-developer make
+
+ Script Path: ~/Ariadne/env_run (better to chose with the
+ file browser tool)
+
+ Script Options: tester make
+
+ Working Directory: ~/Ariadne (location of the env source scripts
+ that env_run uses)
+
+ Environment variabls: (none, env_run will source env_tester)
+
+ Interpreter: /bin/bash (left to default)
+
+ For debugging to work for the tests, they need to be run with
+ java listening:
+
+ java -agentlib:jdwp=transport=dt_socket,server=y,suspend=y,address=*:5005 $file
+
+ I've included this in the bash wrappers made by make.
+
+ -------------
+ To add an "Application"
+
+ Humburger > Run > edit configurations
+ Shows Run/Debug configurations dialog
+ Upper left hit '+'
+ Shows drop down
+ chose [Application] first choice
+ Shows dialog, for example:
+ Name: Test_Graph_0
+
+ next line are two boxes, they are not labeled, the defaults show:
+ [ module not specified ] [ -cp no module ]
+ I selected::
+ [ java 11 SDk of 'tester' module] [ -cp tester ]
+ This can be confusing, as the modules are 'tester' and 'developer', but
+ here it asks for an SDK! Then the next box says it wants a class path,
+ but it wants a module name!
+
+ next line one box, not labeled
+ [ main class [] ]
+ Note icon at right, it will give a list of class names, here in the tester module,
+ that have main calls, select one.
+
+ next line, again not labeled
+ [ Program Arguments ]
+ Test_Graph_0 has no arguments so I left it blank.
+
+ Working Directory: ~/Ariadne
+
+ Environment Variables:
+ Left blank because the executable itself does not make use of any. I do
+ know at this point if variables set in the environment IDEA ran in are
+ inherited.
+
+ 'Modify Options' with a drop down menu. (At the top right of the configuration dialog)
+ Scan down for the `Java` section.
+ Check: 'Do not build before run'
+ (To build this example, go to the Run menu and run `tester
+ make'. Or run make directly from a console prompt. Be sure to
+ source env_tester first.)
+
+
--- /dev/null
+----------------------------------------
+jdk-23
+
+ cd "$REPO_HOME/tool_shared/third_party/upstream"
+
+ # source for the 11 version used before, now upgraded to 23
+ #curl -C - -o OpenJDK11U-jdk_x64_linux_hotspot_11.0.16_8.tar.gz https://github.com/adoptium/temurin11-binaries/releases/download/jdk-11.0.16+8/OpenJDK11U-jdk_x64_linux_hotspot_11.0.16_8.tar.gz
+ curl -L -C - -b "oraclelicense=accept-securebackup-cookie" -O https://download.oracle.com/java/23/latest/jdk-23_linux-x64_bin.tar.gz
+
+ cd ..
+ tar -xzf upstream/jdk-23_linux-x64_bin.tar.gz
+
+ edit $REPO_HOME/tool_shared/bespoke/env, and update JAVA_HOME:
+ export JAVA_HOME="$REPO_HOME/tool_shared/third_party/jdk-23.0.1"
+
--- /dev/null
+# Python Environment (RT Policy)
+
+- We do **not** commit virtual environments.
+- Create the venv at `tool_shared/third_party/python/` (called 'python' rather than 'venv'), and set a path to it
+either in the env_<role> scripts (such as env_developer), or in the bespoke/env script if it is shared by all.
+
+
+
+
--- /dev/null
+# This is a document, not a script
+# There are more docs on IDEs, directory structure, etc.
+# Note especially the workflow document.
+
+#1. In a login shell
+
+ # enter the project environment as a developer
+ > cd Rabbit
+ > . env_developer
+
+ # run your IDE
+ > emacs
+
+# 2. inside of an emacs shell, or IDE build scrit
+
+ # do you edits
+ # run local test experiments
+
+ > make all
+ > make release
+
+
+ # 3. In env_tester run more thorough test suite. When satisfied make a release branch and tag it.
+ # Release branches have consecutive major release numbers.
+
+
--- /dev/null
+# Suffix Conventions
+
+## Specify interface used with variable when clarification is useful
+
+- `_set`: Indicates that the variable holds a set of items.
+
+- `_list`: Used for variables that represent a list of items.
+
+- `_f`: Refers to a function.
+
+Instead of making a variable name plural, add the interface qualifier.
+
+ e.g. names -> name_set or name_lisst
+
+## Always a good idea to use these when working with files
+
+- `_fp`: Refers to a file path. The part after the last slash is a file name.
+
+- `_afp`: Refers to an absolute file path.
+
+- `_dp`: Refers to a directory path. By convention, the value ends in a slash.
+
+- `_adp`: Refers to an absolute directory path.
+
+- `_fn`: Refers to a file name. Value has no slashes.
+
+- `_dn`: Refers to a directory name. Value has no slashes.
+
+- `_fn_base`: The file name without the last dot and subsequent characters.
+
+- `_fn_ext`: The subsequent characters after the last dot in a file name.
+++ /dev/null
-#!/usr/bin/env bash
-# template for script for creating a new project based on the Harmony skeleton
-set -x
-
-# Edit and set these variables
-#
- # 1. URL or path of Harmony skeleton
- harmony_repo_url="<REPLACE_WITH_HARMONY_REPO_URL>"
-
- # 2. project name
- project_dname="<REPLACE_WITH_YOUR_NEW_PROJECT_NAME>"
-
- initial_commit_message="Initial commit derived from the Harmony skeleton"
-
-# Creates the project
-#
- git clone "$harmony_repo_url" "$project_dname"
- if [ $? -ne 0 ]; then
- echo "ERROR: Cloning failed. Check harmony_repo_url."
- exit 1
- fi
- cd "$project_dname"
-
- # Discard Harmony version history
- rm -rf .git
- git init
-
- # Set the default branch name
- git checkout -b core_developer_branch
-
-# Initial Commit
-#
- git add .
- git commit -m "$initial_commit_message"
+++ /dev/null
-
-1. Authored
-
- An authored file is one that is not to be edited by build scripts. Scripts should
- treat them as read only.
-
- An authored directory is one where the contained files in the directory subtree
- are considered to be authored files.
-
-2. First implementation now deprecated.
-
- Authored directories had a `🖉` character as the last character of their names.
-
- Files were considered to be authored if they were in an authored directory, or anywhere
- in its subtree. Or if the file name had a `🖉` character as the last character of its name.
-
- Then the `rm_na` command was used in scripts. This version of `rm` would refuse to delete authored files.
-
- This approach had two drawbacks. Some tools still have difficulty with such Unicode characters, and many keyboard entry interfaces and editors provide no means for entering them. Secondly, `rm_na` does not enforce read-only semantics, rather it merely prevents deletion.
-
- As a result, the pencil characters and `rm_na` have been removed from the RT workflow.
-
-3. Status quo
-
- Read-only authored directories and files are planned to come back through another implementation, see point 4. In the meantime, we keep them as a contract with developers. Document, source, and executable directories are authored. Script driven synthesis and editing work is done in the `scratchpad` directories. The `scratchpad` directory contents is gitignored.
-
-4. The planned implementation.
-
- When the `subu` system reaches a production version, it will be used to create a sub user for the developer called 'builder'. The developer can then set file permissions for builder.
-
+++ /dev/null
-#+TITLE: RT Harmony Build Environment (Orchestrator + Build Domains: lib_cli, kmod)
-#+OPTIONS: toc:nil
-
-* 0. Scope
-A concise contract for building user-space artifacts (static libraries + CLI executables) and Linux kernel modules (out-of-tree, *.ko) in one repo without target collisions. Authored sources remain read-only; all synthesis happens in ~scratchpad/~. A small, stable public interface is exposed via an orchestrator Makefile.
-
-* 1. Core Principles
-1.1 Minimize complexity (YAGNI): one happy path; branch only when mandated.
-1.2 Variable-driven config: the project declares *what*; domain makefiles define *how*.
-1.3 Automatic discovery by suffix: ~*.lib.c~, ~*.cli.c~, ~*.mod.c~; never hard-code basenames.
-1.4 Authored trees are read-only to scripts; writes go to ~scratchpad/~.
-1.5 Build domains are independent and reusable; orchestration is via separate ~make -f~ calls.
-
-* 2. Repo Layout, Authority, and Skeleton
-2.1 =REPO_HOME= is exported by the environment and is the authoritative project root.
-2.2 Build is invoked from =$REPO_HOME/developer=.
-2.3 Domain makefiles are vendored under:
- =$(REPO_HOME)/tool_shared/third_party/RT-project-share/release/make/=
-2.4 Directory semantics:
- 2.4.1 =developer/cc/= **authored** C sources (read-only to scripts).
- 2.4.2 =developer/scratchpad/= **SCRATCHPAD** (intermediates, depfiles, kbuild outputs, CLI binaries).
- 2.4.3 =release/= publish area (e.g., =release/machine= for executables, =release/module= for *.ko).
-2.5 Harmony skeleton invariants: the skeleton pre-creates the standard tree; recipes may assume directories exist.
-
-* 3. Build Domains & Files
-3.1 Orchestrator (project-local): =developer/tool/makefile=
- - Public targets: ~all~, ~lib_cli~, ~kmod~, ~clean~ (~usage~ optional; ~all~ is first).
- - Includes =environment_RT_1.mk= and invokes domain makefiles via ~make -f~.
-3.2 Domain: user-space → =target_lib_cli.mk=
- - Builds static lib from ~*.lib.c~ and CLI executables from ~*.cli.c~.
- - Public targets: ~library~, ~cli~, ~clean~. ~cli~ depends on ~library~.
-3.3 Domain: kernel modules → =target_kmod.mk=
- - Builds out-of-tree modules (~.ko~) from ~*.mod.c~ using Kbuild.
- - Public targets: ~kmod~, ~clean~.
-
-* 4. Public-Target Orchestration (strict)
-4.1 The orchestrator owns public targets and their order. Domains expose callable targets but are not public entrypoints.
-4.2 Shape:
-#+BEGIN_SRC makefile
-RT_INCOMMON := $(REPO_HOME)/tool_shared/third_party/RT-project-share/release
-include $(RT_INCOMMON)/make/environment_RT_1.mk
-
-.PHONY: all lib_cli kmod clean
-all: lib_cli kmod
-
-lib_cli:
- @$(MAKE) -f $(RT_INCOMMON)/make/target_lib_cli.mk cli
-
-kmod:
- @$(MAKE) -f $(RT_INCOMMON)/make/target_kmod.mk kmod
-
-clean:
- @$(MAKE) -f $(RT_INCOMMON)/make/target_lib_cli.mk clean
- @$(MAKE) -f $(RT_INCOMMON)/make/target_kmod.mk clean
-#+END_SRC
-4.3 Result: no target collisions. ~all~ remains the single happy path.
-
-* 5. Discovery & Suffix Contract
-5.1 Suffixes define intent:
- 5.1.1 ~*.lib.c~ → compiled into a static archive.
- 5.1.2 ~*.cli.c~ → linked into CLI executables.
- 5.1.3 ~*.mod.c~ → compiled via Kbuild into ~.ko~.
-5.2 Discovery is implemented in the domain makefiles; the orchestrator can optionally export a filtered list but domains must work without it.
-
-* 6. Authored vs Write Areas
-6.1 **Authored** (=developer/cc/= and other documented trees): tools never write into authored trees.
-6.2 **SCRATCHPAD** (=developer/scratchpad/=): all intermediates, depfiles, CLI binaries, and kbuild outputs (~.ko~).
-6.3 **release/**: explicit promotion target. Nothing writes here during build; only an explicit release step copies from ~developer/scratchpad/~.
-
-* 7. Dependencies
-7.1 User-space: ~CFLAGS += -MMD -MP~ with per-object depfiles included.
-7.2 Depfiles live beside objects in ~developer/scratchpad/~ and are removed by ~clean~.
-7.3 No separate “make dependency” step.
-7.4 Kbuild manages kernel deps internally.
-
-* 8. Kbuild Integration (kmod)
-8.1 Kbuild interface: =/lib/modules/$(uname -r)/build= (kernel headers/devel tree).
-8.2 All Kbuild artifacts are directed to the project SCRATCHPAD:
- ~KBUILD_OUTPUT_DIR := $(CURDIR)/$(SCRATCHPAD)~.
-8.3 Shape:
-#+BEGIN_SRC makefile
-ifndef REPO_HOME
- $(error REPO_HOME is not set; build must be done in a project environment)
-endif
-KBUILD_BASE_List := $(basename $(notdir $(wildcard $(REPO_HOME)/developer/cc/*.mod.c)))
-KMOD_BUILD_DPath := /lib/modules/$(shell uname -r)/build
-KBUILD_OUTPUT_DIR := $(CURDIR)/$(SCRATCHPAD)
-
-KERNEL_OBJS_M := $(addsuffix .o,$(KBUILD_BASE_List))
-KMOD_TARGETS := $(addsuffix .ko,$(addprefix $(KBUILD_OUTPUT_DIR)/,$(KBUILD_BASE_List)))
-
-.PHONY: kmod clean
-kmod: $(KMOD_TARGETS)
-
-$(KBUILD_OUTPUT_DIR)/%.c: $(REPO_HOME)/developer/cc/%.mod.c
- cp $< $@
-
-$(KBUILD_OUTPUT_DIR)/%.ko: $(KBUILD_OUTPUT_DIR)/%.c
- $(MAKE) -C $(KMOD_BUILD_DPath) M=$(REPO_HOME) O=$(KBUILD_OUTPUT_DIR) obj-m=$*.o
-
-clean:
- $(MAKE) -C $(KMOD_BUILD_DPath) M=$(REPO_HOME) O=$(KBUILD_OUTPUT_DIR) obj-m="$(KERNEL_OBJS_M)" clean
-#+END_SRC
-
-* 9. User-Space Domain (lib + CLI)
-9.1 Domain name: =target_lib_cli.mk=.
-9.2 Shape:
-#+BEGIN_SRC makefile
-# Scan *.lib.c / *.cli.c; derive OBJECT_LIB / OBJECT_EXEC under $(SCRATCHPAD)
-# -include $(OBJECT_LIB:.o=.d) $(OBJECT_EXEC:.o=.d)
-# library: builds $(LIBFILE) from OBJECT_LIB (empty archive OK)
-# cli: depends on $(LIBFILE); links each $(EXECDIR)/% from %.cli.o + $(LIBFILE)
-# With EXECDIR := $(SCRATCHPAD), CLIs land in developer/scratchpad/
-#+END_SRC
-
-* 10. Variable Conventions
-10.1 Export-worthy variables in ALL_CAPS.
-10.2 Do not assign to =REPO_HOME= in Makefiles.
-10.3 Canonical scratch directory variable: =SCRATCHPAD=.
-10.4 Prefer explicit paths (e.g., link with ~$(LIBFILE)~) unless you require ~-L/-l~ naming.
-
-* 11. Usage & Defaults
-11.1 Domain makefiles may expose ~usage~ as the first target for direct calls.
-11.2 Orchestrator keeps ~all~ as the first target (so ~make~ “just works”).
-11.3 Skip-if-empty logic is not required; empty prereq lists no-op naturally.
-11.4 Optional diagnostic: ~check-pwd~ can warn if ~$(CURDIR) ≠ $(REPO_HOME)/developer~.
-
-* 12. Release Conventions
-12.1 Build outputs (CLIs and ~.ko~) remain in ~developer/scratchpad/~.
-12.2 Promotion is explicit: copy **as-is** into ~release/machine~ (executables) or ~release/module~ (kernel modules).
-12.3 No arch suffixing at build time; no per-arch subdirs; no symlinks.
-
-* 13. Alternatives considered (and why not chosen)
-13.1 **Script adds arch suffix at release time:** Needs to “guess” artifact identity and build arch; risks drift if build host ≠ release host.
-13.2 **Make target adds arch suffix at build time:** Hard-codes basename rules or requires extra metadata; increases cognitive load for developers.
-13.3 **Per-arch release trees + symlinks:** Adds directory sprawl and symlink churn; complicates diffs and reviews.
-13.4 **Chosen:** local build/use + explicit promotion. It is the least complex, avoids mismatch hazards, and keeps authored trees clean. Artifacts are reproducible from sources; release is a conscious, auditable copy.
-
-* 14. Summary (Do / Don’t)
-14.1 Do keep domains independent; orchestrator stitches them via ~make -f~.
-14.2 Do derive *what to build* from suffixes; don’t hard-code filenames.
-14.3 Do confine writes to ~developer/scratchpad/~; never write in authored trees.
-14.4 Don’t auto-publish; use explicit promotion to ~release/~.
-14.5 Harmony skeleton pre-creates the standard tree; recipes may assume directories exist.
+++ /dev/null
-Ah oui. Donc ..
-
-This is what I would like you to do. Start over on the core code.
-
-1. there is git ignore class.
-
-A 'discern' function is any function that is given a project path and a relative path into the project, and then returns either 'Accept' or 'Ignore'.
-
-The git ignore class holds a discern function stack. Said stack is initialized with a triple. the first of the pair is a discernment function that always returns 'Accept'. The second in the triple is a project path, and the third a relative path to a directory where said .gitignore was found.
-
-Initially the stack is empty.
-
-Said class has a method called `check` that returns either 'Accept' or 'Ignore'.
-
-When traversing a project tree, typically Harmony, or <other>, the traversing function will send each (<project>, <rel>, <information>) triple to the `check` method of the git ignore class instance. For our program we have one such instance.
-
-The `check` method: 1) if the discern stack i snot empty, `check` calls the discern functions on the ignore function stack, if any of them returns 'Ignore' the `check` method immediately returns 'Ignore'. 2) if all `discern` function returns `Accept`, and the node name is '.gitignore', then:
-2.1 the top of the discern stack path is checked and compared to the path to the node given to `check`. If the path is the same, then we have a strange error, we have seen two files called .gitignore in the same directory. I guess we go buy a lottery ticket.
-2.1 the path to the node is sent to then sent to `parse_gitignore` function which returns a discern function. That functino as part of the triple, is pushed onto the git ignore instance's discern function stack.
-
-When ever the traversing function pops back up, it calls the classe's 'pop' function which pops the top off of the git ignore instance's discern function stack.
-
-A note about the gitignore file parser: currently (see to-do list) it returns one of two dicern functions. If the relative path is empty, i.e. we are at the top of the project, then it returns a discern function that returns Accept. If the relative path is not empty, it returns a discern function that always returns 'Ignore'.
-
-2. The <other> subset Harmony checker:
-
-2.1 First traverse the entire Harmony tree. That is the tree that has the tool directory the checker is running from.
-
-For each node in the Harmony tree:
-2.1.1 check if it is to be ignored, if so skip it
-2.1.2 take said node's relative path and use it as a key for a new entry in the 'skeleton dictionary'. Make the entry value 'information' about its node.
-
-A node's 'information' includes: modification date, and its type being file or directory or something else, and if it is a leaf node or not in the tree. (surely 'make_information' is a separate function). If the 'checksum' command is given, then the node's checksum becomes part of information. (new command)
-
-
-2.2 traverse the <other> tree and make two sets:
-2.2.1 an 'ignored' set, of the relative paths to ignored files. This will require making a git ignore class instance and calling the proper methods while doing a traversal.
-2.2.2 look up the relative path to the <other> node in the skeleton dictionary
-2.2.2.1 if lookup information says the <other> node corresponds to a leaf node in the skeleton, do not descend into this node.
-2.2.2.2 if the lookup into the skeleton dictionary fails, add this node to the 'addendum' list.
-
-
-2.2 traverse the skeleton dictionary entries
-
-for each entry:
-2.2.1 Check if the relative path is in the <other> gitignored set.
-2.2.1.1 If so add it to the 'present_but_ignored' list. Continue to the next entry. Otherwise:
-2.2.1.2 Use the relative path (the dictionary key) to extend the <other> project path to get an <other> node path.
-2.2.1.2.1 check if such a node exists (likely either a file or a directory it is exists)
-2.2.2.2.1.1 If there is not an <other> node found: add said relative path to the 'missing' list, and continue to the next entry. Otherwise:
-2.2.2.2.1.2 If the skeleton dictionary information says it is a leaf node in the skeleton, but it is not a leaf node in <other> then send this directory node to the addendum descender function. (The addendum descender function then descends from said <other> node, while appending all node relative paths discovered into the addendum list.)
-2.2.2.2.1.3 If the <other> node has a more recent modification time add its relative path to the 'newer' list. If it is older add it to the 'older' list. If it is the same age, and the 'checksum' command has been given, compare the checksums. If they differ, then add the relative path to the 'different' list.
-
-3. Make reports. Each report we are to generate corresponds to a command name. We will need additional commands to cover the additional lists I described in this spec. The 'all' command will generate all the reports, of course.
+++ /dev/null
-skeleton_diff — Harmony skeleton vs <other> spec
-===============================================
-
-0. Context
-0.1 Harmony is the authoritative skeleton.
-0.2 Each Harmony derived project (“<other>”) starts as a clone of Harmony.
-0.3 Over time:
- 0.3.1 Harmony evolves.
- 0.3.2 Individual projects evolve.
- 0.3.3 Some improvements flow back to Harmony, some do not.
-0.4 The goal is to detect and reason about drift between Harmony and <other>
- using a clear, explicit model of:
- 0.4.1 The Harmony skeleton (authoritative source of structure).
- 0.4.2 The <other> tree (authoritative source of what actually exists).
- 0.4.3 Git ignore semantics (even if approximated at first).
- 0.4.4 Node level information (type, mtime, leaf status, checksum).
-
-1. GitIgnoreDiscern class
-1.1 A “discern” function
- 1.1.1 Signature: discern(project_root, rel_path, info) -> "Accept" | "Ignore".
- 1.1.2 rel_path is a Path relative to project_root.
- 1.1.3 info is node information (see section 2.3).
-1.2 GitIgnoreDiscern instance
- 1.2.1 Holds a “discern function stack”.
- 1.2.2 Each entry in the stack is a triple:
- (discern_function, project_root_path, rel_dir_path_of_gitignore)
- 1.2.3 The stack is initialized empty.
-1.3 check method
- 1.3.1 Input: (project_root, rel_path, info).
- 1.3.2 Behavior:
- 1.3.2.1 If the discern stack is not empty:
- - Iterate from top to bottom (or bottom to top, but chosen and
- documented) calling each discern function.
- - If any discern returns "Ignore", then check returns "Ignore".
- 1.3.2.2 If all discern functions return "Accept", then:
- - If the node name is ".gitignore", we handle it specially
- (see 1.4).
- - Otherwise, return "Accept".
-1.4 Handling ".gitignore"
- 1.4.1 When check sees a node whose name is ".gitignore":
- 1.4.1.1 The path of the directory that contains this .gitignore is rel_dir.
- 1.4.1.2 For now we do not attempt to detect “two .gitignore files in the
- same directory”; that would indicate a malformed filesystem.
- 1.4.1.3 We call parse_gitignore(project_root, rel_dir) which returns a
- discern function.
- 1.4.1.4 We push (discern_function, project_root, rel_dir) onto the
- discern function stack.
- 1.4.1.5 check returns "Accept" for the .gitignore file itself.
-1.5 pop method
- 1.5.1 The tree traversal logic must call a pop method whenever it pops
- back up from a directory that had a .gitignore.
- 1.5.2 pop removes the top triple from the discern function stack.
-1.6 parse_gitignore approximation
- 1.6.1 For now (heuristic phase):
- 1.6.1.1 If rel_dir is empty (we are at the project root):
- - Return a discern function that always returns "Accept".
- 1.6.1.2 If rel_dir is not empty:
- - Return a discern function that always returns "Ignore" for
- any node under that directory (except the .gitignore itself).
- 1.6.2 Future work (TODO):
- 1.6.2.1 Properly parse .gitignore content.
- 1.6.2.2 Build discern functions that implement the documented
- semantic of .gitignore patterns.
-
-2. Harmony dictionary (“skeleton dictionary”)
-2.1 Traversal
- 2.1.1 Traverse the entire Harmony tree.
- 2.1.2 This is the tree that contains the tool directory skeleton_check is
- running from, or equivalently the tree rooted at $REPO_HOME.
- 2.1.3 The traversal:
- 2.1.3.1 Maintains a GitIgnoreDiscern instance.
- 2.1.3.2 For each node encountered:
- - Build rel_path, the path relative to Harmony root.
- - Build info (see 2.3).
- - Call gitignore.check(HARMONY_ROOT, rel_path, info).
- - If "Ignore", skip the node (and if it is a dir, do not descend).
- - If "Accept", proceed.
-2.2 Skeleton dictionary
- 2.2.1 For each accepted node:
- - Use rel_path as a dictionary key.
- - Store a NodeInfo object as the value.
- 2.2.2 All rel_paths in this dictionary are part of the “skeleton”.
-2.3 Node information (“information”)
- 2.3.1 Fields:
- 2.3.1.1 path_type: "file" | "dir" | "other".
- 2.3.1.2 mtime: numeric modification timestamp.
- 2.3.1.3 is_leaf_flag: bool, true if the node is a leaf in the tree.
- 2.3.1.4 checksum: optional checksum (string or bytes) when enabled.
- 2.3.2 Leaf definition:
- 2.3.2.1 For directories: a dir is a leaf if there are no child nodes
- recorded beneath it (no children in the dictionary).
- 2.3.2.2 For files and “other”: they are trivially leaves as far as
- the tree structure is concerned.
-2.4 Checksum mode
- 2.4.1 If the “checksum” command has been given:
- 2.4.1.1 NodeInfo includes a checksum of file contents.
- 2.4.1.2 For non files, checksum may be None.
- 2.4.2 Computing checksums is optional and may be expensive.
-
-3. <other> traversal and ignored set
-3.1 Traversal of <other>
- 3.1.1 We traverse the <other> tree (project root = other_root).
- 3.1.2 We use a *separate* GitIgnoreDiscern instance for <other>.
- 3.1.3 For each node:
- 3.1.3.1 Compute rel_path relative to other_root.
- 3.1.3.2 Compute NodeInfo for that node.
- 3.1.3.3 Call gitignore.check(other_root, rel_path, info).
-3.2 Ignored set
- 3.2.1 If gitignore.check says "Ignore":
- 3.2.1.1 Do not descend into that node if it is a directory.
- 3.2.1.2 Add rel_path to the “ignored” set for <other>.
- 3.2.2 If gitignore.check says "Accept":
- 3.2.2.1 Do descend into directories.
- 3.2.2.2 Do *not* add this rel_path to the “ignored” set.
-3.3 Skeleton lookup while traversing <other>
- 3.3.1 For each accepted <other> node:
- 3.3.1.1 Look up rel_path in the skeleton dictionary.
- 3.3.1.2 Cases:
- a) Found in skeleton_dict:
- - skeleton_info = skeleton_dict[rel_path].
- - If skeleton_info.is_leaf_flag is True and the
- <other> node is a directory, then:
- * This directory corresponds to a skeleton leaf.
- * Do not descend further in the *outer* traversal.
- * Let the addendum descender handle any deeper nodes.
- b) Not found in skeleton_dict:
- - Add rel_path to the “addendum seed” list (see 4.1.3).
- - Descend normally; deeper nodes are also addendum candidates.
-
-4. Comparing skeleton_dict and <other>
-4.1 Lists to construct
- 4.1.1 missing_list
- - Paths that exist in skeleton_dict but do not exist in <other>
- (and are not in the ignored set for <other>).
- 4.1.2 present_but_ignored_list
- - Paths that exist in skeleton_dict, and whose rel_path appears
- in the <other> ignored set.
- 4.1.3 addendum_list
- - Paths that exist in <other> but not in skeleton_dict.
- - This may be built by:
- a) While traversing <other>, for any accepted node whose
- rel_path is not in skeleton_dict, add it to addendum_list.
- b) Additionally, when we find an <other> directory node that
- corresponds to a skeleton leaf directory, an “addendum
- descender” may be called starting from that node to gather
- all project specific material under that subtree into
- addendum_list.
- 4.1.4 newer_list
- - For nodes where rel_path exists in both skeleton_dict and
- <other>, and both are files:
- - If mtime(other) > mtime(skeleton), add rel_path to newer_list.
- 4.1.5 older_list
- - As above, but mtime(other) < mtime(skeleton).
- 4.1.6 different_list (checksum mode)
- - If checksums are available and mtime(other) == mtime(skeleton),
- but checksum(other) != checksum(skeleton), add rel_path to
- different_list.
-
-4.2 Detailed skeleton dictionary scan
- 4.2.1 For each entry in skeleton_dict:
- 4.2.1.1 Let rel_path be the key, skeleton_info the value.
- 4.2.1.2 If rel_path is in <other> ignored set:
- - Add rel_path to present_but_ignored_list.
- - Continue to next skeleton entry.
- 4.2.1.3 Construct other_path = other_root / rel_path and see if it exists.
- a) If other_path does not exist:
- - Add rel_path to missing_list.
- - Continue.
- b) If skeleton_info.is_leaf_flag is True and the
- other_path is a directory:
- - This is a subtree under a skeleton leaf.
- - Call the addendum descender on other_path to
- gather project specific additions.
- - Continue after that.
- c) If both sides are files:
- - Compare mtimes and optional checksums and update
- newer_list, older_list, different_list.
-
-5. Commands and reports
-5.1 Commands correspond to reports or combined analyses:
- 5.1.1 environment
- - Print environment, including REPO_HOME and useful Harmony variables.
- 5.1.2 structure
- - Use skeleton_dict and <other> to report missing directories and
- structural drift.
- - Interpret “between” vs “below” using skeleton leaf boundaries:
- - Missing nodes under skeleton directories indicate incomplete
- adoption in <other>.
- - Extra nodes under skeleton leaf directories indicate “below”
- project additions.
- 5.1.3 import
- - Use newer_list.
- - Print cp commands to copy from <other> into Harmony.
- - Do not execute the commands.
- 5.1.4 export
- - Use older_list.
- - Print cp commands to copy from Harmony into <other>.
- - Do not execute the commands.
- 5.1.5 suspicious
- - Use addendum_list plus knowledge of expected zones:
- - Ignore developer/, tester/, release/ (user owned).
- - Ignore tool/ and tool_shared/ (tool zones).
- - Anything else that is not in skeleton_dict and not in
- user owned or tool zones is suspicious.
- 5.1.6 addendum
- - Report project specific additions under tool/ and tool_shared/
- that are not in skeleton_dict.
- - Essentially a filtered view of addendum_list.
- 5.1.7 checksum
- - Enable checksum mode and produce different_list in addition to
- newer_list and older_list.
- - May be a standalone command, or a modifier to import/export.
- 5.1.8 present_but_ignored
- - Report skeleton paths that exist in Harmony but are ignored by
- <other>’s gitignore semantics.
- 5.1.9 all
- - Run the complete suite: environment, structure, import, export,
- suspicious, addendum, present_but_ignored, checksum (if enabled).
-5.2 “files” is not a user facing command
- 5.2.1 The “files” step is internal: it is the comparison over
- skeleton_dict and <other> that builds newer_list, older_list,
- different_list.
- 5.2.2 import/export use its results.
-
-6. Safety guarantees
-6.1 No writes
- 6.1.1 The program does not modify files.
- 6.1.2 It only prints suggested commands and reports.
-6.2 Time based comparison
- 6.2.1 Newer vs older is based on mtime. If clocks are misleading,
- results need manual judgment.
-6.3 Git integration
- 6.3.1 The tool assumes Harmony is under git so old versions exist even
- after cp operations.
-6.4 Exit status
- 6.4.1 0 on success (even if differences are found).
- 6.4.2 Non zero on argument errors or internal failures (e.g. invalid
- project path).
+++ /dev/null
-#+TITLE: RT Code Format Guide
-#+AUTHOR: Thomas Walker Lynch
-#+DATE: 2025-02-28
-#+OPTIONS: toc:nil
-
-# perhaps add rules about main functions being merely wrappers that pack arguments, call the reall business function, and then unpack results from the business function perhaps to print, and to set the main return value.
-
-* Introduction
-
-The RT Code Format is intended to apply across languages, and thus the rules are agnostic to the language being code. The RT Code format produces a dense output so as to make room
-for longer identifier names and to put more code on that tiny screen of your laptop so you can work in a cafe. The rules focus on indentation, naming conventions, enclosure spacing, and unique handling of commas.
-
-* RT Formatting Should Be Applied After Any Other Formatting
-
-Many formatting tools apply automatic spacing and alignment adjustments before finalizing code. One common example is Preemptive Enclosure Adjustment (PEA), where spaces are added or removed inside enclosures automatically. This can cause conflicts with RT Formatting rules.
-
-RT Formatting should be applied as a **final step** to resolve such conflicts:
-- RT rules **override** PEA rules where they differ.
-- Where there is no conflict, existing formatting remains unchanged.
-- This ensures consistency when AI-generated code is reformatted.
-
-Common formatting conflicts:
-- **Indentation:** PEA favors 4-character indentation, whereas RT Formatting enforces 2-character indentation.
- This allows for more liberal indentation use and keeps statements compact.
-- **Comma Placement:** RT Formatting treats the comma as a **syntactic append operator**.
-- **Parentheses, Brackets, and Braces:** AI should follow the **exception detection procedure** for enclosure spacing.
-- **Operator Formatting:** Certain operators require **specific spacing rules**.
-- **Short Statements:** `if`, `while`, and similar constructs follow the **Short Stuff Rule** for single-line clauses.
-
-* Naming Conventions
-
-1. **Namespaces and types** use *PascalCase*.
-2. **Functions and variables** use *snake_case*.
-3. **Ordered collections** use `_list` as a suffix (e.g., `node_list`), even if the language does not have a `List` type.
-
-Examples:
-#+BEGIN_SRC c
-mouse_count
-test_LabelList_0 // Function testing LabelList (a class/type)
-Thomas_Walker_Lynch
-#+END_SRC
-
-* Binary Operators
-
- There is no space around multiply and divide binary operators.
-
- There is one space around all other operators.
-
-* Assignment
-
- Two types of assignment:
-
- 1. sampling assignment, `=` inside `if`, `while`, etc.
- 2. single statement assignment
-
- No space around sampling assignment `=`.
-
-Example:
-#+BEGIN_SRC c
-if( result=some_condition() ){ // Sampling assignment, no spaces
- process(result);
-}
-a = b + c; // Regular assignment with spaces
-#+END_SRC
-
-* No space before Newline
-
-There is never space before an unquoted newline.
-
-* Enclosure
-
-Enclosed text is found after an opening enclosure punctuation symbol,
-and before the matching closing punctuation symbol.
-
-- `(...)` (parentheses)
-- `{...}` (braces)
-- `[...]` (square brackets)
-- `<...>` (angle brackets)
-
-It is common to find enclosures as part of language statements. For example:
-#+BEGIN_SRC c
-if(i<10)
-#+END_SRC
-Here the enclosed text is `i<10`.
-
-As another example:
-#+BEGIN_SRC c
-while(true)
-#+END_SRC
-Here the enclosured text is `true`.
-
-Enclosures are also found in expressions. For example:
-#+BEGIN_SRC c
- 3*(2 + 4)
-#+END_SRC
-Here the enclosed text is `2 + 4`.
-
-There can be multiple enclosures in a given statement, depending on the language, or in a given expression. For example:
-#+BEGIN_SRC c
- (1 +3)*(2 + 4)
-#+END_SRC
-Here there are two enclosures `(1 + 3)` and `(2 + 4)`. The first enclosure encloses the text `1 + 3` while the second encloses `(2 + 4)`.
-
-In RT formatting, there is no native space before or after the enclosure punctuation. There can be space due to other rules, such as the space around the plus operator. For example:
-#+BEGIN_SRC c
- (1*3) + (2*4)
-#+END_SRC
-Here the space around the enclosure punctuation belongs to the operator, rather than to the enclosure punctuation.
-
-Enclosed text can hold further enclosed text. This is 'nesting' of enclosures.
-
-Because enclosure nesting can run deep, we have allowed for one exception to the no space enclosure punctuation rule. Follow these steps:
-
-** Line-by-Line Formatting
-
-Enclosure formatting is applied **per line**, without scanning beyond that line.
-
-- **Virtual Closure Rule:**
- At the **end of a line**, any still-open enclosure punctuation is treated as **closed** for formatting purposes.
-
-- **Virtual Opening Rule:**
- At the **start of a new line**, any **orphaned closing punctuation** found there is treated as **belonging to the current line**.
-
-
-** Procedure for Identifying Enclosure Exceptions
-
-1. The language is not Lisp.
-2. The enclosure meets **all** of the following conditions:
- - It opens and closes on a **single line**.
- - It contains at least **one nested enclosure** inside.
- - It is not found in the enclosed text of other enclosure on that line.
-3. If these conditions hold, **apply the exception**:
- - Insert **one space** after the opening enclosure punctuation.
- - Insert **one space** before the closing enclosure punctuation.
-
-**Example of a qualifying enclosure:**
-#+BEGIN_SRC c
-if( (x == 3 || y < 5) && z ){
- process_data();
-}
-#+END_SRC
-
-Here, `( (x == 3 || y < 5) && z )` qualifies for spacing adjustment.
-
-**Example of a non-qualifying enclosure:**
-#+BEGIN_SRC c
-if(y < 5){
- process_data();
-}
-#+END_SRC
-
-Since no enclosure on this line meets the conditions, **no additional spaces** are added.
-
-** Adjacency
-When two enclosures appear side by side (like `)(` or `}{`), there is *no space* between them.
-
-* Commas
-
-The **comma rule** is one of the most distinctive and recognizable aspects of RT Code Formatting.
-
-1. **One space before the comma** (e.g., `a ,b`).
-2. **No space after the comma** (e.g., `a ,b`).
-3. **Line break before the comma when breaking lines**, but **no line break after the comma**.
-
-Examples:
-#+BEGIN_SRC c
-a
-,b
-#+END_SRC
-
-When function arguments get too long, break lines as follows:
-#+BEGIN_SRC c
-result = some_function(
- first_argument
- ,second_argument_with_longer_name
- ,third_argument
-);
-#+END_SRC
-
-✔ **This ensures consistency and maintains readability.**
-
-* Short Stuff Rule
-
-For **`if`**, **`for`**, and **`while`** statements that introduce a *single-line* clause with no `else`, if the **condition and clause together fit within one line, they should **remain on a single line without braces**. Say when about ≤40 characters, though this is not strictly ≤40 characters — it depends on complexity and formatting. If the condition and action are simple, or perhaps fit a parallel construct with other short stuff, they should stay inline.
-
-
-
-
-
-Example:
-#+BEGIN_SRC c
-if( x > 0 ) return x;
-while( has_next() ) process_next();
-#+END_SRC
-
-
+++ /dev/null
-* Bracketed Phrases
-
-In token processing, a *bracketed phrase* is the text starting from an opening bracket up to its matching closing bracket, including both brackets. We treat any of `(...)`, `{...}`, `[...]`, or `<...>` as “brackets”. Bracketed phrases are detected purely at the token level—no higher-level grammar or semantics are considered.
-
-** Examples
-- **`if(x){...}` vs. `f(x){...}`**
- Both share the same token-level structure: an identifier followed by `(x)` and then `{...}`.
-- **`sin(3x)`**
- Has one bracketed phrase `(3x)`, where `3x` is the “contents” and `()` is the “container.”
-
-** Nesting
-
-1. **Innermost Bracketed Phrase**
- Contains *no other* bracketed phrase inside it. Due to adjacency, multiple innermost bracketed phrases can occur.
-
-2. **Outermost Bracketed Phrase**
- An outermost bracketed phrase is one that is not itself contained in any other bracketed phrase.
-
-3. **Contained (Inner) Bracketed Phrase**
- A bracketed phrase located within the contents of another bracketed phrase (the *outer* one).
-
-4. **Bracketed Phrase with Nesting**
- A bracketed phrase that contains one or more bracketed phrases.
-
- A bracketed phrase is “with nesting” only if it contains at least one inner bracketed phrase. In other words, non-quoted bracket punctuated phrases occurs inside the contents — not just commas or other punctuation.
-
-
-**Examples**
-In `sin(f(x) + (a))`, the phrase `(x)` is contained in `(f(x) (a))`, which in turn is contained in `sin(...)`. `(a) is also contained in`(f(x) (a))`. `(x)` is innermost.
-`(a)` is also innermost.
-
-**Open Bracketed Phrases
-
-A bracketed phrase is **open** if it’s missing a matching opening or closing bracket.
-
-- **Open on the Right**: Has unmatched opening brackets (e.g., `(` but no `)`).
-- **Open on the Left**: Has unmatched closing brackets (e.g., `)` but no preceding `(`).
-
-** 1D Box Analogy
-
-Think of each bracketed phrase like a **1D CSS box**:
-
-- The **opening and closing brackets** are the “borders.”
-- **Margin (outside)**: By default, bracketed phrases have *no extra spacing* around their borders—unless another rule (like an operator or adjacent token) requires space.
- Example: `f()()` is valid with no space, but `f () ()` is not.
-- **Padding (inside)**: If a bracketed phrase is both
- 1) outermost on a line,
- 2) has nesting,
- 3) and is not a Lisp s-expression,
- then place **one space** immediately after the opening bracket and **one space** before the closing bracket.
-
+++ /dev/null
-#+TITLE: RT Project Workflow (Spartan)
-#+AUTHOR: RT
-#+OPTIONS: toc:2 num:nil
-
-* Purpose
-Lightweight workflow for RT projects using the Harmony skeleton. Roles are simple; releases are branches. Keep friction low so we can ship.
-
-* Roles
-** 1) Toolsmith
-- Sets up the skeleton
-- Populates shared tools
-- Maintains those tools
-
-** 2) Developer
-- Translates the spec into code
-- Evolves the code iteratively
-
-** 3) Tester
-- Writes unit tests for small functions
-- Writes integration tests
-- Assembles and runs the regression suite
-- *Policy:* every reported bug gains a test in the regression suite
-
-** 4) Project Manager
-- Aligns on “what is working and how well”
-- Confirms readiness to cut a release branch (with the team)
-
-* How to enter the project
-1) =cd= to the project root
-2) Source the proper environment (e.g., =. env_developer=)
-3) Run tools *inside that environment*
-
-* Release flow
-** The little loop
-The =core_developer_branch= is the moving head under active development.
-
-- =\$REPO_HOME/release= holds *current candidates under test* (convenience staging).
-- Loop:
- 1. Architect and PM, maintain the “required + desired” feature manifest.
- 2. Architect sketches the outline (expect it to evolve).
- 3. Developers implement features.
- 4. Developers drop candidates into =$REPO_HOME/release=.
- 5. Tester exercises candidates, files bugs, and adds tests to the regression suite.
- 6. Developers address issues and produce new candidates.
- 7. Repeat until candidates are sufficiently functional and reliable.
-
-Developers may keep personal experiments under =developer/=. These are not written for repeatability like tests; though they might seed future tests.
-
-** The big loop
-When candidates in =$REPO_HOME/release= are sufficiently functional and stable—and the PM agrees on “what is working and how well”—*cut a release branch*.
-
-- *Name*: =release_v<n>= where =n= is the next consecutive integer (starting at 1).
-- *Create*:
- #+begin_src sh
- git checkout core_developer_branch
- git pull --ff-only
- git branch release_v3
- git push reasoning_repo release_v3
- git push github_repo release_v3
- #+end_src
-- After this, the release branch “takes on its own life.”
-
-If a non-urgent bug is found on the shipped line:
-- Fix it on =core_developer_branch= for the next release (backport to the release if truly needed).
-- Due to the bug getting a regression test, the core developers will not forget it.
-
-If an urgent fix is needed on the shipped line:
-- Apply the fix on =release_v<n>=, then cut =release_v<n.m>= where =m= is the next consecutive modification number (starting at 1).
-- As always, *add a regression test* for the bug.
-
-* Deprecation
-New major releases *deprecate prior releases*. Maintainers decide any support window.
-
-* Do / Don’t
-- *Do*: fast-forward pulls on release branches; keep history linear.
-- *Do*: keep fixes small and targeted.
-- *Don’t*: rebase release branches.
-- *Don’t*: routinely merge the moving core branch into a release line.
-
-* Notes
-- Tags are not required in this spartan flow (use only if your distribution channel needs them).
-- Consider server-side protection on =release_v*= branches to prevent force-pushes.
-- Typical remotes: =reasoning_repo= (internal) and =github_repo= (GitHub). Substitute if yours differ.
-
-* One-liner mental model
-Core keeps moving; releases branch off and live their own lives. If everyone uses Harmony, we all live in peace. :)
+++ /dev/null
-* Project Directory Structure
- This document explains the naming conventions and layout of the project files.
-
-** 1. Top-Level Directory (`Harmony/`)
- - aka `$REPO_HOME`, managed by the project administrator.
-
-** 2. Developer Workspace (`Harmony/developer/`)
- - Contains source code, build scripts, and development tools.
-
- - **Subdirectories:**
- - `deprecated/` :: Contains old or refactored files.
- - `document/` :: Developer-specific documentation.
- - `javac/` :: Java source code.
- - `jvm/` :: Compiled Java bytecode (JARs, class files).
- - `scratchpad/` :: Temporary workspace for builds.
- - `shell/` :: Executable scripts.
- - `tool/` :: Development utilities.
-
-** 3. Testing Workspace (`Harmony/tester/`)
- - Contains test benches, test scripts, and test documentation.
-
- - **Subdirectories:**
- - `document/` :: Documentation related to testing.
- - `javac/` :: Java-based test sources.
- - `tool/` :: Utilities for testing.
-
-** 4. General Documentation (`Harmony/document/`)
- - Contains overall project documentation.
-
-** 5. Release Directory (`Harmony/release/`)
- - The release candidate directory before finalization.
-
-** 6. Shared Tools (`Harmony/tool_shared/`)
- - Tools shared across different roles.
-
- - **Subdirectories:**
- - `bespoke/` :: Custom-built project tools.
- - `customized/` :: Modified third-party tools.
- - `document/` :: Tool-related documentation.
- - `third_party/` :: Unmodified third-party tools.
-
-** 7. Other Files
- - `LICENSE.txt` :: Project licensing information.
- - `README.md` :: Project introduction.
-
-** 8. Naming Conventions
- - Directory names are chosen based on logical properties.
- - For example, `developer/` contains files *for* the developer.
- - Plural names are generally avoided unless necessary.
- - This system minimizes ambiguity and helps developers understand structure intuitively.
+++ /dev/null
-<!DOCTYPE html>
-<html lang="en">
-<head>
- <meta charset="UTF-8">
- <meta name="viewport" content="width=device-width, initial-scale=1.0">
- <link href="https://fonts.googleapis.com/css2?family=Noto+Sans+JP&display=swap" rel="stylesheet">
- <title>RT C coding conventions</title>
- <style>
- body {
- font-family: 'Noto Sans JP', Arial, sans-serif;
- background-color: hsl(0, 0%, 0%);
- color: hsl(42, 100%, 80%);
- padding: 2rem;
- }
- .page {
- padding: 3rem;
- margin: 1.25rem auto;
- max-width: 46.875rem;
- background-color: hsl(0, 0%, 0%);
- box-shadow: 0 0 0.625rem hsl(42, 100%, 50%);
- }
- h1 {
- font-size: 1.5rem;
- text-align: center;
- color: hsl(42, 100%, 84%);
- text-transform: uppercase;
- margin-top: 1.5rem;
- }
- h2 {
- font-size: 1.25rem;
- color: hsl(42, 100%, 84%);
- text-align: center;
- margin-top: 2rem;
- }
- h3 {
- font-size: 1.125rem;
- color: hsl(42, 100%, 75%);
- margin-top: 1.5rem;
- }
- p, li {
- color: hsl(42, 100%, 90%);
- text-align: justify;
- margin-bottom: 1rem;
- }
- code {
- font-family: 'Courier New', Courier, monospace;
- background-color: hsl(0, 0%, 25%);
- padding: 0.125rem 0.25rem;
- color: hsl(42, 100%, 90%);
- }
- </style>
-</head>
-
-<body>
-<div class="page">
- <header>
- <h1>Reasoning Technology (RT) C file control structure</h1>
- <p>© 2024 Thomas Walker Lynch - All Rights Reserved.</p>
- </header>
-
- <h2>Introduction</h2>
-
- <p>This document summarizes some of the coding conventions used in RT C projects. Discussed here are conventions for integrated header designs, ad hoc namespaces, and a structured approach to source file extensions. The document also outlines the associated build process using a standardized makefile.</p>
-
- <h2>Header file integration</h2>
-
- <p>RT C projects adopt an innovative approach by integrating headers directly into source files. This ensures consistency between interfaces and implementations, eliminating mismatches. Each file contains both an interface and an implementation section, gated by preprocessor directives.</p>
-
- <p>Each RT C source file integrates its header directly into the source file. This locality makes header content easier to maintain as everything is found in a single file. It also eliminates the need to maintain two files for each module.</p>
-
- <h3>Each file has two sections</h3>
- <ul>
- <li><strong>Interface section:</strong> Contains declarations, macros, and <code>#includes</code> needed for the interface. Ensures consistency by defining the interface exactly once, even when the file is included multiple times.</li>
- <li><strong>Implementation section:</strong> Contains function definitions and additional includes needed for the implementation. This section is compiled only when the file is used as an implementation.</li>
- </ul>
-
- <p>Each section is turned on and off with the CPP macro <code>FACE</code>.</p>
-
- <h3>Example</h3>
- <pre><code>
-// If not an FACE, then an IMPLEMENTATION
-#ifndef FACE
- #define MyModule·IMPLEMENTATION
- // Ensures included files are processed for their interfaces.
- #define FACE
-#endif
-
-// Define the interface exactly once.
-#ifndef MyModule·FACE
-#define MyModule·FACE
- // Interface-only includes go here.
- void MyModule·function();
-#endif
-
-#ifdef MyModule·IMPLEMENTATION
- // Additional includes for implementation go here.
- #include <stdio.h>
- void MyModule·function() {
- printf("Hello, World!\n");
- }
-#endif
- </code></pre>
-
- <h3>Explanation</h3>
- <p>The example above demonstrates the structure and purpose of each block:</p>
- <p><strong>First block:</strong> Ensures that the file operates correctly based on the value of <code>FACE</code>. If <code>FACE</code> is undefined, it defines <code>MyModule·IMPLEMENTATION</code> to enable the implementation section and sets <code>FACE</code> to ensure subsequent includes process interface sections.</p>
- <p><strong>Second block:</strong> Defines the interface, including declarations and interface-specific includes. The <code>#ifndef MyModule·FACE</code> macro ensures the interface is defined exactly once, regardless of how many times the file is included.</p>
- <p><strong>Third block:</strong> Contains implementation-specific includes and function definitions. Guarded by <code>MyModule·IMPLEMENTATION</code>, it is only included when compiling the implementation.</p>
- <p>Interface includes are placed in the interface block, ensuring they are available wherever the interface is used. Implementation includes are isolated in the implementation block, minimizing unnecessary dependencies in other files.</p>
-
- <h2>Namespace conventions</h2>
- <p>RT projects use ad hoc namespaces to maintain clarity and prevent naming conflicts. This is achieved by prefixing exported identifiers with a module-specific name followed by the <code>·</code> (cdot) character.</p>
-
- <h3>Conventions</h3>
- <ul>
- <li><strong>Prefix:</strong> The module name serves as the prefix, ensuring all identifiers are unique across the program.</li>
- <li><strong>Separator:</strong> The <code>·</code> character visually separates the prefix from the identifier name, maintaining readability and avoiding conflicts.</li>
- </ul>
-
- <h3>Example</h3>
- <pre><code>
-void Server·run();
- </code></pre>
-
- <h2>Source file extensions</h2>
- <p>RT projects use standardized extensions to distinguish between library and command-line interface (CLI) source files:</p>
- <ul>
- <li><strong><code>.lib.c</code>:</strong> Files implementing library functions.</li>
- <li><strong><code>.cli.c</code>:</strong> Files implementing command-line tools.</li>
- </ul>
-
- <p>The <code>.lib.c</code> files compile into libraries, while <code>.cli.c</code> files compile into standalone executables. The makefile processes these files automatically, ensuring a clear separation of functionality.</p>
-
- <h3>Build process</h3>
- <p>The build process follows these steps:</p>
- <ol>
- <li><strong>Dependency generation:</strong> Run <code>make dependency</code> to create dependencies. This step is only required when the dependency structure changes.</li>
- <li><strong>Compilation:</strong> Run <code>make cli</code> to compile CLI sources and link them against the library. The makefile automatically manages targets and dependencies.</li>
- </ol>
-
- <h2>Benefits</h2>
- <ul>
- <li><strong>Consistency:</strong> Integrated headers ensure interface and implementation are always in sync.</li>
- <li><strong>Modularity:</strong> Each file encapsulates its interface and implementation, reducing coupling.</li>
- <li><strong>Clarity:</strong> Ad hoc namespaces and standardized extensions improve readability and organization.</li>
- <li><strong>Efficiency:</strong> The makefile automates builds, minimizing errors and streamlining development.</li>
- </ul>
-
- <h2>Conclusion</h2>
- <p>This document outlines the conventions and practices for writing and building RT C projects. By integrating headers, adopting namespaces, and standardizing extensions, RT ensures its projects are robust, modular, and easy to maintain.</p>
-</div>
-</body>
-</html>
+++ /dev/null
-#+TITLE: Reasoning Technology (RT) C file control structure
-#+AUTHOR: Thomas Walker Lynch
-#+OPTIONS: toc:2 num:nil
-#+LANGUAGE: en
-
-* Introduction
-This document summarizes coding conventions used in RT C projects: integrated header designs, ad hoc namespaces, and a structured approach to source file extensions. It also outlines the associated build process using a standardized makefile.
-
-* Header file integration
-RT C projects integrate the header directly into the source file. Each file contains both interface and implementation sections, gated by preprocessor directives. This keeps interface and implementation in sync and avoids maintaining two files.
-
-** Each file has two sections
-- *Interface section*: declarations, macros, and =#include= needed for the interface. Defined exactly once even with multiple inclusion.
-- *Implementation section*: function definitions and any additional includes needed for the implementation. Only compiled when used as an implementation.
-
-Each section is toggled by the CPP macro =FACE=.
-
-** Example
-#+BEGIN_SRC c
-// If not an FACE, then an IMPLEMENTATION
-#ifndef FACE
- #define MyModule·IMPLEMENTATION
- // Ensures included files are processed for their interfaces.
- #define FACE
-#endif
-
-// Define the interface exactly once.
-#ifndef MyModule·FACE
-#define MyModule·FACE
- // Interface-only includes go here.
- void MyModule·function();
-#endif
-
-#ifdef MyModule·IMPLEMENTATION
- // Additional includes for implementation go here.
- #include <stdio.h>
- void MyModule·function() {
- printf("Hello, World!\n");
- }
-#endif
-#+END_SRC
-
-** Explanation
-- *First block*: If =FACE= is undefined, define =MyModule·IMPLEMENTATION= and set =FACE= so subsequent includes expose interfaces.
-- *Second block*: Define the interface exactly once via =#ifndef MyModule·FACE=.
-- *Third block*: Implementation-only includes and definitions guarded by =MyModule·IMPLEMENTATION=.
-
-* Namespace conventions
-RT projects use ad hoc namespaces: exported identifiers are prefixed with a module name and the =·= (cdot) separator for clarity and to avoid collisions.
-
-** Conventions
-- *Prefix*: module name.
-- *Separator*: =·= visually separates prefix from identifier.
-
-** Example
-#+BEGIN_SRC c
-void Server·run();
-#+END_SRC
-
-* Source file extensions
-Standardized extensions distinguish library from CLI sources:
-- =.lib.c= :: library implementations
-- =.cli.c= :: command-line tools
-
-=.lib.c= compiles into libraries; =.cli.c= into executables. The makefile auto-detects and builds accordingly.
-
-** Build process
-1. *Dependency generation*: =make dependency= (only when dependency graph changes).
-2. *Compilation*: =make cli= builds CLI targets and links with the library.
-
-* Benefits
-- *Consistency*: integrated headers keep interfaces and implementations aligned.
-- *Modularity*: each file encapsulates interface + implementation.
-- *Clarity*: namespaces + extensions improve readability.
-- *Efficiency*: standardized makefile reduces build friction.
-
-* Conclusion
-Following these conventions yields robust, modular C projects with predictable builds.
+++ /dev/null
-Java has long been criticized for its lack of support for `import as`, despite
-years of requests and proposals.
-
-The Java platform’s approach to aliasing issues relies on using fully qualified
-names, which poses challenges given the length of package names, especially when
-they include reversed domain names.
-
-Because `Harmony` is used to help with testing and is not part of the project
-being tested, when aliasing conflicts arise, it is typically the `Harmony` identifiers
-that need to be fully qualified. Such a renamed identifier can exceed 34
-characters!
-
-One proposal to get around this was to use an `In` class where the members were
-class extensions of imported classes. Then all imports would have the prefix `In.`.
-However, this did not work out because constructors are not
-inherited, and Java’s restrictions on `final` classes prevent the use of
-`LocalClass extends ImportClass {}` to give no names to classes.
-
-Another proposal was to use the `alias` project on GitHub, which offers an XML-based
-approach to aliasing. However, it introduces complexities, as it requires XML
-configurations to be supplied to the compiler, adding setup overhead. Perhaps
-another tool could create these.
-
-We studied a preprocessing proposal where `import as` statements would be
-replaced with fully qualified names before compilation. However, this approach
-changes the tool flow for users and would require additional steps to ensure
-`jdb` points to the original source files rather than intermediate files, which
-complicates debugging. For both this proposal and the prior, we wanted to avoid
-joining the world of java tool development.
-
-So we have a simple solution, it is not ideal, but it is not bad. We prefix
-the string `Mosaic_` to the front of all the class names in the Harmony library.
-As a shop we are adopting this convention for all packaged java code.
+++ /dev/null
-
-This document describes how to run jdb in the test environment while also viewing source code.
-
-This is written relative to the Harmony project, but is generally applicable.
-
-It shows invocation from a shell, and mentions emacs, but it is generally
-understood that users will do this from within their favorite IDE.
-
-In addition a reader can read this document for some general principles.
-
-1. setting the environment
-
- The environment should be set before running the IDE. For example,
-
- > cd Harmony
- > source env_tester
- > emacs &
-
- (I use emacs as my IDE. You might be using a different tool.)
-
-2. location of the executable
-
- Provided that the project administrator installed it, jdb is located in the
- third_party tools directory. In the tester environment the variable
- `JAVA_HOME` should hold the jdb directory path, and this should already
- be in the `PATH`. For example:
-
- > echo $ENV
- tester/tool/env
-
- > echo $JAVA_HOME
- /var/user_data/Thomas-developer/Harmony/tool_shared/third_party/jdk-11
-
- > which jdb
- /var/user_data/Thomas-developer/Harmony/tool_shared/third_party/jdk-11/bin/jdb
-
-3. invocation from a shell command:
-
- jdb -sourcepath $SOURCEPATH <class_name>
-
- The `SOURCEPATH` is assigned a value in `tester/tool/env`. In some versions
- of jdb there is no space between `-sourcepath` and the `$SOURCDEPATH`.
-
- jdb will read CLASSPATH from the environment. In contrast jdb will not read
- `SOURCEPATH` from the environment. It must be passed as an argument.
-
- There is a `run_jdb` script in the `tool` directory.
-
-4. invocation inside of Emacs
-
- The file found in the RT-incommon project, developer/release/emacs/jdbx.el` holds a
- definition for the `jdbx` command. This command will read the SOURCEPATH
- from the environment and run jdb in Emacs.
-
- That file also holds the definition for a listener to the jdb `sourcepath`
- command.
-
-
-
-
-
-
+++ /dev/null
-
-Bash is inconsistent about returning the name of the running script in
-all scenarios (sourced, executed directly, from with in a function called
-by another function).
-
-1.
-
-BASH_SOURCE[0] was used because $0 did not work with sourced scripts (a
-fact that is leveraged for detecting when in a sourced script).
-
-2.
-
-However, this did not work in all scenarios:
-
- read -r -d '' script_afp_string <<'EOF'
- realpath "${BASH_SOURCE[0]}" 2>/dev/null
- EOF
-
- script_afp(){
- eval "$script_afp_string"
- }
-
- export script_afp_string
- export -f script_afp
-
-When `script_afp` was exported, used in another file, and used within a function
-in that other file, it reported `environment` for the script name at
-BASH_SOURCE[0]. In various call scenarios the actual script name appears at
-BASH_SOURCE[1] or even at BASH_SOURCE[2].
-
-3.
-
-As a stable alternative to having a script_afp function, place this line
-at the top of scripts that use the `script_XX` functions, or at the top
-of all scripts:
-
- script_afp=realpath "${BASH_SOURCE[0]}"
-
-Then use $script_afp as a string within other functions. It will have stable
-value no matter the call structure.
+++ /dev/null
-<!DOCTYPE html>
-<html lang="en">
-<head>
- <meta charset="UTF-8">
- <meta name="viewport" content="width=device-width, initial-scale=1.0">
- <link href="https://fonts.googleapis.com/css2?family=Noto+Sans+JP&display=swap" rel="stylesheet">
-
- <title>Directory Structure Description</title>
-<style>
- html {
- font-size: 16px; /* This will be the base for rem units */
- }
-
- body {
- font-family: 'Noto Sans JP', Arial, sans-serif;
- background-color: hsl(0, 0%, 0%);
- color: hsl(42, 100%, 80%);
- padding: 2rem;
- margin: 0;
- }
-
- .page {
- padding: 1.25rem; /* 20px */
- margin: 1.25rem auto; /* 20px */
- max-width: 46.875rem; /* 750px */
- background-color: hsl(0, 0%, 0%);
- box-shadow: 0 0 0.625rem hsl(42, 100%, 50%); /* 10px */
- }
-
- ul, li {
- font-size: 1rem; /* Keeping default font size */
- list-style-type: none;
- }
-
- li::before {
- content: "📁 ";
- margin-right: 0.3125rem; /* 5px */
- }
-
- li {
- margin-bottom: 0.3125rem; /* 5px */
- }
-
- .description {
- margin-left: 0.625rem; /* 10px */
- color: hsl(42, 100%, 75%);
- }
-
- code {
- font-family: 'Courier New', Courier, monospace;
- background-color: hsl(0, 0%, 25%);
- color: hsl(42, 100%, 90%);
- padding: 0.125rem 0.25rem; /* 2px 4px */
- border-radius: 0.1875rem; /* 3px */
- font-size: 90%;
- }
-
- h1 {
- text-align: center;
- color: hsl(42, 100%, 84%);
- text-transform: uppercase;
- margin-bottom: 1.25rem; /* 20px */
- }
-
- h2 {
- color: hsl(42, 100%, 84%);
- text-transform: uppercase;
- margin-top: 2.5rem; /* 40px */
- }
-
- p {
- color: hsl(42, 100%, 90%);
- margin-bottom: 1.25rem; /* 20px */
- text-align: justify;
- }
-</style>
-
-</head>
-<body>
-
- <div class="page">
- <h1>Directory Naming</h1>
-
- <h2>Reference</h2>
-
- <ul>
- <li>Harmony/<span class="description">aka REPO_HOME, top level owned by the project administrator.</span></li>
- <ul>
- <li>developer/ <span class="description">Workspace for the developer. Has the source code, build scripts, and development-specific tools.</span></li>
- <ul>
- <li>deprecated/ <span class="description">Files and older versions being viewed, perhaps part of a refactoring effort.</span></li>
- <li>document/ <span class="description">Documentation on developing and building the project.</span></li>
- <li>javac/ <span class="description">Java source files for compilation.</span></li>
- <li>jvm/ <span class="description">Compiled Java bytecode files for the project, typically a jar for a Java project.</span></li>
- <li>scratchpad/ <span class="description">Temporary storage typically for intermediate files created during build.</span></li>
- <li>shell/ <span class="description">Shell scripts intended to be part of the project release. (These are not tools.)</span></li>
- <li>tool/ <span class="description">Tools created by the developer, used for development tasks.</span></li>
- </ul>
- <li>document/ <span class="description">General documentation about the project.</span></li>
- <li>release/ <span class="description">Release candidate for testing. Becomes the release on the release branch.</span></li>
- <li>scratchpad/ <span class="description">Temporary storage for project administration tasks.</span></li>
- <li>tester/ <span class="description">Workspace for the tester. Has the test bench, tests, and test scripts.</span></li>
- <ul>
- <li>document/ <span class="description">Test-specific documentation.</span></li>
- <li>javac/ <span class="description">The tests of the test bench sources.</span></li>
- <li>tool/ <span class="description">Tools needed for testing and managing the test environment.</span></li>
- </ul>
- <li>tool/ <span class="description">Project administration specific tools.</span></li>
- <li>tool_shared/ <span class="description">Tools shared across project roles.</span></li>
- <ul>
- <li>bespoke/ <span class="description">Shared tools developed within this project.</span></li>
- <li>customized/ <span class="description">Modified versions of third-party tools adapted for the project.</span></li>
- <li>document/ <span class="description">Documentation related to shared tools and setup.</span></li>
- <li>third_party/ <span class="description">Shared tools sourced from third-party vendors or open-source projects. These have their own independent licenses,</span></li>
- </ul>
- <li>LICENSE.txt <span class="description">The project license detailing usage and distribution terms.</span></li>
- <li>README.md <span class="description">A general overview and introduction to the project.</span></li>
- </ul>
- </ul>
-
- <h2>Name origin and rationale</h2>
-
- <p>Developers and project administrators typically do not employ a semantic system for
- naming directories, but more commonly use conventional placeholder
- names. The intended purpose of files in a directory with a placeholder
- name then must be inferred from experience or inspection of the files, or
- learned from documents or other people.</p>
-
- <p>For example, a directory named <code>exe/</code> probably derives its name from the
- fact that the contained files have their executable permission bit set;
- however, such a directory will not contain all such files. There might
- even be some files in an <code>exe/</code> directory that do not have their
- executable permission bit set. The two concepts being an <code>exe/</code> file
- (i.e. being a file in an <code>exe/</code> directory) and being an executable file
- are not identical. The actual intended meaning of being an <code>exe/</code> file
- will sometimes be that the contained files are applications available to a
- user, or that they are tools available for use in a project.
- </p>
-
- <p>The directory names in this project resulted from an exploration of a
- property-based file system. In such a system a number of files and
- agents are defined. Then we can ask questions about their relationships.
- Files with a relationship to the developer are collected, and this
- becomes the <code>developer/</code> directory. In a similar manner we get the
- directories, <code>tester/</code>, and <code>javac/</code>. In this latter case the
- agent is a compiler rather than a role.
- </p>
-
- <p>When attempting to apply the <code>is-for</code> property in practice it
- became apparent that using this sole property was insufficient. Consider
- the directories <code>deprecated/</code> and <code>scratchpad/</code>. There is no
- <em>Mr. Deprecated</em> or <em>Mr. Scratchpad</em> who the contained
- files are for. (And this conclusion is not for the lack of trying. Even
- mythological beings did not suffice as agents.) Rather than being for an
- agent, the files collected in such a directory have in common a state of
- being that was imposed upon them by decree. Perhaps the developer, has
- decreed that a file is now deprecated, or a build script has decreed that
- it is a scratchpad file. Such decrees are typically more dynamic than the
- relationship properties. Also, these properties are disconnected from the
- contents of the file. When, for example, a file has the property of being
- for the java compiler, we gain some information about its contents. In the
- universe of possible messages sent through a file, such a file will
- contain text that is proposed to be java syntax conforming. In contrast,
- when we learn that a file is <code>deprecated/</code> we gain no
- information about the contents of the file, because any file can
- be <code>deprecated</code>, independent of its contents.
- </p>
-
- <p>To understand a directory name within this system, one can imagine
- reading said name as part of a sentence that integrates the
- property. Consider two property names: <code>is-a</code>
- and <code>is-for</code>. For example, "Each file in
- the <code>document/</code> directory <code>is-a</code> document," or "Each
- file in the <code>developer/</code> directory <code>is-for</code> the
- developer." Although the property name is not carried over from the
- property based file system to the conventional file system, we can
- typically infer what it must have been. (It is beyond the scope of
- discussion here, but in actuality, property based file system collections
- are defined by predicates. Each predicate is given a file's properties and
- relationships as arguments, then resolves to true if and only if the file
- belongs to the collection. Now wouldn't that be interesting if we instead
- derived a probability?)
- </p>
-
- <p>It is uncommon for a property value to be plural. While it is not
- disallowed, it rarely occurs in practice. This is true independent of
- whether we are discussing a relationship property or a state
- property. Hence when we make a file collection based on a shared property,
- then carry that over as a directory name in a conventional file system,
- the resulting directory name will often be singular. This pattern can be
- observed in the case of the <code>document/</code> directory, as shown in
- the prior paragraph.
- </p>
-
- </div>
-
-</body>
-</html>
+++ /dev/null
-# Suffix Conventions
-
-## Specify interface used with variable when clarification is useful
-
-- `_set`: Indicates that the variable holds a set of items.
-
-- `_list`: Used for variables that represent a list of items.
-
-- `_f`: Refers to a function.
-
-Instead of making a variable name plural, add the interface qualifier.
-
- e.g. names -> name_set or name_lisst
-
-## Always a good idea to use these when working with files
-
-- `_fp`: Refers to a file path. The part after the last slash is a file name.
-
-- `_afp`: Refers to an absolute file path.
-
-- `_dp`: Refers to a directory path. By convention, the value ends in a slash.
-
-- `_adp`: Refers to an absolute directory path.
-
-- `_fn`: Refers to a file name. Value has no slashes.
-
-- `_dn`: Refers to a directory name. Value has no slashes.
-
-- `_fn_base`: The file name without the last dot and subsequent characters.
-
-- `_fn_ext`: The subsequent characters after the last dot in a file name.
+++ /dev/null
-See 'workflow.org'
+++ /dev/null
-Apache License
-Version 2.0, January 2004
-http://www.apache.org/licenses/
-
-TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
-
-1. Definitions.
-
-"License" shall mean the terms and conditions for use, reproduction, and
-distribution as defined by Sections 1 through 9 of this document.
-
-"Licensor" shall mean the copyright owner or entity authorized by the copyright
-owner that is granting the License.
-
-"Legal Entity" shall mean the union of the acting entity and all other entities
-that control, are controlled by, or are under common control with that
-entity. For the purposes of this definition, "control" means (i) the power,
-direct or indirect, to cause the direction or management of such entity, whether
-by contract or otherwise, or (ii) ownership of fifty percent (50%) or more of
-the outstanding shares, or (iii) beneficial ownership of such entity.
-
-"You" (or "Your") shall mean an individual or Legal Entity exercising
-permissions granted by this License.
-
-"Source" form shall mean the preferred form for making modifications, including
-but not limited to software source code, documentation source, and configuration
-files.
-
-"Object" form shall mean any form resulting from mechanical transformation or
-translation of a Source form, including but not limited to compiled object code,
-generated documentation, and conversions to other media types.
-
-"Work" shall mean the work of authorship, whether in Source or Object form, made
-available under the License, as indicated by a copyright notice that is included
-in or attached to the work (an example is provided in the Appendix below).
-
-"Derivative Works" shall mean any work, whether in Source or Object form, that
-is based on (or derived from) the Work and for which the editorial revisions,
-annotations, elaborations, or other modifications represent, as a whole, an
-original work of authorship. For the purposes of this License, Derivative Works
-shall not include works that remain separable from, or merely link (or bind by
-name) to the interfaces of, the Work and Derivative Works thereof.
-
-"Contribution" shall mean any work of authorship, including the original version
-of the Work and any modifications or additions to that Work or Derivative Works
-thereof, that is intentionally submitted to Licensor for inclusion in the Work
-by the copyright owner or by an individual or Legal Entity authorized to submit
-on behalf of the copyright owner. For the purposes of this definition,
-"submitted" means any form of electronic, verbal, or written communication sent
-to the Licensor or its representatives, including but not limited to
-communication on electronic mailing lists, source code control systems, and
-issue tracking systems that are managed by, or on behalf of, the Licensor for
-the purpose of discussing and improving the Work, but excluding communication
-that is conspicuously marked or otherwise designated in writing by the copyright
-owner as "Not a Contribution."
-
-"Contributor" shall mean Licensor and any individual or Legal Entity on behalf
-of whom a Contribution has been received by Licensor and subsequently
-incorporated within the Work.
-
-2. Grant of Copyright License. Subject to the terms and conditions of this
-License, each Contributor hereby grants to You a perpetual, worldwide,
-non-exclusive, no-charge, royalty-free, irrevocable copyright license to
-reproduce, prepare Derivative Works of, publicly display, publicly perform,
-sublicense, and distribute the Work and such Derivative Works in Source or
-Object form.
-
-3. Grant of Patent License. Subject to the terms and conditions of this License,
-each Contributor hereby grants to You a perpetual, worldwide, non-exclusive,
-no-charge, royalty-free, irrevocable (except as stated in this section) patent
-license to make, have made, use, offer to sell, sell, import, and otherwise
-transfer the Work, where such license applies only to those patent claims
-licensable by such Contributor that are necessarily infringed by their
-Contribution(s) alone or by combination of their Contribution(s) with the Work
-to which such Contribution(s) was submitted. If You institute patent litigation
-against any entity (including a cross-claim or counterclaim in a lawsuit)
-alleging that the Work or a Contribution incorporated within the Work
-constitutes direct or contributory patent infringement, then any patent licenses
-granted to You under this License for that Work shall terminate as of the date
-such litigation is filed.
-
-4. Redistribution. You may reproduce and distribute copies of the Work or
-Derivative Works thereof in any medium, with or without modifications, and in
-Source or Object form, provided that You meet the following conditions:
-
-You must give any other recipients of the Work or Derivative Works a copy of
-this License; and You must cause any modified files to carry prominent notices
-stating that You changed the files; and You must retain, in the Source form of
-any Derivative Works that You distribute, all copyright, patent, trademark, and
-attribution notices from the Source form of the Work, excluding those notices
-that do not pertain to any part of the Derivative Works; and If the Work
-includes a "NOTICE" text file as part of its distribution, then any Derivative
-Works that You distribute must include a readable copy of the attribution
-notices contained within such NOTICE file, excluding those notices that do not
-pertain to any part of the Derivative Works, in at least one of the following
-places: within a NOTICE text file distributed as part of the Derivative Works;
-within the Source form or documentation, if provided along with the Derivative
-Works; or, within a display generated by the Derivative Works, if and wherever
-such third-party notices normally appear. The contents of the NOTICE file are
-for informational purposes only and do not modify the License. You may add Your
-own attribution notices within Derivative Works that You distribute, alongside
-or as an addendum to the NOTICE text from the Work, provided that such
-additional attribution notices cannot be construed as modifying the License.
-You may add Your own copyright statement to Your modifications and may provide
-additional or different license terms and conditions for use, reproduction, or
-distribution of Your modifications, or for any such Derivative Works as a whole,
-provided Your use, reproduction, and distribution of the Work otherwise complies
-with the conditions stated in this License.
-
-5. Submission of Contributions. Unless You explicitly state otherwise, any
-Contribution intentionally submitted for inclusion in the Work by You to the
-Licensor shall be under the terms and conditions of this License, without any
-additional terms or conditions. Notwithstanding the above, nothing herein shall
-supersede or modify the terms of any separate license agreement you may have
-executed with Licensor regarding such Contributions.
-
-6. Trademarks. This License does not grant permission to use the trade names,
-trademarks, service marks, or product names of the Licensor, except as required
-for reasonable and customary use in describing the origin of the Work and
-reproducing the content of the NOTICE file.
-
-7. Disclaimer of Warranty. Unless required by applicable law or agreed to in
-writing, Licensor provides the Work (and each Contributor provides its
-Contributions) on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
-KIND, either express or implied, including, without limitation, any warranties
-or conditions of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
-PARTICULAR PURPOSE. You are solely responsible for determining the
-appropriateness of using or redistributing the Work and assume any risks
-associated with Your exercise of permissions under this License.
-
-8. Limitation of Liability. In no event and under no legal theory, whether in
-tort (including negligence), contract, or otherwise, unless required by
-applicable law (such as deliberate and grossly negligent acts) or agreed to in
-writing, shall any Contributor be liable to You for damages, including any
-direct, indirect, special, incidental, or consequential damages of any character
-arising as a result of this License or out of the use or inability to use the
-Work (including but not limited to damages for loss of goodwill, work stoppage,
-computer failure or malfunction, or any and all other commercial damages or
-losses), even if such Contributor has been advised of the possibility of such
-damages.
-
-9. Accepting Warranty or Additional Liability. While redistributing the Work or
-Derivative Works thereof, You may choose to offer, and charge a fee for,
-acceptance of support, warranty, indemnity, or other liability obligations
-and/or rights consistent with this License. However, in accepting such
-obligations, You may act only on Your own behalf and on Your sole
-responsibility, not on behalf of any other Contributor, and only if You agree to
-indemnify, defend, and hold each Contributor harmless for any liability incurred
-by, or claims asserted against, such Contributor by reason of your accepting any
-such warranty or additional liability.
-
-END OF TERMS AND CONDITIONS
+++ /dev/null
-SPDX-License-Identifier: LicenseRef-TWL-Confidential
-Title: Confidential — Restricted Access (Personal)
-
-CONFIDENTIAL INFORMATION. The contents of this repository and all associated
-materials ("Confidential Information") are proprietary to Thomas Walker Lynch.
-If you are not an intended recipient, you must cease access, delete all copies,
-and notify the author immediately.
-
-No license is granted by this notice. Unless you have a separate written
-agreement (e.g., NDA or license) with the author, you may not use, copy,
-modify, disclose, distribute, publish, host, provide access to, or reverse
-engineer any part of the Confidential Information.
-
-Permitted Internal Review. If you are an intended recipient, you may review
-the materials solely for internal evaluation and solely within the scope
-authorized by the author.
-
-Return/Destruction. Upon request, you must promptly return or destroy all
-copies and certify destruction.
-
-Trademarks. No rights to names, logos, or marks are granted.
-
-Warranty/Liability. PROVIDED "AS IS", WITHOUT WARRANTY. TO THE MAXIMUM
-EXTENT PERMITTED BY LAW, THE AUTHOR SHALL NOT BE LIABLE FOR ANY DAMAGES.
-
+++ /dev/null
-SPDX-License-Identifier: LicenseRef-RT-Confidential
-Title: Confidential — Restricted Access (RT)
-
-CONFIDENTIAL INFORMATION. The contents of this repository and associated
-materials ("Confidential Information") are proprietary to Reasoning Technology Inc..
-If you are not an intended recipient, you must cease access, delete all
-copies, and notify Reasoning Technology Inc. immediately.
-
-No license is granted by this notice. Unless you have a separate written
-agreement with Reasoning Technology Inc. (e.g., NDA or license), you may not use, copy,
-modify, disclose, distribute, publish, host, provide access to, or reverse
-engineer any part of the Confidential Information.
-
-Permitted Internal Review. Intended recipients may review the materials
-solely for internal evaluation and only as expressly authorized by
-Reasoning Technology Inc..
-
-Return/Destruction. Upon request, promptly return or destroy all copies and
-certify destruction.
-
-Trademarks. No rights to names, logos, or marks are granted.
-
-Warranty/Liability. PROVIDED "AS IS", WITHOUT WARRANTY. TO THE MAXIMUM
-EXTENT PERMITTED BY LAW, Reasoning Technology Inc. AND AUTHORS ARE NOT LIABLE FOR DAMAGES.
-
-Contact. For authorization or licensing, email licensing@ReasoningTechnology.com.
+++ /dev/null
-Copyright (c) 2025 Thomas Walker Lynch.
-
-All rights reserved.
-
-This source code is made available for inspection only.
-
-No permission is granted to use, copy, modify, or distribute it in any form without explicit written permission.
+++ /dev/null
-MIT License
-
-Copyright (c) 2019, 2024 Reasoning Technology
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
+++ /dev/null
-SPDX-License-Identifier: LicenseRef-TWL-NoUse-ARR
-Title: All Rights Reserved — No License Granted (Personal)
-
-Copyright (c) 2025 Thomas Walker Lynch. All rights reserved.
-
-No license is granted by this notice. Except pursuant to a separate written
-agreement signed by the copyright holder, you may not use, copy, modify,
-merge, publish, distribute, sublicense, sell, host, or deploy this software
-("Software"), in whole or in part, in source or binary form.
-
-Limited Viewing Permission. If you received this repository directly from the
-author, you may view the files solely to evaluate whether to request a license.
-No other rights are granted.
-
-Trademarks. No rights to names, logos, or marks are granted.
-
-Warranty Disclaimer. THE SOFTWARE IS PROVIDED "AS IS" WITHOUT WARRANTY OF ANY
-KIND, EXPRESS OR IMPLIED.
-
-Liability. TO THE MAXIMUM EXTENT PERMITTED BY LAW, THE AUTHOR SHALL NOT BE
-LIABLE FOR ANY DAMAGES ARISING FROM USE OR ACCESS.
-
-Contact. For licensing, contact the author.
-
+++ /dev/null
-SPDX-License-Identifier: LicenseRef-RT-NoUse-ARR
-Title: All Rights Reserved — No License Granted (RT)
-
-Copyright (c) 2025 Reasoning Technology Inc.. All rights reserved.
-
-No license is granted by this notice. Except under a separate written agreement executed by Reasoning Technology Inc., you may not use, copy, modify, merge, publish, distribute, sublicense, sell, host, or deploy this software ("Software"), in whole or in part, in source or binary form.
-
-Limited Viewing Permission. If you received this repository directly from Reasoning Technology Inc., you may view the files solely to evaluate whether to obtain a license. No other rights are granted.
-
-Trademarks. No rights to names, logos, or marks are granted.
-
-Warranty Disclaimer. THE SOFTWARE IS PROVIDED "AS IS" WITHOUT WARRANTY OF ANY
-KIND, EXPRESS OR IMPLIED.
-
-Liability. TO THE MAXIMUM EXTENT PERMITTED BY LAW, Reasoning Technology Inc. SHALL NOT BE
-LIABLE FOR ANY DAMAGES ARISING FROM USE OR ACCESS.
-
-Contact. For licensing, email licensing@ReasoningTechnology.com.
+++ /dev/null
-LicenseRef-TWL-Personal-NC (Personal Non-Commercial License)
-
-Copyright (c) 2025 Thomas Walker Lynch
-
-Permission is hereby granted to any natural person ("You") to use, copy, and
-modify the Software for personal, non-commercial purposes, subject to the
-following conditions:
-
-1. Non-Commercial Use. "Non-commercial" means: no direct or indirect
- remuneration, revenue, sponsorship, or consideration is received in
- connection with Your use, copies, modifications, or deployments of the
- Software. Academic teaching and personal research are deemed non-commercial.
-
-2. Redistribution. You may redistribute unmodified copies of the Software, or
- Your modifications, for non-commercial purposes only, provided that:
- (a) this license text and the copyright notice are included in all copies;
- (b) a clear notice of any changes is included; and
- (c) You do not misrepresent authorship or sponsorship.
-
-3. No SaaS or Production Hosting. Operating the Software as a network service
- accessible by others (hosted or SaaS) is deemed commercial unless you have
- obtained written permission from the copyright holder.
-
-4. No Trademark License. This license does not grant rights to use names,
- logos, or trademarks of the authors or Reasoning Technology Inc.
-
-5. Termination. Any breach terminates Your rights under this license
- automatically. Upon termination, You must cease use and distribution.
-
-6. Warranty Disclaimer. THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF
- ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
- MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, AND NON-INFRINGEMENT.
-
-7. Limitation of Liability. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
- HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES, OR OTHER LIABILITY, WHETHER IN AN
- ACTION OF CONTRACT, TORT, OR OTHERWISE, ARISING FROM, OUT OF, OR IN
- CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
-
-8. Compatibility. This license is not OSI-approved and may be incompatible
- with certain open-source distribution requirements. If in doubt, use MIT
- or Apache-2.0 instead, or contact the author for a different grant.
-
-SPDX-Identifier: LicenseRef-TWL-Personal-NC
+++ /dev/null
-LicenseRef-RT-Commercial (Reasoning Technology Commercial License)
-
-Copyright (c) 2025 Reasoning Technology Inc.
-
-Subject to a valid commercial agreement with Reasoning Technology Inc.
-("RT"), RT grants the licensee identified in that agreement ("Licensee")
-a worldwide, non-exclusive license to:
-
- (a) use, reproduce, modify, and create derivative works of the Software;
- (b) make internal deployments of the Software and derivative works; and
- (c) redistribute the Software and derivative works in object or source form
- as permitted by the executed commercial agreement.
-
-Restrictions. Except as expressly permitted in the executed agreement,
-Licensee may not sublicense, resell, or offer the Software as a service to
-third parties, and may not remove or alter copyright, license, or NOTICE
-statements.
-
-Support, updates, warranty, and indemnities (if any) are governed solely by
-the executed commercial agreement. Absent such agreement, no rights are
-granted under this license.
-
-NO WARRANTY. THE SOFTWARE IS PROVIDED "AS IS" WITHOUT WARRANTY OF ANY KIND,
-EXCEPT AS MAY BE EXPRESSLY STATED IN THE EXECUTED COMMERCIAL AGREEMENT.
-
-LIMITATION OF LIABILITY. TO THE MAXIMUM EXTENT PERMITTED BY LAW, IN NO EVENT
-SHALL RT OR THE AUTHORS BE LIABLE FOR ANY CLAIMS OR DAMAGES, EXCEPT AS MAY BE
-EXPRESSLY PROVIDED IN THE EXECUTED COMMERCIAL AGREEMENT.
-
-For commercial licensing, contact: licensing@ReasoningTechnology.com
-SPDX-Identifier: LicenseRef-RT-Commercial
+++ /dev/null
-# Empty Directory Sentinels
-
-- We use `.githolder` to keep potentially empty dirs in Git.
-- `.githolder` is marked `export-ignore` in `.gitattributes` so it won’t appear in release archives.
+++ /dev/null
-# Python Environment (RT Policy)
-
-- We do **not** commit virtual environments.
-- Create the venv at `tool_shared/third_party/python/` (called 'python' rather than 'venv'), and set a path to it
-either in the env_<role> scripts (such as env_developer), or in the bespoke/env script if it is shared by all.
-
-
-
-
+++ /dev/null
-# This is a document, not a script
-# There are more docs on IDEs, directory structure, etc.
-# Note especially the workflow document.
-
-#1. In a login shell
-
- # enter the project environment as a developer
- > cd Rabbit
- > . env_developer
-
- # run your IDE
- > emacs
-
-# 2. inside of an emacs shell, or IDE build scrit
-
- # do you edits
- # run local test experiments
-
- > make all
- > make release
-
-
- # 3. In env_tester run more thorough test suite. When satisfied make a release branch and tag it.
- # Release branches have consecutive major release numbers.
-
-
+++ /dev/null
-
-The project is originally configured to be used with Emacs as an IDE. The tools
-can all be run from a shell inside of emacs. Even when using an IDE what the
-shell environment scripts and tools do should be understood.
-
-I have added a working IntelliJ IDEA configuration, so if you want a modern IDE
-it is probably best to go with this. See ItelliJ_IDEA.txt in this directory.
-
-I've not run Eclipse on the project, if you do, perhaps you can update the notes
-here. These things will probably increase your odds of making it work:
- 1. open a shell
- 2. cd to Ariadne, and source the env_developer
- 3. run the tool 'distribute_source'
- 3. run eclipse from the command line
- 4. give eclipse the 'scratchpad' directory as its source
-
-Be sure to run `release` after development to update what the tester sees.
-
-Do the analogous steps if you contribute as a 'tester'. I.e. from
-the shell source env_tester instead. Also, you will need to add
-distribute_source to tester/tool, as it is currently not there.
-
+++ /dev/null
-
-System requirements:
-
-dnf install libX11-devel libXpm-devel libjpeg-devel libpng-devel libtiff-devel
-dnf install gtk3-devel giflib-devel gnutls-devel
-dnf install ncurses-devel texinfo
-dnf install libacl-devel libattr-devel libgccjit libgccjit-devel
-
-# install and build script:
-
-cd "$REPO_HOME"/tool_shared/third_party
-mkdir -p emacs/{src,build,bin}
-
-# We sought stability, and now this. What can I say? It has 'visual-wrap-prefix-mode'.
-pushd upstream
-curl -L -O https://alpha.gnu.org/gnu/emacs/pretest/emacs-30.0.92.tar.xz
-popd
-
-tar -xf upstream/emacs-30.0.92.tar.xz -C emacs/src --strip-components=1
-
-# need to clear the environment
-env -i bash
-
-pushd emacs/src
-./configure --prefix="$REPO_HOME"/tool_shared/third_party/emacs
-
- I gather this warning is unavaoidable?
- "configure: WARNING: Your version of Gtk+ will have problems with"
-
-
-# replace nproc with number of processors:
-make -j$(nproc)
-
-# make install installs locally due to the `--prefix` option `./configure` above
-make install
-make clean
-
-popd
-rm -r emacs/{src,build}
-
-# Find emacs in the emacs/in directory. Be sure to add it to the path
-# in the tool_shared/bespoke/env file:
-# PATH="$REPO_HOME/tool_shared/third_party/emacs/bin:$PATH"
-
-
+++ /dev/null
-
-This file describes the local install and configuration of IntelliJ_IDEA for
-the project with the RT project skeleton.
-
-Project development has been done with ItelliJ and with Emacs. Perhaps
-someone will add more about Eclipse to the install_Eclipse.txt page.
-
---------------------------------------------------------------------------------
-Some notes
-
-'project directory' - the directory with the .git file in it. Called
-$REPO_HOME in RT scripts. Called $PROJECT_DIR$ in IntelliJ file paths.
-
-'module directory' - for RT projects examples include
-`~/Ariadne/developer' `~/Ariadne/tester`. These are independent build
-environments.
-
-IntelliJ automatic scanning:
-
- When selecting `new project` or `new module` the fist time IntelliJ will
- go off and scan directories.
-
- My advice, ** uncheck anything it scans ** then hit next. If you
- don't hit next, the `new project` or `new module won't be made.
-
-IntelliJ paths on forms:
-
- I tried using $PROJECT_DIR$ as a variable standing for the project
- directory, as this was suggested by an AI. However IntelliJ simply
- made a directory with the literal variable name. Recommendation:
- don't use it.
-
- Also tried using $REPO_HOME, as that was defined in the environment
- IntelliJ was run from. Nope, the environment that idea was invoked
- from seems to be thrown away.
-
- `~` for the home directories does work. There is one blessing.
-
- When a file or directory path has a blank on a form, there will be a
- file navigator icon at the far right in the blank. It does not show
- when the form is not scrolled all the way to the right. The browser
- tool starts from either `/home` or at `/` (the root of the file
- sytem) rather than at the top of the project.
- It inserts absolute path names.
-
- It seems everything is based on absolute paths, so it will be
- interesting to see what happens when people download a repo
- with `.imp` files in it ...
-
-A GUI bug:
-
- There is a Gnome Linux bug where the drop down menu can stay on top no matter
- what other window, application, or what virtual desktop a person is on. You
- must go back to the IDEA application window and hit <escape> to make it go
- away.
-
-The [OK] button at the bottom of dialogs:
-
- This closes the dialog.
-
- To apply changes hit [Apply].
-
- [OK] will not save what is on the dialog if [Apply] would fail, but
- it still closes it.
-
---------------------------------------------------------------------------------
-To install ItelliJ
-
- Download the tar file from
- `https://www.jetbrains.com/idea/download/?section=linux`
- into the
- `$REPO_HOME/tool_shared/third_party/upstream`
- directory.
-
- Expand it into
- `$REPO_HOME/tool_shared/third_party`
-
- cd into the expanded directory, into `bin`, then `chmod u+x` and run `idea_inst`.
-
- set the env path to include
- `$REPO_HOME/tool_shared/third_party/idea-IC*/bin`
-
- The executable is called `idea`.
-
- Consider setting a desktop short cut. Consider instead installing it in your
- own bin directory. Easily done, just move the directory created by the tar
- file expansion there.
-
- I prefer a user mode install, as there is no reason this tool should need
- admin privileges.
-
---------------------------------------------------------------------------------
-Startup
-
- ./tool_shared/third_party/idea-IC-243.21565.193/bin/idea &
-
- Shows: Welcome screen
- select "Open" as Ariadne already exists
-
- Shows: Open File or Project Browser
- In top dialog box put full path to project directory.
-
- Hit [OK] at the bottom. Unlikely, but might be scrolled off the bottom of the screen.
-
- Shows: main window
- Appears after hitting OK from the "Open File or Project" [ok].
-
- Has a tool bar at the top. There is a double meat hamburger menu icon
- at the left. Hitting this will replace the top bar with a vertical
- menu for drop down menus.
-
- Careful, after the hamburger icon is pressed, the first drop down
- menu instantly appears. Slide over to get the other drop downs.
- Don't click, slide!
-
- Under tool bar:
- Far left is an icon bar. Then a file browser. And then a big box
- describing hot keys.
-
---------------------------------------------------------------------------------
-Configuration
-
-If you cloned the Ariadne project, the modules will already be configured, and
-also probably some of the run configuration will already be configured.
-
-If you add a project, or modules, know that is possible to go back and
-change settings, except perhaps for the Project directory, I've not tried
-that yet.
-
-It will on occasion add directories. I have multiple language setup with
-source in javac. Though the directory 'src' is not in the configuration,
-IntelliJ like to create it then refuse to delete it, so after configuring I
-then go back and delete it with `rmdir`. Sometimes it shows in the file
-browser though it is not there.
-
- -------------
- Setup Project
- Hamburger icon > File dop-down > Project Structure > Project
-
- select project SDK from disk:
- ~/Ariadne/tool_shared/third_party/jdk-11
-
- -------------
- Setup Modules
-
- Hamburger icon > File dop-down > Project Structure > Modules
-
- Shows: "Project Structure" dialog
-
- Hit the '+' option that shows at the top of the second panel. There is
- no description of what it does. Mouse over just says 'add'. It is
- there with a couple of other icons. After modules are added they will
- be listed in this panel.
-
- New Module.
-
- Dialog pop-up
-
- Name: developer
-
- Location: This will be the project directory. As examples,
- ~/Ariadne or ~/Harmony.
-
- Dependencies, there will then be a drop down.
-
- Sometimes is suggests the "Project SDK" at the top. If so select that.
-
- Sometimes it allows select from disk, is so enter ~/<project>/tool_shared/third_party/.
-
- Other times it shows a discovered directory that is the same as
- the one I suggest browsing to.
-
- Careful, the module won't be made until hitting [Create] at the bottom.
-
- As far as I can tell you can't get this panel again, rather delete and add
- a new module if you need to change the entries.
-
- Shows: "Project Structure" dialog, again, now the third panel with
- information about the developer module. Third panel shows three
- choices: [Source] [Paths] [Dependencies]
-
- [Sources] comming up with the source dialog is the default, but that does
- not mean the [Sources] button has been pushed.
-
- With Sources there are two panels.
-
- In second panel, on right side, the module root should show at the top.
- Under if it lists any sources, use the button at the far right of the
- listing to x it out anything that IntelliJ has automatically added.
-
- The first panel now shows a file browser for the module.
-
- Select the `javac` directory with a single click. Then, and only
- after, look immediately the directory lists and click on [Sources]
-
- When the [Source] button on the sources dialog has been
- pushed it will turn colors and gain a border when pushed. The
- [Sources] button must be pushed, or selected source
- directories will not be applied. Selecting a directory and
- hitting [OK] will not save anything, and will close the
- dialog.
-
- "Source Folders" will now appear in the second panel. The
- javac folder will be listed. Hhit: [apply] at the
- bottom. [apply] will then turn colors to show that there is
- nothing more to apply.
-
-
- Slide over to [Paths]
- Copmiler Output
- select [Use Module Compile Output Path]
- Output Path: $PROJECT_DIR$/developer/scratchpad
- Test Path: $PROJECT_DIR$/developer/test
-
- leave the exclude output checkbox, that means to exclude from repo
- and from indexing for search
-
- hit: [apply] at the bottom
-
- Add the `log` directory to [Resources], if you have one.
-
- After setting 'scratchpad' as the output directory on the [paths]
- configuration form, and leaving `scratchpad` as excluded via
- the checkbox. You can not then on the Sources form add
- `scratchpad` to the 'Excluded' list. Though it is excluded, it
- does not show there.
-
- After hitting [OK] the dialog disappears. Go back and check that everything
- you set is there. It seems common that for some reason, perhaps the order
- of hitting buttons, that settings are not there when going back.
-
---------------------------------------------------------------------------------
-Integrating programs from the project
-
- -------------
- Local tests and tools.
-
- This section is for adding an external tool, for example `tester/tool/make`, which
- builds Harmony tests.
-
- Hamburger> Run > edit configurations
- Shows Run/Debug configurations dialog
- Upper left hit '+'
- Shows drop down
- choose [Shell Script] second from bottom
- Shows dialog, for example:
- Name: tester-developer make
-
- Script Path: ~/Ariadne/env_run (better to chose with the
- file browser tool)
-
- Script Options: tester make
-
- Working Directory: ~/Ariadne (location of the env source scripts
- that env_run uses)
-
- Environment variabls: (none, env_run will source env_tester)
-
- Interpreter: /bin/bash (left to default)
-
- For debugging to work for the tests, they need to be run with
- java listening:
-
- java -agentlib:jdwp=transport=dt_socket,server=y,suspend=y,address=*:5005 $file
-
- I've included this in the bash wrappers made by make.
-
- -------------
- To add an "Application"
-
- Humburger > Run > edit configurations
- Shows Run/Debug configurations dialog
- Upper left hit '+'
- Shows drop down
- chose [Application] first choice
- Shows dialog, for example:
- Name: Test_Graph_0
-
- next line are two boxes, they are not labeled, the defaults show:
- [ module not specified ] [ -cp no module ]
- I selected::
- [ java 11 SDk of 'tester' module] [ -cp tester ]
- This can be confusing, as the modules are 'tester' and 'developer', but
- here it asks for an SDK! Then the next box says it wants a class path,
- but it wants a module name!
-
- next line one box, not labeled
- [ main class [] ]
- Note icon at right, it will give a list of class names, here in the tester module,
- that have main calls, select one.
-
- next line, again not labeled
- [ Program Arguments ]
- Test_Graph_0 has no arguments so I left it blank.
-
- Working Directory: ~/Ariadne
-
- Environment Variables:
- Left blank because the executable itself does not make use of any. I do
- know at this point if variables set in the environment IDEA ran in are
- inherited.
-
- 'Modify Options' with a drop down menu. (At the top right of the configuration dialog)
- Scan down for the `Java` section.
- Check: 'Do not build before run'
- (To build this example, go to the Run menu and run `tester
- make'. Or run make directly from a console prompt. Be sure to
- source env_tester first.)
-
-
+++ /dev/null
-----------------------------------------
-jdk-23
-
- cd "$REPO_HOME/tool_shared/third_party/upstream"
-
- # source for the 11 version used before, now upgraded to 23
- #curl -C - -o OpenJDK11U-jdk_x64_linux_hotspot_11.0.16_8.tar.gz https://github.com/adoptium/temurin11-binaries/releases/download/jdk-11.0.16+8/OpenJDK11U-jdk_x64_linux_hotspot_11.0.16_8.tar.gz
- curl -L -C - -b "oraclelicense=accept-securebackup-cookie" -O https://download.oracle.com/java/23/latest/jdk-23_linux-x64_bin.tar.gz
-
- cd ..
- tar -xzf upstream/jdk-23_linux-x64_bin.tar.gz
-
- edit $REPO_HOME/tool_shared/bespoke/env, and update JAVA_HOME:
- export JAVA_HOME="$REPO_HOME/tool_shared/third_party/jdk-23.0.1"
-
projects / Harmony.git / commitdiff