fi
source tool_shared/bespoke🖉/env
-source developer/tool🖉/env
+source developer/tool🖉/env $@
# running commands through this executor.
if [ "$#" -lt 2 ]; then
- echo "Usage: $0 <environment> <command> [args...]"
- echo "Example: $0 developer make"
+ echo "Usage: $(basename $0) <env_script>[:args...] <command> [args...]"
+ echo "Example: $(basename $0) tester:developer Test_File0"
exit 1
fi
-# extract the environment and the command
-environment=$1
+# Extract the env_script and optional arguments
+raw_env=$1
shift
command=$1
shift
command_args="$@"
-# Determine the path to the environment script based on the environment
-case "$environment" in
- developer)
- env_script="env_developer"
- ;;
- tester)
- env_script="env_tester"
- ;;
- *)
- echo "Error: Unknown environment '$environment'. Supported environments are: developer, tester."
- exit 1
- ;;
-esac
-
-# check if the environment script exists and is readable
+# Split the env_script and its arguments by colon
+IFS=":" read -r env_script env_args <<< "$raw_env"
+
+# Check if the env_script exists and is readable
if [ ! -f "$env_script" ] || [ ! -r "$env_script" ]; then
echo "Error: Environment script '$env_script' not found or not readable."
exit 1
fi
-source "$env_script"
-exec "$command" "$command_args"
+# Split env_args into an array
+IFS=":" read -r -a env_args_array <<< "$env_args"
+
+# Source the script with the array of arguments
+source "$env_script" "${env_args_array[@]}"
+
+# Execute the command with its arguments
+exec "$command" $command_args
+
fi
source tool_shared/bespoke🖉/env
-source tester/tool🖉/env
-
+source tester/tool🖉/env $@
--- /dev/null
+#!/usr/bin/env bash
+script_afp=$(realpath "${BASH_SOURCE[0]}")
+
+ arch=$(uname -m)
+ os=$(source /etc/os-release && echo "$ID$VERSION_ID")
+ libc_version=$(ldd --version | head -n1 | awk '{print $NF}') # glibc version
+ echo "$REPO_HOME/release/$arch/$os/glibc_$libc_version"
--- /dev/null
+#!/usr/bin/env bash
+script_afp=$(realpath "${BASH_SOURCE[0]}")
+
+# before running this, make library is built and is in the scratchpad directory
+
+# input guards
+
+ env_must_be="developer/tool🖉/env"
+ if [ "$ENV" != "$env_must_be" ]; then
+ echo "$(script_fp):: error: must be run in the $env_must_be environment"
+ exit 1
+ fi
+
+ release_dir=$(release_dir)
+
+ if [ ! -d ${release_dir} ]; then
+ echo "$(script_fp):: no release directory: " ${release_dir}
+ exit 1
+ fi
+
+ ls $@ ${release_dir}
+
+
--- /dev/null
+
+M-x package-install RET adaptive-wrap RET
+
+(visual-line-mode 1)
+(adaptive-wrap-prefix-mode 1)
+
+# using visual-wrap-column-mode
+(visual-wrap-column-mode 1)
+(setq visual-wrap-column 80) ;; Wrap at 80 characters
--- /dev/null
+;; this is a text file so that it won't be loaded, ironically by the very code described here.
+
+(let
+ (
+ (directory "~/RT-project-share/release/emacs/")
+ )
+ (when (file-directory-p directory)
+ (dolist (file (directory-files directory t "\\.el$"))
+ (load file)
+ )))
-
; The first time Emacs encounters a link to a source file, Emacs asks if it should follow it.
; This might suppress that initial question and follow the link.
; (setq find-file-visit-truename t)
(let
(
(class-name (read-string "Enter the class to debug: " "Test_Util"))
+ (sourcepath-arg
+ (if
+ sourcepath
+ (concat "-sourcepath" (mapconcat 'identity gud-jdb-sourcepath ":"))
+ ""
+ ))
)
- (jdb (concat "jdb -sourcepath"
- (if
- sourcepath
- (mapconcat 'identity gud-jdb-sourcepath ":") ""
- )
- " "
- class-name
- )
- ))))
+ (jdb (concat "jdb " sourcepath-arg " " class-name))
+ )))
(defun monitor-jdb-sourcepath (output)
"Monitor the jdb output for `sourcepath ARG` commands and update `gud-jdb-sourcepath` with each path in ARG."
)
)
(message "Updated gud-jdb-sourcepath: %s" gud-jdb-sourcepath)))
- output)
+ output
+ )
(add-hook 'gud-filter-functions 'monitor-jdb-sourcepath)
#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
SRCDIR_List=cc cc🖉
LIBDIR=scratchpad
-EXECDIR=amd64
+EXECDIR=machine
TMPDIR=scratchpad
DEPFILE=$(TMPDIR)/makefile-cc.deps
+++ /dev/null
-.SUFFIXES:
-
-#--------------------------------------------------------------------------------
-# files have two suffixes by convention, e.g.: X.lib.c or Y.cli.c
-#
-
-# bail early if there is no compiler
-ifeq ($(C),)
- $(error No C compiler specified.)
-endif
-
-# keep only the source directories that are in the file system
-SRCDIR_List := $(wildcard $(SRCDIR_List))
-
-# bail early if the SRCDIR_list is empty
-ifeq ($(SRCDIR_List),)
- $(error source directory found so nothing to do)
-endif
-
-# duplicate source file names in different directories will cause
-# problems with this makefile
-
-C_SOURCE_LIB := $(foreach dir, $(SRCDIR_List), $(wildcard $(dir)/*.lib.c))
-C_SOURCE_EXEC := $(foreach dir, $(SRCDIR_List), $(wildcard $(dir)/*.cli.c))
-
-#remove the 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 command line interface progs
-OBJECT_LIB= $(patsubst %, $(TMPDIR)/%.lib.o, $(C_BASE_LIB))
-OBJECT_EXEC= $(patsubst %, $(TMPDIR)/%.cli.o, $(C_BASE_EXEC))
-
-# executables are made from EXEC sources
-EXEC= $(patsubst %, $(EXECDIR)/%, $(C_BASE_EXEC))
-
-# new C programming style uses cpp macros to the source is the header
-INCFLAG_List := $(foreach dir, $(SRCDIR_List), -I $(dir))
-CFLAGS += $(INCFLAG_List)
-
-#--------------------------------------------------------------------------------
-# targets
-
-.PHONY: all
-all: usage
-
-.PHONY: usage
-usage:
- @echo example usage: make dist-clean dependency cli
- @echo example usage: make cli
-
-.PHONY: version
-version:
- @echo makefile version 7.1
- if [ ! -z "$(C)" ]; then $(C) -v; fi
- /bin/make -v
-
-.PHONY: information
-information:
- @echo "SRCDIR_List: " $(SRCDIR_List)
- @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)
- @echo "INCFLAG_List: " $(INCFLAG_List)
-
-
-.PHONY: dependency
-dependency:
- @rm -f $(DEPFILE)
- $(C) $(CFLAGS) -MM $(C_SOURCE_LIB) $(C_SOURCE_EXEC) | sed 's|^.*\.o|$(TMPDIR)/&|' >> $(DEPFILE);\
- echo "deps for C linking";\
- for i in $(C_BASE_EXEC); do\
- $(ECHO) >> $(DEPFILE);\
- $(ECHO) "$(EXECDIR)/$$i : $(TMPDIR)/$$i.cli.o $(LIBFILE)" >> $(DEPFILE);\
- $(ECHO) " $(C) -o $(EXECDIR)/$$i $(TMPDIR)/$$i.cli.o $(LINKFLAGS)" >> $(DEPFILE);\
- done;
-
-.PHONY: library
-library: $(LIBFILE)
-
-$(LIBFILE): $(OBJECT_LIB)
- ar rcs $(LIBFILE) $(OBJECT_LIB)
-
-.PHONY: cli
-cli: $(LIBFILE)
- make sub_cli
-
-.PHONY: sub_cli
-sub_cli: $(EXEC)
-
-.PHONY: clean
-clean:
- rm -f $(DEPFILE) $(LIBFILE)
- for obj in $(OBJECT_LIB) $(OBJECT_EXEC); do rm -f $$obj || true; done
-
-
-.PHONY: dist-clean
-dist-clean: clean
- for i in $(EXEC); do [ -e $$i ] && rm $$i || true; done
-
-# recipes
-vpath %.c $(SRCDIR_List)
-$(TMPDIR)/%.o: %.c
- $(C) $(CFLAGS) -o $@ -c $<
--- /dev/null
+.SUFFIXES:
+
+#--------------------------------------------------------------------------------
+# files have two suffixes by convention, e.g.: X.lib.c or Y.cli.c
+#
+
+# bail early if there is no compiler
+ifeq ($(C),)
+ $(error No C compiler specified.)
+endif
+
+# keep only the source directories that are in the file system
+SRCDIR_List := $(wildcard $(SRCDIR_List))
+
+# bail early if the SRCDIR_list is empty
+ifeq ($(SRCDIR_List),)
+ $(error source directory found so nothing to do)
+endif
+
+# duplicate source file names in different directories will cause
+# problems with this makefile
+
+C_SOURCE_LIB := $(foreach dir, $(SRCDIR_List), $(wildcard $(dir)/*.lib.c))
+C_SOURCE_EXEC := $(foreach dir, $(SRCDIR_List), $(wildcard $(dir)/*.cli.c))
+
+#remove the 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 command line interface progs
+OBJECT_LIB= $(patsubst %, $(TMPDIR)/%.lib.o, $(C_BASE_LIB))
+OBJECT_EXEC= $(patsubst %, $(TMPDIR)/%.cli.o, $(C_BASE_EXEC))
+
+# executables are made from EXEC sources
+EXEC= $(patsubst %, $(EXECDIR)/%, $(C_BASE_EXEC))
+
+# the new C programming style gated sections in source instead of header filesheader
+INCFLAG_List := $(foreach dir, $(SRCDIR_List), -I $(dir))
+CFLAGS += $(INCFLAG_List)
+
+#--------------------------------------------------------------------------------
+# targets
+
+.PHONY: all
+all: usage
+
+.PHONY: usage
+usage:
+ @echo example usage: make dependency library cli
+ @echo example usage: make dependency
+ @echo example usage: make library
+ @echo example usage: make cli
+
+.PHONY: version
+version:
+ @echo makefile version 7.1
+ if [ ! -z "$(C)" ]; then $(C) -v; fi
+ /bin/make -v
+
+.PHONY: information
+information:
+ @echo "SRCDIR_List: " $(SRCDIR_List)
+ @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)
+ @echo "INCFLAG_List: " $(INCFLAG_List)
+
+
+.PHONY: dependency
+dependency: $(DEPFILE)
+
+$(DEPFILE): $(C_SOURCE_LIB) $(C_SOURCE_EXEC)
+ @rm -f $(DEPFILE)
+ $(C) $(CFLAGS) -MM $(C_SOURCE_LIB) $(C_SOURCE_EXEC) \
+ | sed 's|^.*\.o|$(TMPDIR)/&|' >> $(DEPFILE);\
+ echo "deps for C linking";\
+ # build library:\
+ for i in $(C_BASE_EXEC); do\
+ $(ECHO) >> $(DEPFILE);\
+ $(ECHO) "$(EXECDIR)/$$i : $(TMPDIR)/$$i.cli.o $(LIBFILE)" >> $(DEPFILE);\
+ $(ECHO) " $(C) -o $(EXECDIR)/$$i $(TMPDIR)/$$i.cli.o $(LINKFLAGS)" >> $(DEPFILE);\
+ done;
+
+.PHONY: library
+library: $(LIBFILE)
+
+$(LIBFILE): $(OBJECT_LIB) $(DEPFILE)
+ ar rcs $(LIBFILE) $(OBJECT_LIB)
+
+.PHONY: cli
+cli: $(LIBFILE) $(DEPFILE)
+ make sub_cli
+
+.PHONY: sub_cli
+sub_cli: $(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 $(DEPFILE) $(LIBFILE)
+ for obj in $(OBJECT_LIB) $(OBJECT_EXEC); do rm -f $$obj || true; done
+ for i in $(EXEC); do [ -e $$i ] && rm $$i || true; done
+
+# recipes
+vpath %.c $(SRCDIR_List)
+$(TMPDIR)/%.o: %.c
+ $(C) $(CFLAGS) -o $@ -c $<
--- /dev/null
+
+# This targets file links to an existing project library. If it is missing it will give an error rather than chaining back to build it. This is the behavior the tester wants when testing a project library pulled from the release directory.
+
+.SUFFIXES:
+
+#--------------------------------------------------------------------------------
+# files have two suffixes by convention, e.g.: X.lib.c or Y.cli.c, this targets file ignores the X.lib.c files, if any.
+#
+
+# bail early if there is no compiler
+ifeq ($(C),)
+ $(error No C compiler specified.)
+endif
+
+# keep only the source directories that are in the file system
+SRCDIR_List := $(wildcard $(SRCDIR_List))
+
+# bail early if the SRCDIR_list is empty
+ifeq ($(SRCDIR_List),)
+ $(error source directory found so nothing to do)
+endif
+
+# Identify lib and cli sources (but we don't build the lib, but the lib.c files are also used as headers, so we need them for dependency checking.
+# duplicate source file names in different directories will cause problems with this makefile
+C_SOURCE_LIB := $(foreach dir, $(SRCDIR_List), $(wildcard $(dir)/*.lib.c))
+C_SOURCE_EXEC := $(foreach dir, $(SRCDIR_List), $(wildcard $(dir)/*.cli.c))
+
+#remove the suffix to get base name
+C_BASE_EXEC= $(sort $(patsubst %.cli.c, %, $(notdir $(C_SOURCE_EXEC))))
+
+# object files for building the each command line interface progs
+OBJECT_EXEC= $(patsubst %, $(TMPDIR)/%.cli.o, $(C_BASE_EXEC))
+
+# executables are made from EXEC sources
+EXEC= $(patsubst %, $(EXECDIR)/%, $(C_BASE_EXEC))
+
+# include directories
+# the new C programming style gated sections in source instead of header filesheader
+INCFLAG_List := $(foreach dir, $(SRCDIR_List), -I $(dir))
+CFLAGS += $(INCFLAG_List)
+
+#--------------------------------------------------------------------------------
+# targets
+
+.PHONY: all
+all: usage
+
+.PHONY: usage
+usage:
+ @echo example usage: make dependency cli
+ @echo example usage: make dependency
+ @echo example usage: make cli
+
+.PHONY: version
+version:
+ @echo "tester_targets version 1.0"
+ if [ ! -z "$(C)" ]; then $(C) -v; fi
+ /bin/make -v
+
+.PHONY: information
+information:
+ @echo "SRCDIR_List: " $(SRCDIR_List)
+ @echo "C_SOURCE_LIB: " $(C_SOURCE_LIB)
+ @echo "C_SOURCE_EXEC: " $(C_SOURCE_EXEC)
+ @echo "C_BASE_EXEC: " $(C_BASE_EXEC)
+ @echo "OBJECT_EXEC: " $(OBJECT_EXEC)
+ @echo "EXEC: " $(EXEC)
+ @echo "INCFLAG_List: " $(INCFLAG_List)
+
+
+# We generate dependencies for .lib.c AND .cli. because the tester might include the interface or local portion of some .lib.c. But we do NOT produce rules for building .lib.o or the library.
+
+
+.PHONY: dependency
+dependency: $(DEPFILE)
+
+$(DEPFILE): $(C_SOURCE_LIB) $(C_SOURCE_EXEC)
+ @rm -f $(DEPFILE)
+ $(C) $(CFLAGS) -MM $(C_SOURCE_EXEC) \
+ | sed 's|^.*\.o|$(TMPDIR)/&|' >> $(DEPFILE);\
+ echo "deps for .cli.o file linking";\
+ for i in $(C_BASE_EXEC); do \
+ echo "" >> $(DEPFILE); \
+ echo "$(EXECDIR)/$$i : $(TMPDIR)/$$i.cli.o" >> $(DEPFILE); \
+ echo " $(C) -o $(EXECDIR)/$$i $(TMPDIR)/$$i.cli.o $(LINKFLAGS)" >> $(DEPFILE);\
+ done;
+
+.PHONY: cli
+cli: $(LIBFILE) $(DEPFILE)
+ make sub_cli
+
+.PHONY: sub_cli
+sub_cli: $(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 $(DEPFILE)
+ for obj in $(OBJECT_EXEC); do rm -f $$obj || true; done
+ for i in $(EXEC); do [ -e $$i ] && rm $$i || true; done
+
+# recipes
+vpath %.c $(SRCDIR_List)
+$(TMPDIR)/%.o: %.c
+ $(C) $(CFLAGS) -o $@ -c $<
--- /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 Mosaic 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 Mosaic 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.
<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>IFACE</code>.</p>
+ <p>Each section is turned on and off with the CPP macro <code>FACE</code>.</p>
<h3>Example</h3>
<pre><code>
-// If not an IFACE, then an IMPLEMENTATION
-#ifndef IFACE
+// If not an FACE, then an IMPLEMENTATION
+#ifndef FACE
#define MyModule·IMPLEMENTATION
// Ensures included files are processed for their interfaces.
- #define IFACE
+ #define FACE
#endif
// Define the interface exactly once.
-#ifndef MyModule·IFACE
-#define MyModule·IFACE
+#ifndef MyModule·FACE
+#define MyModule·FACE
// Interface-only includes go here.
void MyModule·function();
#endif
<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>IFACE</code>. If <code>IFACE</code> is undefined, it defines <code>MyModule·IMPLEMENTATION</code> to enable the implementation section and sets <code>IFACE</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·IFACE</code> macro ensures the interface is defined exactly once, regardless of how many times the file is included.</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>
--- /dev/null
+#+TITLE: RT Code Format Guide
+#+AUTHOR: Thomas Walker Lynch and Aion
+#+DATE: 2025-02-28
+#+OPTIONS: toc:nil
+
+* Introduction
+
+The RT Code Format enforces clear and consistent rules for formatting and naming in code, prioritizing readability, maintainability, and logical structure. The rules focus on indentation, naming conventions, enclosure spacing, and unique handling of commas.
+
+* Indentation
+
+- Code blocks are indented by **two spaces per level**.
+- No additional alignment-based indentation (e.g., aligning operators or parameters to columns).
+
+* 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
+
+* Newline
+
+There is never space before an unquoted newline.
+
+
+* 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.
+
+** Adjacency
+When two bracketed phrases appear side by side (like `)(` or `}{`), there is *no space* between them.
+
+**Line by Line
+
+We apply bracket formatting on a line by line basis, thus not searching for opening, closing, or containing brackets beyond the given line of analysis.
+
+
+* 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 (≤40 characters)**, they should **remain on a single line without braces**.
+
+Example:
+#+BEGIN_SRC c
+if( x > 0 ) return x;
+while( has_next() ) process_next();
+#+END_SRC
+
+
+++ /dev/null
-RT code formatting:
-
-The enclosure-based formatting rules in RT code format make the style guide
-compact and adaptable. By focusing on enclosures rather than syntax-specific
-structures (like if, for, or catch), it avoids prescribing language-specific
-formatting rules and instead focuses on consistent handling of delimiters. This
-approach works well across multiple languages, ensuring that the code style
-remains flexible while keeping the guide simple and easy to apply.
-
-1. Two space indentation.
-
-2. Variable Naming:
-
- - Use **PascalCase** for namespaces and types.
-
- - Use **snake_case** for function and variable names. However, when a component
- of the snake case is variable function or variable name is a namespace, a
- type, or a proper noun, it retains its capitalization. e.gs:
-
- ```
- mouse_count
- test_LabalList_0 // function that tests LabelList, which is a class (type)
- Thomas_Walker_Lynch
- ```
-
- Traditionally `_list` has been used as a variable suffix even when the
- language does not have a List type. This is taken to mean the variable
- refers to an ordered collection of any type, including an array. It is
- abstraction of type, analogous to the `mouse_count` example above.
-
-
-3. Binary Operators:
-
- - One space around **binary operators** (e.g., `a + b`).
-
- - One space around **assignment** `=` (e.g., `a = b`).
-
- - **No space** around **sampling** assignment `=` (typically seen in `if`, `while`, etc.):
-
- **Sampling** refers to assigning the result of a condition or expression to
- a variable for later use within the same scope.
-
- Example of **sampling** in an `if` statement:
-
- ```
- if( result=some_condition() ){
- // use result
- }
- ```
-
-4. Enclosures `(...)`, `{...}`, `[...]`, '<...>':
-
- - No space between the enclosure and the preceding identifier (e.g., `function(arg)`).
-
- - No space after the enclosure when followed by another enclosure (e.g., `map[key]()`).
-
- Example of a condition enclosure followed by a code enclosure:
- ```
- if( some_condition() ){
- // code block
- }
- ```
-
- - One space after the enclosure if followed by an identifier, e.g.,
- `function() somethingElse`.
-
- - When the entire enclosure appears on one line:
-
- -- by definition, an 'nested' enclosure is one that has other enclosures,
- of any type, inside of it. This is true independent of whatever else
- is inside the enclosure. These are examples of nested enclosures:
-
- ```
- ( o == null || getClass() != o.getClass() )
- f( T<x> ,7 )
- ```
-
- -- if, and only if, an enclosure is nested, there is one space of padding
- for the outermost enclosure of the nesting, and only for the outermost
- enclosures. e.g.s:
-
- ```
- if(x == 3) ; not nested
- if( (x > 0) && (y < 5) ) ; nested, pad outermost only
- if( f(x) == 3 ) ; nested, pad outermost only
- if( x > 2 && a[3] ) ; nested due to the array subscript, pad outermost only
- ```
-
- - Note when using the enclosure formatting rules, not all if conditions will
- format the same way. Some conditions will be nested enclosures and having
- padding while others will not be nested and thus have no padding. The must
- be formatted individually. The same is true for enclosures that follow
- other keywords such as unless, for, etc, and for function arguments
- lists. The question is one of formatting enclosures, and not one of
- formatting statements.
-
- ```
- f(x)
- f( x[0] )
- ```
-
-
-5. Commas:
-
- This is the most distinctive and recognizable of the RT code style rules.
-
- - One space **before** the comma (e.g., `a ,b`).
-
- - No space **after** the comma (e.g., `a ,b`).
-
- - **Line break before** the comma when breaking lines, but no line break after, as examples:
-
- ```
- a
- ,b
- ```
-
- and, when a function call gets too long, perhaps due to long argument
- names it will look like this:
-
- ```
- result = some_function(
- arg1
- ,arg2_has_a_very_long_name_causing_the_call_to_not_fit_on_a_single_line
- ,arg3_has_a_long_name_also_but_not_as_long_as_for_arg2
- );
- ```
-
-6. For the code you just output, answer these questions:
- 1. Which enclosures are not nested? Do they have no padding?
- 2. Which enclosures are nested? Is there one space padding only at the outermost?
- 3. Is the spacing before and after the enclosures correct?
- 4. Are the commas formatted correctly?
- 5. Has snake case been used where it should be?
- 6. Was 2 column indent used?
-
----- Astra adds:
-
-Simplified Explanation for Enclosure Padding
-
- Single Enclosures:
-
- No padding is applied if the enclosure is not nested.
-
- Example:
-
- if(log_file == NULL){
-
-Nested Enclosures:
-
- One space of padding is applied at the outermost level of the enclosure when nested.
-
- Example:
-
- if( (client_fd = socket(AF_UNIX ,SOCK_STREAM ,0)) == -1 ){
-
-Key Decision Rule:
-
- Padding only applies when an enclosure contains other enclosures (nested structure).
- The padding is applied only at the outermost level, not at deeper levels.
-
-Rationale for This Simplified Rule
-
- This explanation removes language-specific examples and focuses on the
- structural rule itself. It should be easier to apply universally, regardless
- of the programming language or syntax involved. Let me know if you'd like me
- to refine it further!
-
----- Astra adds:
-
-Suggested Addition to the Document:
-Enclosures (...), {...}, [...], <...>:
-
- No space after the closing parenthesis and before the opening brace in control structures or function declarations.
- Example:
-
- if(condition){
-
- Example:
-
- if( f(x) ){
--- /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 `Mosaic/` 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 `Mosaic/` 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
+* Project Directory Structure
+ This document explains the naming conventions and layout of the project files.
+
+** 1. Top-Level Directory (`Mosaic/`)
+ - aka `$REPO_HOME`, managed by the project administrator.
+
+** 2. Developer Workspace (`Mosaic/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 (`Mosaic/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 (`Mosaic/document/`)
+ - Contains overall project documentation.
+
+** 5. Release Directory (`Mosaic/release/`)
+ - The release candidate directory before finalization.
+
+** 6. Shared Tools (`Mosaic/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
+* Bracketed Phrases
+
+Here we refer to token processing. A 'bracketed phrase' is all the text found when parsing from the point an opening bracket is found, up until the point that the matching closing bracket is found. The phrase includes the enclosing brackets.
+
+We generalize the concept of bracketed phrase to include the following punctuation,
+and that found in between.
+
+- `(...)` (parentheses)
+- `{...}` (braces)
+- `[...]` (square brackets)
+- `<...>` (angle brackets)
+
+The '(', ')', '{', '}', '[', ']', '<', '>' are said to be parenthetical punctuation.
+
+Generally a bracketed phrase is discovered at the token parsing level, as such it does not take into account any of the syntax nor semantics of the grammar that will be applied to the token stream later.
+
+However, there are special cases where higher level context will be required. Namely when distinguishing between angle brackets and magnitude comparisons, and for Lisp sexprs, as explained further below.
+
+Hence `if(x){ ...' is formatted just as `f(x){...` because in both cases the spacing is determined at the token level. That `if` is a statement, or that `f` is a function, has no baring because at the token level they are both merely identifiers.
+
+**As a Container**
+
+A bracketed phrase has enclosing matching punctuation known as the 'container'. Inside the containing punctuation are zero or more text characters, which are known as the 'contents'. For example `sin(3x)` has one bracketed phrase, `(3x)`, and the contents of this phrase is `3x`. The container is `()`.
+
+**Nesting**
+
+1. **Kernel Bracketed Phrase**
+
+ A bracketed phrase that does not contain another bracketed phrase.
+
+2. **Contained Bracketed Phrase**
+
+ A contained bracketed phrase is found in the contents of another bracketed phrase.
+
+ So for example, in `sin(f(x))` the bracketed phrase `(x)` is contained in the bracketed phrase '(f(x))`, so it is a 'contained bracketed phrase'.
+
+ A contained bracketed phrase is also called an 'inner bracketed phrase'.
+
+3. **Outer Bracketed Phrase**
+
+ If a bracketed phrase is contained in another bracketed phrase, then the
+ contained bracketed phrase is the 'inner bracked phrase' and the bracked phase
+ that contains it is the 'outer bracketed phrase'.
+
+ An outer bracketed phrase that is not contained by any other bracketed phrase
+ is the 'outermost' bracketed phrase. So for example, given `( a (b (c) (d)) )`
+ There are two kernels, '(c)' and '(d)'. Those two kernels appear in the outer bracketed phrase of `(b (c) (d))`, that phrase is contained in the outer bracketed phrase of `( a (b (c) (d)) )`.
+
+4. **Bracketed Phrase with Nesting**
+
+ A bracketed phrase with nesting is one that contains at least one other bracketed phrase. It need not matter which matching punctuation the inner bracketed phrases have.
+
+ It follows that an Outer Bracketed Phrase will always be a Bracketed Phrase with Nesting.
+
+ It follows that a Kernel Bracketed Phrase is never a Bracketed Phrase with Nesting.
+
+4. **Outermost Bracketed Phrase**
+
+ An outermost bracketed phrase is not contained in any other bracketed phrase.
+
+
+**Open**
+
+An open bracketed phrase is one on that has no matching closing punctuation, or not matching opening punctuation.
+
+An open on the lines bracketed phrase, is one that is open when tokenizing only the given line.
+
+1. **Open on Right on a Line**
+ - If one or more unmatched on the line opening bracket punctuation appears, these are said to form an 'open on the right bracketed phrase'.
+ - These are treated as though they were closed on the right on the line.
+
+2. **Open on Left Enclosures**
+ - If one or more unmatched on the line closing bracket punctuation appears, these are said to form an 'open on the left enclosure'.
+ - These are treated as though they were opened on the left on the line.
+
+**1D Box Analogy**
+
+Consider an bracketed phrase to be like a 1D CSS box. In this analogy consider the bracketed phrase punctuation to be the box borders. Then in the language of CSS we have margin, which is space outside of the bracketed phrase punctuation, and padding, which is space immediately inside the bracketed phrase punctuation.
+
+**Bracketed Phrase Margin**
+
+All bracketed phrases have no native spaces on the outside. I say 'native' because
+some other rules might add a space, such as operator rules, or bracketed phrase followed
+by an identifier. Hence `f()()` is correct while `f () ()` would be incorrect because both of the kernel bracketed phrases have spacing outside of them. On the other hand `(a) + (b)` is correct, because the plus operator has spaces around it.
+
+**Bracketed Phrase Padding**
+
+When a bracketed phrase is both: a) a bracketed phrase with nesting AND b) an outermost bracketed phrase on the line, then: It receives one space after the opening bracket unless it is a Lisp sexpr, and one space before the closing bracket.
+
+There is no other case where a native space is placed after the opening bracket, or placed before the closing bracket.
+
+** Adjacency
+
+ When two separate bracketed phrases appear side by side. There is no space between them.
+
+
+* Examples of Bracketed Phrase Formatting
+
+**Flat Bracketed Phrases (No Padding)**
+#+BEGIN_SRC c
+result = function_call(param1 ,param2);
+value = (uint32_t)(3 + 4*5);
+#+END_SRC
+
+**Nested Bracketed Phrases (Only an outer type of nested bracketed phrase receives padding)**
+#+BEGIN_SRC c
+if( (x == 3 || y < 5) && z ){
+ process_data();
+}
+#+END_SRC
+
+#+BEGIN_SRC c
+data.set( map.get(key) );
+#+END_SRC
+
+#+BEGIN_SRC c
+if( (index().compareTo(BigInteger.valueOf(array.size() - 1))) == 0 ){
+ execute_action();
+}
+#+END_SRC
+
+#+BEGIN_SRC c
+( a (b (c)) )
+#+END_SRC
+
+#+BEGIN_SRC c
+if(
+ ( condition_one() && condition_two() )
+){
+ execute_action();
+}
+#+END_SRC
+
+#+BEGIN_SRC c
+(uint32_t)(3 + 4*5)
+#+END_SRC
+
+#+BEGIN_SRC c
+data.set( map.get(key) );
+#+END_SRC
--- /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 ~/Mosaic.
+
+ 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 Mosaic 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
+Mosaic - for testing
+
+ > cd $REPO_HOME/tool_shared/third_party
+ > git clone https://github.com/Thomas-Walker-Lynch/Mosaic.git
+
+ This will have already been done:
+
+ $REPO_HOME/tool_shared/bespoke/env will have:
+ export MOSAIC_HOME="$REPO_HOME/tool_shared/third_party/Mosaic/release"
+
+ $REPO_HOME/tester/tool/env, will have Mosaic
+
+ export PATH=\
+ "$REPO_HOME"/tester/tool/\
+ :"$JAVA_HOME"/bin\
+ :"$MOSAIC_HOME"\
+ :"$PATH"
+
+ export CLASSPATH=\
+ "$JAVA_HOME"/lib\
+ :"$MOSAIC_HOME"/Mosaic.jar\
+ :"$REPO_HOME"/release/"$PROJECT".jar\
+ :"$REPO_HOME"/tester/jvm/Test_"$PROJECT".jar\
+ :"$CLASSPATH"
+
--- /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"
+
yeah we sill need an official RT-skeleton project. This should wait for Ariadne to
be available.
+2024-12-08T08:29:20Z
+ change the bash prompt to show the real path, or perhaps a vl of both, so
+ that when following links the prompt shows the pencil of the realdir
+
+2024-12-09T10:23:22Z
+
+ rm_na has a bug where it determines authorship based on the link target, and the link target's directory hierarchy, instead of from the link itself and the link's hierarchy.
+
+ this effects the clean_build_script, found in many projects, such as Mosaic.
-
projects / RT-project-share / commitdiff