+++ /dev/null
-<!DOCTYPE html>
-<html lang="en">
- <head>
- <meta charset="UTF-8">
- <title>RT Prescriptive Code Format Guide</title>
- <script src="setup.js"></script>
- <script>
- window.StyleRT.include('RT/theme');
- window.StyleRT.include('RT/layout/article_tech_ref');
- </script>
- </head>
- <body>
- <RT-article>
- <RT-title
- author="Thomas Walker Lynch"
- date="2026-03-05"
- title="RT Prescriptive Code Format Guide (Version 4)">
- </RT-title>
-
- <RT-TOC level="1"></RT-TOC>
-
- <h1>Object vs. Instance Nomenclature</h1>
- <p>
- We reserve the word 'object' for its general English meaning. When discussing data that is manipulated solely through a defined interface, use the term <RT-term>instance</RT-term>.
- </p>
-
- <h1>Identifier Naming Conventions</h1>
- <ul>
- <li>Types, modules: <RT-code>PascalCase</RT-code></li>
- <li>Functions, variables: <RT-code>snake-kebab_case</RT-code> (if <RT-code>-</RT-code> is supported) or <RT-code>snake_case</RT-code> (if not supported)</li>
- <li>Globals: <RT-code>UPPER_SNAKE_CASE</RT-code></li>
- </ul>
-
- <h2>Proper Nouns and Acronyms</h2>
- <p>
- Even in <RT-code>PascalCase</RT-code> and <RT-code>snake_case</RT-code>, proper nouns and acronyms remain capitalized, as per standard English language conventions (e.g., <RT-code>IEEE_publication_count</RT-code>).
- </p>
-
- <h2>Expanded Suffix Semantics</h2>
- <p>Add a container or type suffix instead of making variable names plural. Never use plurals.</p>
- <ul>
- <li><RT-code>*_dp</RT-code> : directory path</li>
- <li><RT-code>*_dpr</RT-code> / <RT-code>*_dpa</RT-code> : relative / absolute directory path</li>
- <li><RT-code>*_fp</RT-code> : file path</li>
- <li><RT-code>*_fpr</RT-code> / <RT-code>*_fpa</RT-code> : relative / absolute file path</li>
- <li><RT-code>*_fs_nod_p</RT-code> : file system node path (when type is unspecified)</li>
- <li><RT-code>*_list</RT-code> / <RT-code>*_seq</RT-code> : generic ordered items / indexed items</li>
- <li><RT-code>*_map</RT-code> / <RT-code>*_dict</RT-code> : keyed containers</li>
- <li><RT-code>*_count</RT-code> : number of elements</li>
- <li><RT-code>*_flag</RT-code> : boolean</li>
- </ul>
-
- <h2>Primary and Secondary Separators (snake-kebab_case)</h2>
- <p>
- If a language supports the hyphen (<RT-code>-</RT-code>) in identifiers (such as Common Lisp and Emacs Lisp), the identifier is written in <RT-code>snake-kebab_case</RT-code>. The hyphen is used as the primary word separator. The underscore (<RT-code>_</RT-code>) is then used as a secondary separator to denote logically related portions or namespace boundaries within the identifier.
- </p>
- <p>
- Otherwise, if the language does not support hyphens in identifiers (such as C, Python, and Java), the identifier falls back to standard <RT-code>snake_case</RT-code> and only the underscore (<RT-code>_</RT-code>) is used for all separation. In C specifically, a center dot (<RT-code>·</RT-code>) is used for ad hoc namespaces.
- </p>
-
- <h1>Comma Separated Lists</h1>
-
- <h2>Horizontal Comma List</h2>
- <p>The comma is preceded by a space and abuts the item it follows.</p>
- <RT-code>
- int x ,y ,z;
- </RT-code>
-
- <h2>Vertical Comma List</h2>
- <p>The comma is placed <em>before</em> the item on the new line, aligned with the item's indentation.</p>
- <RT-code>
- result = some_function(
- first_argument
- ,second_argument
- ,third_argument
- );
- </RT-code>
-
- <h1>Enclosure Spacing</h1>
-
- <h2>Single-Level Enclosures</h2>
- <p>No space padding inside the enclosure punctuation.</p>
- <RT-code>
- if(condition){
- do_something();
- }
- </RT-code>
-
- <h2>Multi-Level Enclosures</h2>
- <p>One space of padding is applied <em>only</em> to the outermost enclosure punctuation.</p>
- <RT-code>
- if( f(g(x)) ){
- do_something();
- }
- </RT-code>
-
- <h2>Short Stuff Rule</h2>
- <p>If a statement can fit on a single line and is short, keep it on a single line without braces.</p>
- <RT-code>
- if(x == 0) return;
- </RT-code>
-
- <h1>Indentation</h1>
- <ul>
- <li>Strictly two spaces per indentation level.</li>
- <li>Never use tabs.</li>
- <li>Nest lines under the syntactic element that opened them.</li>
- </ul>
-
- <h2>Example: The CLI Pattern</h2>
- <p>Here is an example demonstrating the separation of work logic from the command line interface.</p>
- <RT-code>
- def calculate_area(length ,width):
- # The Work Function. Pure logic. Reusable by any other module.
- return length * width
-
- def CLI():
- # The Command Line Interface. Parses strings, calls work, handles output.
- import sys
-
- if len(sys.argv) < 3:
- print("Usage: ./area.py <len> <width>")
- sys.exit(1)
-
- # Parse Strings -> Native Types
- l = int(sys.argv[1])
- w = int(sys.argv[2])
-
- # Invoke Work
- result = calculate_area(l ,w)
-
- # Output
- print(f"Area: {result}")
-
- if __name__ == "__main__":
- CLI()
- </RT-code>
-
- <h1>The CLI vs. Work Function Pattern</h1>
- <p>
- To avoid the "String Trap"—where logic is tightly coupled to the terminal and requires string serialization to reuse—executable modules must separate the Command Line Interface from the core logic.
- </p>
- <ul>
- <li><strong>Work Functions:</strong> Implement core logic. They accept and return native instances (ints, lists, paths), never look at <RT-code>sys.argv</RT-code> (or equivalent), and do not depend on being run from a command line.</li>
- <li><strong>CLI Function:</strong> The bridge between the OS and the Work Function. It is always named <RT-code>CLI()</RT-code>. It parses string arguments into native types, calls the Work Function, formats the output for the user, and translates exceptions into exit codes.</li>
- </ul>
- <p>When a module is executed directly, the only top-level action should be calling <RT-code>CLI()</RT-code>.</p>
-
- <h1>Exercises</h1>
- <p>To ensure a full understanding of the RT code format, please complete the following exercises.</p>
-
-
- <h2>Exercise 1: Comma and Function Call Formatting</h2>
- <p>Reformat the following C code snippet to strictly adhere to the RT code format rules. Pay close attention to the horizontal and vertical comma lists, and the enclosure spacing for the function call.</p>
- <RT-code>
- void my_function(int a, int b, int c) {
- int result = calculate_value(a, b, c);
- printf("Result: %d, a: %d, b: %d, c: %d\n", result, a, b, c);
- }
-
- result = my_function(
- rediculously_long_first_argument,
- rediculously_long_second_argument,
- rediculously_long_third_argument
- );
- </RT-code>
-
- <h2>Exercise 2: Multi-Level Enclosure and Short Stuff Rule</h2>
- <p>Reformat the following C code snippet. The <RT-code>if</RT-code> statement should use the multi-level enclosure rule, and the <RT-code>for</RT-code> loop body should use the short stuff rule.</p>
- <RT-code>
- if (check_permissions(user_id, file_path) && is_valid(file_path)) {
- for (int i = 0; i < 10; i++) {
- if (i % 2 == 0) {
- printf("Even: %d\n", i);
- }
- }
- }
- </RT-code>
-
- </RT-article>
- </body>
-</html>
+++ /dev/null
-<!DOCTYPE html>
-<html lang="en">
- <head>
- <meta charset="UTF-8">
- <title>Naming and Directory Conventions</title>
- <script src="setup.js"></script>
- <script>
- window.StyleRT.include('RT/theme');
- window.StyleRT.include('RT/layout/article_tech_ref');
- </script>
- </head>
- <body>
- <RT-article>
- <RT-title
- author="RT"
- date="2026-03-05"
- title="Naming and Directory Conventions">
- </RT-title>
-
- <p>
- A directory name is taken as a <RT-term>property</RT-term> for a set of files. Consequently, directory names are rarely plural. For example, suppose we have a number of test files in a directory. The directory would be named <RT-code>test</RT-code>, as each file in the directory has the property of being a test.
- </p>
-
- <p>
- It would be nice if we could attach multiple properties to a file as part of the file system framework, but conventional file systems do not support this. Consequently, when needed, people add a second property to a file using dot extensions to the file's name. Hence, we get something like <RT-code>sqrt.c</RT-code> in a directory called <RT-code>source</RT-code>. The first property is that the file is source code, and the second property is that it is C code.
- </p>
-
- <p>
- We could extend the dot suffix model of adding a property to a file by using multiple dot suffixes. Our C makefile structure makes use of this.
- </p>
-
- <p>So what is a reasonable primary property for a set of files? Perhaps:</p>
- <ul>
- <li>Who uses each file with this property. Home directories are named like this.</li>
- <li>The role of the people using the file. This is a more generic version of the prior rule. The <RT-code>developer</RT-code> and <RT-code>tester</RT-code> directories were named in this manner.</li>
- <li>What program are the files for. Thus we might name a directory of files for the C compiler <RT-code>cc</RT-code>.</li>
- <li>The generic category of program said files are for. Thus we end up with directories called <RT-code>src</RT-code> or <RT-code>executable</RT-code>.</li>
- </ul>
-
- <p>
- As for the names <RT-code>src</RT-code> and <RT-code>executable</RT-code>, those come from times when almost all programs were compiled. We prefer instead the names <RT-code>authored</RT-code> and <RT-code>made</RT-code>. <RT-code>authored</RT-code> files are those written by humans (or these days, perhaps AI), while <RT-code>made</RT-code> files are products of tools. For a Python program, we put packages in <RT-code>authored</RT-code> with a module called <RT-code>CLI.py</RT-code> for the command line interface. Then we link from <RT-code>made</RT-code> into <RT-code>authored</RT-code> so as to give the program a name.
- </p>
-
- <p>
- Hence, with the default makefile for C, compiler fodder is found in the <RT-code>authored/</RT-code> directory. File name extensions are used to signal to the build tools how the file is to be processed:
- </p>
- <ul>
- <li><RT-code>.cli.c</RT-code> : Compiler fodder made into a stand-alone executable.</li>
- <li><RT-code>.lib.c</RT-code> : Library code source, compiled as an object file and added to the project archive.</li>
- <li><RT-code>.mod.c</RT-code> : Kernel module sources.</li>
- </ul>
-
- <p>
- The RT C coding environment does not use separate source and header files. Instead, a variable is set that gates off the implementation if the source code is to be used as a header. Hence, all of our C source fits fine within an <RT-code>authored</RT-code> directory.
- </p>
- </RT-article>
- </body>
-</html>
+++ /dev/null
-<!DOCTYPE html>
-<html lang="en">
- <head>
- <meta charset="UTF-8">
- <title>Language Addenda (C, Python, Bash, Lisp)</title>
- <script src="setup.js"></script>
- <script>
- window.StyleRT.include('RT/theme');
- window.StyleRT.include('RT/layout/article_tech_ref');
- </script>
- </head>
- <body>
- <RT-article>
- <RT-title
- author="RT"
- date="2026-03-05"
- title="Language Addenda (C, Python, Bash, Lisp)">
- </RT-title>
-
- <RT-TOC level="1"></RT-TOC>
-
- <h1>Purpose</h1>
- <p>
- The RT code format is language-agnostic, but actual languages differ in syntax and constraints. This document explains how the RT rules are applied in C, Python, Bash, and Lisp dialects.
- </p>
-
- <h1>1. C Addendum</h1>
- <h2>1.1 Control Structure and File Layout</h2>
- <p>
- Each module has an <strong>Interface</strong> section and an <strong>Implementation</strong> section in the same file. The sections are toggled using preprocessor macros (e.g., <RT-code>FACE</RT-code>). Interface declarations are processed even when included multiple times; the implementation is compiled only when used as an implementation.
- </p>
-
- <h2>1.2 Indentation and Comma Lists</h2>
- <p>C code follows the RT two-space indentation and vertical comma lists:</p>
- <RT-code>
-result = some_function(
- first_argument
- ,second_argument_with_longer_name
- ,third_argument
-);
- </RT-code>
-
- <h2>1.3 Error Handling and Ownership</h2>
- <ul>
- <li>Functions should document ownership of pointers and lifetimes.</li>
- <li>Prefer explicit <RT-code>*_count</RT-code> parameters over sentinel values when passing arrays.</li>
- </ul>
-
- <h1>2. Python Addendum</h1>
- <h2>2.1 Indentation and Layout</h2>
- <p>Python enforces indentation syntactically, so the RT two-space rule becomes:</p>
- <ul>
- <li>Use <strong>two-space indentation</strong> for all Python code, even though four is common in the wider ecosystem.</li>
- <li>Vertical comma lists still place the comma at the start of the line, after the indentation.</li>
- </ul>
-
- <h2>2.2 Modules and CLI Separation</h2>
- <p>Python scripts distinguish between:</p>
- <ol>
- <li><strong>Work functions</strong> (importable API).</li>
- <li><strong>CLI entry points</strong> (argument parsing, printing, exit codes).</li>
- </ol>
- <p>Put argument parsing and <RT-code>if __name__ == "__main__":</RT-code> in the CLI section. Keep side effects out of import time.</p>
-
- <h1>3. Bash Addendum</h1>
- <h2>3.1 Shebang and Safety</h2>
- <p>Bash scripts should start with:</p>
- <RT-code>
-#!/usr/bin/env bash
-set -euo pipefail
- </RT-code>
-
- <h2>3.2 Functions vs. Top-Level Code</h2>
- <p>RT-style Bash separates a small top-level CLI harness (argument parsing, usage, dispatch) from a set of functions that implement the work. Parse arguments into variables, call a main function with explicit parameters, and avoid relying on global mutable state where possible.</p>
-
- <h1>4. Lisp / Emacs Lisp Addendum</h1>
- <h2>4.1 Identifier Separators (snake-kebab_case)</h2>
- <p>
- Because Lisp dialects support the hyphen (<RT-code>-</RT-code>) in symbols, they utilize <RT-code>snake-kebab_case</RT-code> as the standard for functions and variables. The hyphen replaces the underscore as the primary word separator.
- </p>
- <p>
- The underscore (<RT-code>_</RT-code>) is reserved strictly as a secondary separator. It is used to group logically related portions of an identifier or to denote semantic boundaries, acting as a structural namespace within the symbol (e.g., <RT-code>city-scape_building-height</RT-code>).
- </p>
-
- <h2>4.2 Enclosures and Indentation</h2>
- <p>
- Lisp relies entirely on parentheses for evaluation boundaries. The RT multi-level enclosure rule applies: one space of padding is applied to the outermost parentheses of an evaluated list, while inner lists receive no padding. Indentation remains strictly two spaces.
- </p>
-
- <h1>5. Using the Addenda</h1>
- <p>
- When in doubt, start with <RT-code>02_RT_Code_Format.html</RT-code> for the core rules, then apply the relevant language section here. If a language requires deviation from the generic rules, document that deviation in this file instead of ad-hoc decisions.
- </p>
- </RT-article>
- </body>
-</html>
--- /dev/null
+<!DOCTYPE html>
+<html lang="en">
+ <head>
+ <meta charset="UTF-8">
+ <title>File and directory naming conventions</title>
+ <script src="setup.js"></script>
+ <script>
+ window.StyleRT.include('RT/theme');
+ window.StyleRT.include('RT/layout/article_tech_ref');
+ </script>
+ </head>
+ <body>
+ <RT-article>
+ <RT-title
+ author="RT"
+ date="2026-03-09"
+ title="File and directory naming conventions">
+ </RT-title>
+
+ <h1>Case</h1>
+ <p>
+ Directory and file names follow the exact same casing rules as the identifiers they represent. Because standard file systems support the hyphen (<RT-code>-</RT-code>), file and directory names use <RT-code>snake-kebab_case</RT-code> for functions and scripts, and <RT-code>PascalCase</RT-code> for types and modules. The hyphen serves as the primary word separator, while the underscore (<RT-code>_</RT-code>) is reserved for structural or namespace boundaries. (Currently many file names use primarily `_`, but we will transition to this more uniform approach.)
+ </p>
+
+ <h1>Directory properties</h1>
+ <p>
+ A directory name is taken as a <RT-term>property</RT-term> for a set of files. Consequently, directory names are rarely plural. For example, suppose we have a number of test files in a directory. The directory would be named <RT-code>test</RT-code>, as each file in the directory has the property of being a test.
+ </p>
+ <p>
+ What is a reasonable primary property for a set of files? Perhaps:
+ </p>
+ <ul>
+ <li>Who uses each file with this property. Home directories are named like this.</li>
+ <li>The role of the people using the file. The <RT-code>developer</RT-code> and <RT-code>tester</RT-code> directories were named in this manner.</li>
+ <li>What program are the files for.</li>
+ <li>The generic category of program said files are for. We prefer the names <RT-code>authored</RT-code> and <RT-code>made</RT-code>. <RT-code>authored</RT-code> files are those written by humans or AI, while <RT-code>made</RT-code> files are products of tools.</li>
+ </ul>
+
+ <h1>Dot extensions as properties</h1>
+ <p>
+ We add a second property to a file using dot extensions to the file's name. We can extend the dot suffix model by using multiple dot suffixes. File name extensions are used to signal to the build tools how the file is to be processed:
+ </p>
+ <ul>
+ <li><RT-code>.cli.c</RT-code> : Compiler fodder made into a stand-alone executable.</li>
+ <li><RT-code>.lib.c</RT-code> : Library code source, compiled as an object file and added to the project archive.</li>
+ <li><RT-code>.mod.c</RT-code> : Kernel module sources.</li>
+ </ul>
+
+ <h2>C source file structure</h2>
+ <p>
+ The RT C coding environment does not use separate source and header files. Each module has an <strong>Interface</strong> section and an <strong>Implementation</strong> section in the same file. A preprocessor macro (e.g., <RT-code>FACE</RT-code>) is used to gate off the implementation if the source code is to be used as a header.
+ </p>
+ </RT-article>
+ </body>
+</html>
--- /dev/null
+<!DOCTYPE html>
+<html lang="en">
+ <head>
+ <meta charset="UTF-8">
+ <title>RT code format conventions</title>
+ <script src="setup.js"></script>
+ <script>
+ window.StyleRT.include('RT/theme');
+ window.StyleRT.include('RT/layout/article_tech_ref');
+ </script>
+ </head>
+ <body>
+ <RT-article>
+ <RT-title
+ author="Thomas Walker Lynch"
+ date="2026-03-09"
+ title="RT code format conventions">
+ </RT-title>
+
+ <RT-TOC level="1"></RT-TOC>
+
+ <h1>Object vs. instance nomenclature</h1>
+ <p>
+ We reserve the word 'object' for its general English meaning. When discussing data that is manipulated solely through a defined interface, use the term <RT-term>instance</RT-term>.
+ </p>
+
+ <h1>Identifier Names</h1>
+
+ <h2>Case</h2>
+ <ul>
+ <li>Types, modules: <RT-code>PascalCase</RT-code></li>
+ <li>Functions, variables: <RT-code>snake-kebab_case</RT-code> (if <RT-code>-</RT-code> is supported) or <RT-code>snake_case</RT-code> (if not supported)</li>
+ <li>Globals: <RT-code>UPPER_SNAKE_CASE</RT-code></li>
+ </ul>
+
+ <h2>Primary and secondary separators (snake-kebab_case)</h2>
+ <p>
+ If a language supports the hyphen (<RT-code>-</RT-code>) in identifiers (such as Common Lisp and Emacs Lisp), the identifier is written in <RT-code>snake-kebab_case</RT-code>. The hyphen is used as the primary word separator. The underscore (<RT-code>_</RT-code>) is then reserved strictly as a secondary separator to group logically related portions of an identifier or to denote semantic boundaries, acting as a structural namespace within the symbol (e.g., <RT-code>city-scape_building-height</RT-code>).
+ </p>
+ <p>
+ Otherwise, if the language does not support hyphens in identifiers (such as C, Python, and Java), the identifier falls back to standard <RT-code>snake_case</RT-code> and only the underscore (<RT-code>_</RT-code>) is used for all separation. In C specifically, a center dot (<RT-code>·</RT-code>) is used for ad hoc namespaces.
+ </p>
+
+ <h2>Suffixes</h2>
+
+ <p>Add a container type suffix instead of making variable names plural.</p>
+ <ul>
+ <li><RT-code>*_list</RT-code> / <RT-code>*_seq</RT-code> : generic ordered items / indexed items</li>
+ <li><RT-code>*_map</RT-code> / <RT-code>*_dict</RT-code> : keyed containers</li>
+ <li><RT-code>*_count</RT-code> : number of elements</li>
+ </ul>
+
+ <p>Add a type suffix when it adds clarity.</p>
+ <ul>
+ <li><RT-code>*_bool</RT-code> : boolean</li>
+ <li><RT-code>*_flag</RT-code> : boolean</li>
+ </ul>
+
+ <ul>
+ <li><RT-code>*_dirn</RT-code> : directory name</li>
+ <li><RT-code>*_dirp</RT-code> : directory path</li>
+ <li><RT-code>*_dirpr</RT-code> / <RT-code>*_dirpa</RT-code> : relative / absolute directory path</li>
+ <li><RT-code>*_filen</RT-code> : file name</li>
+ <li><RT-code>*_filep</RT-code> : file path</li>
+ <li><RT-code>*_filepr</RT-code> / <RT-code>*_fpa</RT-code> : relative / absolute file path</li>
+ <li><RT-code>*_fsnodn</RT-code> : file system node name (when type is unspecified)</li>
+ <li><RT-code>*_fsnodp</RT-code> : file system node path (when type is unspecified)</li>
+ </ul>
+
+ <h2>Proper nouns and acronyms</h2>
+ <p>
+ Even in <RT-code>PascalCase</RT-code> and <RT-code>snake_case</RT-code>, proper nouns and acronyms remain capitalized, as per standard English language conventions (e.g., <RT-code>IEEE_publication_count</RT-code>).
+ </p>
+
+ <h1>Comma separated lists</h1>
+
+ <h2>Horizontal comma list</h2>
+ <p>The comma is preceded by a space and abuts the item it follows.</p>
+ <RT-code>
+ int x ,y ,z;
+ </RT-code>
+
+ <h2>Vertical comma list</h2>
+ <p>The comma is placed <em>before</em> the item on the new line, aligned with the item's indentation. This applies to all languages, including Python and C.</p>
+ <RT-code>
+ result = some_function(
+ first_argument
+ ,second_argument
+ ,third_argument
+ );
+ </RT-code>
+
+ <h1>Enclosure spacing</h1>
+
+ <h2>Single-level enclosures</h2>
+ <p>No space padding inside the enclosure punctuation.</p>
+ <RT-code>
+ if(condition){
+ do_something();
+ }
+ </RT-code>
+
+ <h2>Multi-level enclosures</h2>
+ <p>One space of padding is applied <em>only</em> to the outermost enclosure punctuation.</p>
+
+ <RT-code>
+ if( f(g(x)) ){
+ do_something();
+ }
+ </RT-code>
+
+ <p>This rule is not applied to function calls in Lisp.</p>
+
+ <h2>Short stuff rule</h2>
+ <p>If a statement can fit on a single line and is short, keep it on a single line without braces.</p>
+ <RT-code>
+ if(x == 0) return;
+ </RT-code>
+
+ <h1>Indentation</h1>
+ <ul>
+ <li>Strictly two spaces per indentation level.</li>
+ <li>Never use tabs.</li>
+ <li>Nest lines under the syntactic element that opened them.</li>
+ </ul>
+ <p>Python enforces indentation syntactically. Use two-space indentation for all Python code, even though four is common in the wider ecosystem.</p>
+
+ <h1>The CLI vs. work function pattern</h1>
+ <p>
+ To avoid the "String Trap" — where logic is tightly coupled to the terminal and requires string serialization to reuse — executable modules must separate the Command Line Interface from the core logic.
+ </p>
+ <ul>
+ <li><strong>Work Functions:</strong> Implement core logic. They accept and return native instances (ints, lists, paths), never look at <RT-code>sys.argv</RT-code> (or equivalent), and do not depend on being run from a command line.</li>
+ <li><strong>CLI Function:</strong> The bridge between the OS and the Work Function. It is always named <RT-code>CLI()</RT-code>. It parses string arguments into native types, calls the Work Function, formats the output for the user, and translates exceptions into exit codes.</li>
+ </ul>
+
+ <h2>Python application</h2>
+ <p>Put argument parsing and <RT-code>if __name__ == "__main__":</RT-code> in the CLI section. Keep side effects out of import time.</p>
+
+ <h2>Bash application</h2>
+ <p>Bash scripts should start with <RT-code>#!/usr/bin/env bash</RT-code> and <RT-code>set -euo pipefail</RT-code>. RT-style Bash separates a small top-level CLI harness from a set of functions that implement the work. Parse arguments into variables, call a main function with explicit parameters, and avoid relying on global mutable state where possible.</p>
+
+ <h1>C addendum: error handling and ownership</h1>
+ <ul>
+ <li>Functions should document ownership of pointers and lifetimes.</li>
+ <li>Prefer explicit <RT-code>*_count</RT-code> parameters over sentinel values when passing arrays.</li>
+ </ul>
+
+ <h1>Exercises</h1>
+ <h2>Exercise 1: Comma and function call formatting</h2>
+ <p>Reformat the following C code snippet to strictly adhere to the RT code format rules.</p>
+ <RT-code>
+ void my_function(int a, int b, int c) {
+ int result = calculate_value(a, b, c);
+ printf("Result: %d, a: %d, b: %d, c: %d\n", result, a, b, c);
+ }
+ </RT-code>
+
+ <h2>Exercise 2: Multi-level enclosure and short stuff rule</h2>
+ <p>Reformat the following C code snippet to use the multi-level enclosure rule and the short stuff rule.</p>
+ <RT-code>
+ if (check_permissions(user_id, file_path) && is_valid(file_path)) {
+ for (int i = 0; i < 10; i++) {
+ if (i % 2 == 0) {
+ printf("Even: %d\n", i);
+ }
+ }
+ }
+ </RT-code>
+
+ <h2>Exercise 3: Identifier Naming Conventions</h2>
+ <p>
+ Rename the following poorly named variables to strictly adhere to the RT code format rules. Assume these are variables in a C or Python program (using standard <RT-code>snake_case</RT-code>). Pay close attention to proper nouns, acronyms, and the expanded suffix semantics.
+ </p>
+ <ul>
+ <li>A variable holding a list of addresses for HTTP servers: <RT-code>httpServers</RT-code></li>
+ <li>A variable counting the total number of parsed HTML nodes: <RT-code>num_html_nodes</RT-code></li>
+ <li>A custom type representing a JSON payload: <RT-code>json_payload</RT-code></li>
+ <li>A boolean indicating if the NASA data download is complete: <RT-code>isNasaDone</RT-code></li>
+ <li>A variable holding multiple absolute file paths for images: <RT-code>imageFiles</RT-code></li>
+ </ul>
+
+
+ </RT-article>
+ </body>
+</html>
set -x
cd "$REPO_HOME"/developer || exit 1
- # /bin/make -f tool/makefile $@
-
- mkdir -p scratchpad/authored
- cp authored/HTTP_server.js scratchpad/authored/
- cp authored/port_forwarder scratchpad/authored/
- cp authored/port_forwarder_CLI scratchpad/authored/
- cp authored/permission_RT scratchpad/authored/
- cp authored/permission_UPG scratchpad/authored/
+ /bin/make -f tool/makefile $@
set +x
echo "$(script_fn) done."
.SUFFIXES:
.EXPORT_ALL_VARIABLES:
-RT_INCOMMON := $(REPO_HOME)/shared/third_party/RT-project-share/release
+RT_MAKEFILE_DP := $(REPO_HOME)/shared/tool/makefile
include $(RT_INCOMMON)/make/environment_RT_1.mk
.PHONY: usage
@printf "local ----------------------------------------\n"
@echo tool/makefile version 2.0
@printf "target_library_CLI.mk ----------------------------------------\n"
- @$(MAKE) -f $(RT_INCOMMON)/make/target_kmod.mk version
+ @$(MAKE) -f $(RT_MAKEFILE_DP)/target_kmod.mk version
@printf "target_kmod.mk ----------------------------------------\n"
- @$(MAKE) -f $(RT_INCOMMON)/make/target_library_CLI.mk version
+ @$(MAKE) -f $(RT_MAKEFILE_DP)/target_library_CLI.mk version
.PHONY: information
information:
@echo KMOD_BUILD_DIR="/lib/modules/$(shell uname -r)/build"
@echo CURDIR="$(CURDIR)"
@printf "target_library_CLI.mk ----------------------------------------\n"
- @$(MAKE) -f $(RT_INCOMMON)/make/target_library_CLI.mk information
+ @$(MAKE) -f $(RT_MAKEFILE_DP)/target_library_CLI.mk information
@printf "target_kmod.mk ----------------------------------------\n"
- @$(MAKE) -f $(RT_INCOMMON)/make/target_kmod.mk information
+ @$(MAKE) -f $(RT_MAKEFILE_DP)/target_kmod.mk information
.PHONY: all
all: library CLI kmod
.PHONY: library lib
library lib:
- @$(MAKE) -f $(RT_INCOMMON)/make/target_library_CLI.mk library
+ @$(MAKE) -f $(RT_MAKEFILE_DP)/target_library_CLI.mk library
.PHONY: CLI
CLI:
- @$(MAKE) -f $(RT_INCOMMON)/make/target_library_CLI.mk CLI
+ @$(MAKE) -f $(RT_MAKEFILE_DP)/target_library_CLI.mk CLI
.PHONY: kmod
kmod:
- @$(MAKE) -f $(RT_INCOMMON)/make/target_kmod.mk kmod
+ @$(MAKE) -f $(RT_MAKEFILE_DP)/target_kmod.mk kmod
.PHONY: clean
clean:
@printf "local ----------------------------------------\n"
@printf "target_library_CLI.mk ----------------------------------------\n"
- @$(MAKE) -f $(RT_INCOMMON)/make/target_library_CLI.mk clean
+ @$(MAKE) -f $(RT_MAKEFILE_DP)/target_library_CLI.mk clean
@printf "target_kmod.mk ----------------------------------------\n"
- @$(MAKE) -f $(RT_INCOMMON)/make/target_kmod.mk clean
+ @$(MAKE) -f $(RT_MAKEFILE_DP)/target_kmod.mk clean
<h1>The version 2.2 Harmony directory tree</h1>
<RT-code>
- 2026-03-07 14:50:50 Z [Harmony:administrator] Thomas_PM@ManhattanSquare
- §/home/Thomas/subu_data/PM/project§
+ 2026-03-09 01:42:16 Z [Harmony:administrator] Thomas_developer@StanleyPark
+ §/home/Thomas/subu_data/developer/project§
> tree Harmony
Harmony
├── 0pus_Harmony
├── administrator
- │ ├── authored
- │ ├── document
- │ │ ├── 00_Project_Structure.html
- </RT-code>
- <RT-code>
- │ │ ├── 01_Workflow_Build_Contract.html
- │ │ ├── Harmony.md
- │ │ └── setup.js
- │ └── tool
- │ ├── after_pull
- │ ├── archive
- │ ├── release
- │ └── setup
+ │ ├── authored
+ │ ├── document
+ │ │ └── setup.js
+ │ └── tool
+ │ ├── archive
+ │ └── setup
├── consumer
- </RT-code>
- <RT-code>
- │ ├── scratchpad
- │ └── tool
- │ └── env
+ │ ├── scratchpad
+ │ └── tool
+ │ └── env
├── developer
- │ ├── authored
- │ │ └── hello.cli.c
- │ ├── document
- │ │ ├── 02_RT_Code_Format.html
- │ │ ├── 03_Naming_and_Directory_Conventions.html
+ │ ├── authored
+ │ │ └── hello.cli.c
</RT-code>
<RT-code>
- │ │ ├── 04_Language_Addenda.html
- │ │ ├── ontology.org
- │ │ └── setup.js
- │ ├── experiment
- │ ├── made
- │ ├── scratchpad
- │ └── tool
- │ ├── do_all
- │ ├── make
+ │ ├── document
+ │ │ ├── 02_RT_Code_Format.html
+ │ │ ├── 03_Naming_and_Directory_Conventions.html
+ │ │ ├── 04_Language_Addenda.html
+ │ │ └── setup.js
+ │ ├── experiment
+ │ ├── made
+ │ ├── scratchpad
+ │ └── tool
+ │ ├── do_all
+ │ ├── make
+ │ ├── makefile
+ │ ├── release
+ │ └── setup
+ ├── document
+ │ ├── Introduction_to_Harmony.html
+ │ ├── Product_Development_Roles_and_Workflow.html
+ │ └── setup.js
+ ├── LICENSE
</RT-code>
<RT-code>
- │ ├── makefile
- │ ├── release
- │ └── setup
- ├── LICENSE
+ ├── README.md
├── scratchpad
- │ └── Harmony__79f9d52__2026-03-07_085628Z.tar
+ │ ├── Harmony__79f9d52__2026-03-07_085628Z.tar
+ │ └── Harmony__e665bb7__2026-03-09_013712Z.tar
├── setup
├── shared
- │ ├── authored
+ │ ├── authored
+ │ ├── document
+ │ │ ├── install_generic.org
+ │ │ ├── install_Python.org
+ │ │ └── setup.js
+ │ ├── made
+ │ ├── style_directory_dict.js
+ │ ├── third_party
+ │ │ ├── RT-style-JS_public -> ../../../RT-style-JS_public/
+ │ │ └── upstream
+ │ └── tool
+ │ ├── scratchpad
+ │ ├── setup
</RT-code>
<RT-code>
- │ ├── document
- │ │ ├── install_generic.org
- │ │ ├── install_Python.org
- │ │ └── setup.js
- │ ├── made
- │ ├── style_directory_dict.js
- │ ├── third_party
- │ │ ├── RT-style-JS_public -> ../../../RT-style-JS_public/
- │ │ └── upstream
- </RT-code>
- <RT-code>
- │ └── tool
- │ ├── scratchpad
- │ ├── setup
- │ ├── style
- │ └── version
+ │ ├── style
+ │ └── version
└── tester
├── authored
- │ └── test_routine.sh
+ │ └── test_routine.sh
├── RT_Format
- </RT-code>
- <RT-code>
- │ ├── RT_Format
- │ ├── RT_Format.el
- │ ├── test_0_data.c
- │ └── test_1_data.py
+ │ ├── RT_Format
+ │ ├── RT_Format.el
+ │ ├── test_0_data.c
+ │ └── test_1_data.py
└── tool
└── setup
- 29 directories, 37 files
+ 30 directories, 36 files
+
+ 2026-03-09 01:42:19 Z [Harmony:administrator] Thomas_developer@StanleyPark
+ §/home/Thomas/subu_data/developer/project§
+ >
</RT-code>
</RT-article>
shared/third_party/Python
#+end_src
-This environment is shared across the =developer= and =tester= roles and is automatically activated through their respective =env_<role>= scripts.
-
* Precondition
Ensure the following:
--- /dev/null
+#ifndef RT·ENVIRONMENT_H
+#define RT·ENVIRONMENT_H
+ #include <stdint.h>
+ #include <stdbool.h>
+
+ typedef unsigned int uint;
+
+ #define Local static
+ #define Free(pt) free(pt); (pt) = NULL;
+
+#endif
--- /dev/null
+# enviroment_RT_1.mk
+# makefile environment variable defaults.
+# cc is the name of the C compiler, a file called <name>.c is C source code.
+# RT uses header integrated C source files, i.e. the source and the header are the same file
+
+SHELL=/bin/bash
+
+# environment_RT_1.mk
+
+ECHO := printf "%b\n"
+
+C_SOURCE_DIR := authored
+C := gcc
+CFLAGS := -std=gnu11 -Wall -Wextra -Wpedantic -finput-charset=UTF-8
+CFLAGS += -MMD -MP
+CFLAGS += -I $(C_SOURCE_DIR)
+
+LIBRARY_NAME := $(PROJECT)
+LIBRARY_NAME := $(subst -,_,$(LIBRARY_NAME))
+
+LIBRARY_DIR := scratchpad
+LIBRARY_FILE := $(LIBRARY_DIR)/lib$(LIBRARY_NAME).a
+
+LN_FLAGS := -L$(LIBRARY_DIR) -L/lib64 -L/lib
+
+MACHINE_DIR := scratchpad/made
+
+KMOD_SOURCE_DIR := cc
+KMOD_CCFLAGS := -I $(KMOD_SOURCE_DIR)
+KMOD_OUTPUT_DIR := scratchpad/kmod
--- /dev/null
+# make/target_kmod.mk — build *.kmod.c as kernel modules (single-pass, kmod-only)
+# invoked from $REPO_HOME/<role>
+# version 1.4
+
+.SUFFIXES:
+.DELETE_ON_ERROR:
+
+#--------------------------------------------------------------------------------
+# defaults for environment variables (override from outer make/env as needed)
+
+# Kernel build tree, which is part of the Linux system, use running kernel if unset
+KMOD_BUILD_DIR ?= /lib/modules/$(shell uname -r)/build
+
+# Authored source directory (single dir)
+KMOD_SOURCE_DIR ?= cc
+
+# Extra compiler flags passed to Kbuild (e.g., -I $(KMOD_SOURCE_DIR))
+KMOD_CCFLAGS ?=
+
+# Include *.lib.c into modules (1=yes, 0=no)
+KMOD_INCLUDE_LIB ?= 1
+
+# KMOD_OUTPUT_DIR is constrained, relative path, on the scratchpad, and ends in kmod
+# Require: non-empty, relative, no '..', ends with 'kmod' dir
+define assert_kmod_output_dir_ok
+ $(if $(strip $(1)),,$(error KMOD_OUTPUT_DIR is empty))
+ $(if $(filter /%,$(1)),$(error KMOD_OUTPUT_DIR must be relative: '$(1)'),)
+ $(if $(filter %/../% ../% %/.. ..,$(1)),$(error KMOD_OUTPUT_DIR must not contain '..': '$(1)'),)
+ $(if $(filter %/kmod %/kmod/ kmod,$(1)),,$(error KMOD_OUTPUT_DIR must end with 'kmod': '$(1)'))
+endef
+KMOD_OUTPUT_DIR ?= scratchpad/kmod
+$(eval $(call assert_kmod_output_dir_ok,$(KMOD_OUTPUT_DIR)))
+
+# The kernel make needs and absolute path to find the output directory
+ABS_KMOD_OUTPUT_DIR := $(CURDIR)/$(KMOD_OUTPUT_DIR)
+
+#--------------------------------------------------------------------------------
+# derived variables (computed from the above)
+
+# Authored basenames (without suffix)
+base_list := $(patsubst %.kmod.c,%,$(notdir $(wildcard $(KMOD_SOURCE_DIR)/*.kmod.c)))
+
+# Optional library sources (without suffix) to include inside modules
+ifeq ($(KMOD_INCLUDE_LIB),1)
+lib_base := $(patsubst %.lib.c,%,$(notdir $(wildcard $(KMOD_SOURCE_DIR)/*.lib.c)))
+else
+lib_base :=
+endif
+
+# Staged sources (kept namespaced to prevent .o collisions)
+all_kmod_c := $(addsuffix .kmod.c,$(addprefix $(KMOD_OUTPUT_DIR)/,$(base_list)))
+all_lib_c := $(addsuffix .lib.c,$(addprefix $(KMOD_OUTPUT_DIR)/,$(lib_base)))
+
+
+
+#--------------------------------------------------------------------------------
+# targets
+
+.PHONY: usage
+usage:
+ @printf "Usage: make [kmod|clean|information|version]\n"
+
+.PHONY: version
+version:
+ @echo target_kmod version 1.4
+
+.PHONY: information
+information:
+ @echo "KMOD_SOURCE_DIR: " $(KMOD_SOURCE_DIR)
+ @echo "KMOD_BUILD_DIR: " $(KMOD_BUILD_DIR)
+ @echo "KMOD_OUTPUT_DIR: " $(KMOD_OUTPUT_DIR)
+ @echo "base_list: " $(base_list)
+ @echo "lib_base: " $(lib_base)
+ @echo "all_kmod_c: " $(all_kmod_c)
+ @echo "all_lib_c: " $(all_lib_c)
+ @echo "KMOD_INCLUDE_LIB=" $(KMOD_INCLUDE_LIB)
+
+
+ifeq ($(strip $(base_list)),)
+ $(warning No *.kmod.c found under $(KMOD_SOURCE_DIR); nothing to build)
+endif
+
+# --- Parallel-safe preparation as real targets ---
+
+# ensure the staging dir exists (order-only prereq)
+$(KMOD_OUTPUT_DIR):
+ @mkdir -p "$(KMOD_OUTPUT_DIR)"
+
+# generate the Kbuild control Makefile
+$(KMOD_OUTPUT_DIR)/Makefile: | $(KMOD_OUTPUT_DIR)
+ @{ \
+ printf "ccflags-y += %s\n" "$(KMOD_CCFLAGS)"; \
+ printf "obj-m := %s\n" "$(foreach m,$(base_list),$(m).o)"; \
+ for m in $(base_list); do \
+ printf "%s-objs := %s.kmod.o" "$$m" "$$m"; \
+ for lb in $(lib_base); do printf " %s.lib.o" "$$lb"; done; \
+ printf "\n"; \
+ done; \
+ } > "$@"
+
+# stage kmod sources (one rule per file; parallelizable)
+$(KMOD_OUTPUT_DIR)/%.kmod.c: $(KMOD_SOURCE_DIR)/%.kmod.c | $(KMOD_OUTPUT_DIR)
+ @echo "--- Stage: $@ ---"
+ @cp -f "$(abspath $<)" "$@"
+
+# stage library sources (optional; also parallelizable)
+$(KMOD_OUTPUT_DIR)/%.lib.c: $(KMOD_SOURCE_DIR)/%.lib.c | $(KMOD_OUTPUT_DIR)
+ @echo "--- Stage: $@ ---"
+ @cp -f "$(abspath $<)" "$@"
+
+
+.PHONY: kmod
+kmod: $(KMOD_OUTPUT_DIR)/Makefile $(all_kmod_c) $(all_lib_c)
+ifeq ($(strip $(base_list)),)
+ @echo "--- No kmod sources; nothing to do ---"
+else
+ @echo "--- Invoking Kbuild for kmod: $(base_list) ---"
+ $(MAKE) -C "$(KMOD_BUILD_DIR)" M="$(ABS_KMOD_OUTPUT_DIR)" modules
+endif
+
+# quality-of-life: allow 'make scratchpad/kmod/foo.ko' after batch build
+$(KMOD_OUTPUT_DIR)/%.ko: kmod
+ @true
+
+.PHONY: clean
+clean:
+ @echo "Cleaning: $(KMOD_BUILD_DIR)"
+ @$(MAKE) -C "$(KMOD_BUILD_DIR)" M="$(ABS_KMOD_OUTPUT_DIR)" clean >/dev/null 2>&1 || true
+ @echo "Cleaning: $(KMOD_OUTPUT_DIR)"
+ @rm -rf -- "$(KMOD_OUTPUT_DIR)"
--- /dev/null
+# make/target_lib_CLI.mk — build *.lib.c and *.CLI.c
+# written for the Harmony skeleton, always invoked from cwd $REPO_HOME/<role>
+# files have two suffixes by convention, e.g.: X.lib.c or Y.CLI.c
+
+.SUFFIXES:
+.DELETE_ON_ERROR:
+
+#--------------------------------------------------------------------------------
+# defaults for environment variables
+
+C ?= gcc
+CFLAGS ?=
+C_SOURCE_DIR ?= cc
+LIBRARY_FILE ?=
+MACHINE_DIR ?= scratchpad/machine
+LN_FLAGS ?=
+
+#--------------------------------------------------------------------------------
+# derived variables
+
+# source discovery (single dir)
+c_source_lib := $(wildcard $(C_SOURCE_DIR)/*.lib.c)
+c_source_exec := $(wildcard $(C_SOURCE_DIR)/*.CLI.c)
+
+# remove suffix to get base name
+c_base_lib := $(sort $(patsubst %.lib.c,%, $(notdir $(c_source_lib))))
+c_base_exec := $(sort $(patsubst %.CLI.c,%, $(notdir $(c_source_exec))))
+
+# two sets of object files, one for the lib, and one for the CLI programs
+object_lib := $(patsubst %, scratchpad/%.lib.o, $(c_base_lib))
+object_exec := $(patsubst %, scratchpad/%.CLI.o, $(c_base_exec))
+
+# executables are made from exec_ sources
+exec_ := $(patsubst %, $(MACHINE_DIR)/%, $(c_base_exec))
+
+#--------------------------------------------------------------------------------
+# pull in dependencies
+
+-include $(object_lib:.o=.d) $(object_exec:.o=.d)
+
+
+#--------------------------------------------------------------------------------
+# targets
+
+# when no target is given make uses the first target, this one
+.PHONY: usage
+usage:
+ @echo example usage: make clean
+ @echo example usage: make library
+ @echo example usage: make CLI
+ @echo example usage: make library CLI
+
+.PHONY: version
+version:
+ @echo makefile version 7.1
+ if [ ! -z "$(C)" ]; then $(C) -v; fi
+ /bin/make -v
+
+.PHONY: information
+information:
+ @printf "· → Unicode middle dot — visible: [%b]\n" "·"
+ @echo "C_SOURCE_DIR: " $(C_SOURCE_DIR)
+ @echo "c_source_lib: " $(c_source_lib)
+ @echo "c_source_exec: " $(c_source_exec)
+ @echo "c_base_lib: " $(c_base_lib)
+ @echo "c_base_exec: " $(c_base_exec)
+ @echo "object_lib: " $(object_lib)
+ @echo "object_exec: " $(object_exec)
+ @echo "exec_: " $(exec_)
+
+.PHONY: library
+library: $(LIBRARY_FILE)
+
+$(LIBRARY_FILE): $(object_lib)
+ @if [ -s "$@" ] || [ -n "$(object_lib)" ]; then \
+ echo "ar rcs $@ $^"; \
+ ar rcs $@ $^; \
+ else \
+ rm -f "$@"; \
+ fi
+
+#.PHONY: CLI
+#CLI: $(LIBRARY_FILE) $(exec_)
+
+.PHONY: CLI
+CLI: library $(exec_)
+
+
+# generally better to use the project local clean scripts, but this will make it so that the make targets can be run again
+
+.PHONY: clean
+clean:
+ rm -f $(LIBRARY_FILE)
+ for obj in $(object_lib) $(object_exec); do rm -f $$obj $${obj%.o}.d || true; done
+ for i in $(exec_); do [ -e $$i ] && rm $$i || true; done
+
+
+# recipes
+scratchpad/%.o: $(C_SOURCE_DIR)/%.c
+ $(C) $(CFLAGS) -o $@ -c $<
+
+$(MACHINE_DIR)/%: scratchpad/%.CLI.o
+ mkdir -p $(MACHINE_DIR)
+ $(C) -o $@ $< $(LN_FLAGS)
+
+++ /dev/null
-#!/usr/bin/env bash
-set -euo pipefail
-
-# test_routing.sh
-# Sends mock HTTP requests to the local unix socket to verify domain routing.
-
-SOCKET_FP="../user/release/scratchpad/network_interface/RT_server.sock"
-
-if [ ! -S "${SOCKET_FP}" ]; then
- echo "Error: Socket not found at ${SOCKET_FP}" >&2
- echo "Make sure the HTTP_server.js process is running in the user workspace." >&2
- exit 1
-fi
-
-echo "=== Testing Reasoning Technology domain ==="
-curl --unix-socket "${SOCKET_FP}" \
- -H "Host: x6.reasoningtechnology.com" \
- http://localhost/
-
-echo -e "\n\n=== Testing Thomas Walker Lynch domain ==="
-curl --unix-socket "${SOCKET_FP}" \
- -H "Host: x6.thomas-walker-lynch.com" \
- http://localhost/
-
-echo -e "\n\n=== Testing Unknown domain ==="
-curl --unix-socket "${SOCKET_FP}" \
- -H "Host: nonexistent-domain.com" \
- http://localhost/
projects / Harmony / commitdiff