--- /dev/null
+# Normalize line endings for a cross-platform dev team
+* text=auto eol=lf
+
+# Common sources/scripts
+*.sh eol=lf
+*.bash eol=lf
+*.py eol=lf
+*.org linguist-language=Org
+*.md linguist-language=Markdown
+*.c linguist-language=C
+*.cc linguist-language=C++
+
+# RT file-type conventions (classify custom suffixes correctly)
+*.lib.c linguist-language=C
+*.cli.c linguist-language=C
+*.lib.cc linguist-language=C++
+*.cli.cc linguist-language=C++
+
+# Keep empty-dir sentinels and build scratch out of release archives
+**/.githolder export-ignore
+scratchdir/ export-ignore
+
+# Housekeeping not needed in source releases
+.gitignore export-ignore
+.editorconfig export-ignore
+
+# Treat license templates as text (and include them by default)
+LICENSES/* text
+document/licenses/* text
- # Harmony
+# Harmony — RT project skeleton
-## About
+Tiny, opinionated starter project skeleton that we use across RT projects independent of language being coded.
-This is an RT project skeleton. There are a few files from a tentative project here, that service as either an example or hinderence.
+Pick a role, source the env, build your thing, then release.
-Source one of these evironment files depending on the role being played when entering the project:
+## Roles (source these, don’t execute)
+- `env_developer` — dev workflow
+- `env_tester` — test + repro
+- `env_toolsmith` — shared tools + env wiring
-- env_developer - for code developer role
-- env_tester - for tester role
-- env_toolsmith - for the toolsmith role
+Developers work under `developer/`, testers under `tester/`, toolsmiths wire `tool_shared/` and env scripts.
-developers work out of the 'developer' directory
-testers work out of the 'tester' direcgtory
-toolsmthis set up 'tool_shared' and the various env scripts.
+## Layout (why it exists)
+- `document/` — project docs (+ RT conventions in org)
+- `developer/` — dev code, experiments, dev-specific docs/tools
+- `tester/` — tests, fixtures, repro steps
+- `tool_shared/` — shared tools/env for all roles
+- `tool_shared/third_party/` — third-party tools
+- `tool_shared/third_party/python/` — your venv lives here (not committed)
+- `release/` — publishable artifacts
+- `tmp/` — scratch (gitignored)
-document/ - for project documents
-developer/document/ - documents specifically concerning development
-developer/tool/ - tools specific for development
+Empty directories are tracked with `.githolder` (kept out of release archives).
-tool_shared/ for tools shared by mulitple roles.
-tool_shared/third_party for third party tools. For example, if you are going to install Python, put the virtual environment in this directoy under the name 'Python' and set a search path to it under `env_developer` or whereever it gets used from.
+## Quick start
+```bash
+# choose a role (must be sourced)
+source ./env_developer # or env_tester / env_toolsmith
-See other projects for examples. Ariadne or Mosaic projects might be good examples. Note we no longer using the 🖉 to mark authored content.
+# create the Python venv under tool_shared/third_party/python/ (literally 'python' instead of 'venv'
+./scripts/python_venv_bootstrap.sh
-## License
+# re-enter later
+source ./env_developer
+
+# where used
+
+In public projects, this structure has been used with Python, Java, C, C++, and Lisp projects.
+
+Note the related https://github.com/Thomas-Walker-Lynch/RT-project-share project. It has the generic makefile used on C/C++ projects and other shared tools. Note the project https://github.com/Thomas-Walker-Lynch/RT_gcc for a more fully featured cpp. Note the projects https://github.com/Thomas-Walker-Lynch/Mosaic, and https://github.com/Thomas-Walker-Lynch/Mosaic for Java examples of this project skeleton being used for a Java testing and dependency grapph build tool, respectively.
-Harmoy is not distributed with an MIT license. However, projects that
-use the Harmony skeleton might be distrbuted under other licenses. See the directory document/license for a nonexculsive list of other licenses that a project that mekes use of the Harmony skeleton might make use of.
\ No newline at end of file
--- /dev/null
+/home/Thomas/subu_data/developer/project/RT/RT-project-share/document🖉/
\ No newline at end of file
--- /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
+* Project Workflow
+
+
+This document outlines the responsibilities of different roles in the project and the release process.
+
+** 1. Project Administrator
+ - Download the project from GitHub.
+ - Install the required tools.
+ - Explain workflows and file locations to project members.
+ - Manage Major and Minor Releases.
+
+** 2. Developer
+ - From the `Harmony/` directory, run:
+ #+begin_src sh
+ source env_developer
+ #+end_src
+ to set up the developer environment.
+ - Build the project:
+ #+begin_src sh
+ make
+ #+end_src
+ - Copy relevant files to the release directory:
+ #+begin_src sh
+ release
+ #+end_src
+ - The tester will evaluate the release candidate.
+
+** 3. Tester
+ - From the `Harmony/` directory, set up the testing environment:
+ #+begin_src sh
+ source env_tester
+ #+end_src
+ - Build and run tests:
+ #+begin_src sh
+ make
+ shell/test_<name>
+ #+end_src
+ - Alternatively, change to a test directory, source its environment, and run tests manually.
+ - The development and testing process will iterate until the release candidate is ready for an official release.
+
+** 4. Major Release
+ - The release candidate is in `$REPO_HOME/release` and has passed testing.
+ - Verify that `$REPO_HOME/tool_shared/bespoke/version` outputs the correct version information. Modify it if necessary.
+ - Create a new branch named `release_v<n>.0` where `<n>` is the major version.
+ - Rename the release directory to `$REPO_HOME/release_v<n>.0` and create a new empty `$REPO_HOME/release/` directory.
+
+** 5. Minor Release
+ - Urgent changes to a major release are made on its corresponding branch.
+ - The developer makes edits, and the tester evaluates the release candidate as usual.
+ - The `version` program is updated.
+ - Rename the release directory to `release_v<n>.<m>`, where `<m>` is the minor version.
+ - Merge changes into `core_developer_branch` if necessary.
+
+** 6. Tips
+ - If acting in multiple roles (developer, tester, admin), keep separate terminal shells for each role to avoid misconfigurations.
--- /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
+* 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
+### Work Flow
+
+#### 1. Project Administrator
+
+1.1. Download the project from GitHub.
+1.2. Install the required tools.
+1.3. Explain the workflows and where things are located to project members.
+1.4. Perform Major and Minor Release administration.
+
+#### 2. Developer
+
+2.1. From the Harmony directory, run `> source env_developer` to set up the
+ developer environment.
+2.2. Use `> make` to build the project, and `> release` to copy relevant files
+ to `$REPO_HOME/release` for testing.
+2.3. The tester will test the release candidate.
+
+#### 3. Tester
+
+3.1. From the Harmony directory, run `> source env_tester` to set up the tester
+ environment.
+3.2. Use `> make` to build the tests, and `> shell/test_<name>` to run a test.
+ Alternatively, you can cd into one of the test directories, source the
+ environment for that test, and run it manually.
+3.3. Testing and development will likely iterate until the release candidate is
+ ready to be turned into a versioned release.
+
+#### 4. Major Release
+
+4.1. The release candidate is located in the `$REPO_HOME/release` directory and
+ has passed testing.
+4.2. Check that the program `$REPO_HOME/tool_shared/bespoke/version` outputs the
+ correct information. If necessary, modify it.
+4.3. A new branch is created in the project for the release, named
+ `release_v<n>.0`, where `v<n>.0` is the version number from the `version`
+ program. The minor version number is set to zero (`.0`), and it is assumed
+ that this will be the case after each major release.
+4.4. Rename the release directory to `$REPO_HOME/release_v<n>.0`, and create a
+ new empty `$REPO_HOME/release` directory. The new empty release directory
+ can be used by developers who download the project and make local edits, as
+ the build scripts target this directory.
+
+#### 5. Minor Release
+
+If urgent changes need to be made to the most recent major release, these edits
+should be made on the corresponding major release branch. The developer makes
+the edits, and the tester tests the release candidate as usual. The `version`
+program is updated. Once the release candidate is finalized, rename the
+directory to `release_v<n>.<m>`, where `<m>` is the minor version number. If
+needed, merge the changes into the `core_developer_branch`.
+
+---
+
+### Tips:
+
+- If you are acting in multiple roles (e.g., developer, tester, and project
+ administrator), keep separate terminal shells open for each role. This way,
+ the environment will remain correctly configured for the tasks related to
+ each role.
--- /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
+# 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
+
+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