From: Thomas Walker Lynch Date: Tue, 26 Nov 2024 09:42:26 +0000 (+0000) Subject: puts common documents in one place, here in the resource directory X-Git-Url: https://git.reasoningtechnology.com/style/%7Bstyle.link%7D?a=commitdiff_plain;h=836f119b9c5a3c697fc7c1f2dd1bd254873eee3f;p=RT-project-share puts common documents in one place, here in the resource directory --- diff --git a/document/Java_import_as_alternative.txt b/document/Java_import_as_alternative.txt new file mode 100644 index 0000000..dda2904 --- /dev/null +++ b/document/Java_import_as_alternative.txt @@ -0,0 +1,33 @@ +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 `Mosaic` is used to help with testing and is not part of the project +being tested, when aliasing conflicts arise, it is typically the `Mosaic` 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 Mosaic library. +As a shop we are adopting this convention for all packaged java code. diff --git a/document/RT_code_format.txt b/document/RT_code_format.txt new file mode 100644 index 0000000..2d5447b --- /dev/null +++ b/document/RT_code_format.txt @@ -0,0 +1,181 @@ +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 ,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) ){ diff --git a/document/bash_name_of_script.txt b/document/bash_name_of_script.txt new file mode 100644 index 0000000..3637574 --- /dev/null +++ b/document/bash_name_of_script.txt @@ -0,0 +1,40 @@ + +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. diff --git a/document/directory_naming.html b/document/directory_naming.html new file mode 100644 index 0000000..d409362 --- /dev/null +++ b/document/directory_naming.html @@ -0,0 +1,198 @@ + + + + + + + + Directory Structure Description + + + + + +
+

Directory Naming

+ +

Reference

+ +
    +
  • Mosaic/aka REPO_HOME, top level owned by the project administrator.
    • +
      +
    • developer/ Workspace for the developer. Has the source code, build scripts, and development-specific tools.
      • +
        +
      • deprecated/ Files and older versions being viewed, perhaps part of a refactoring effort.
        • +
      • document/ Documentation on developing and building the project.
        • +
      • javac/ Java source files for compilation.
        • +
      • jvm/ Compiled Java bytecode files for the project, typically a jar for a Java project.
        • +
      • scratchpad/ Temporary storage typically for intermediate files created during build.
        • +
      • shell/ Shell scripts intended to be part of the project release. (These are not tools.)
        • +
      • tool/ Tools created by the developer, used for development tasks.
        • +
      +
    • document/ General documentation about the project.
      • +
    • release/ Release candidate for testing. Becomes the release on the release branch.
      • +
    • scratchpad/ Temporary storage for project administration tasks.
      • +
    • tester/ Workspace for the tester. Has the test bench, tests, and test scripts.
      • +
        +
      • document/ Test-specific documentation.
        • +
      • javac/ The tests of the test bench sources.
        • +
      • tool/ Tools needed for testing and managing the test environment.
        • +
      +
    • tool/ Project administration specific tools.
      • +
    • tool_shared/ Tools shared across project roles.
      • +
        +
      • bespoke/ Shared tools developed within this project.
        • +
      • customized/ Modified versions of third-party tools adapted for the project.
        • +
      • document/ Documentation related to shared tools and setup.
        • +
      • third_party/ Shared tools sourced from third-party vendors or open-source projects. These have their own independent licenses,
        • +
      +
    • LICENSE.txt The project license detailing usage and distribution terms.
      • +
    • README.md A general overview and introduction to the project.
      • +
    +
+ +

Name origin and rationale

+ +

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.

+ +

For example, a directory named exe/ 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 exe/ directory that do not have their + executable permission bit set. The two concepts being an exe/ file + (i.e. being a file in an exe/ directory) and being an executable file + are not identical. The actual intended meaning of being an exe/ 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. +

+ +

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 developer/ directory. In a similar manner we get the + directories, tester/, and javac/. In this latter case the + agent is a compiler rather than a role. +

+ +

When attempting to apply the is-for property in practice it + became apparent that using this sole property was insufficient. Consider + the directories deprecated/ and scratchpad/. There is no + Mr. Deprecated or Mr. Scratchpad 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 deprecated/ we gain no + information about the contents of the file, because any file can + be deprecated, independent of its contents. +

+ +

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: is-a + and is-for. For example, "Each file in + the document/ directory is-a document," or "Each + file in the developer/ directory is-for 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?) +

+ +

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 document/ directory, as shown in + the prior paragraph. +

+ +
+ + + diff --git a/document/how_to_use_project_directory_structure.txt b/document/how_to_use_project_directory_structure.txt new file mode 100644 index 0000000..6c3ea4c --- /dev/null +++ b/document/how_to_use_project_directory_structure.txt @@ -0,0 +1,59 @@ +### 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_` 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.0`, where `v.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.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.`, where `` 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. diff --git a/document/running_IDE_and_jdb_in_test_environment.txt b/document/running_IDE_and_jdb_in_test_environment.txt new file mode 100644 index 0000000..46daa61 --- /dev/null +++ b/document/running_IDE_and_jdb_in_test_environment.txt @@ -0,0 +1,62 @@ + +This document describes how to run jdb in the test environment while also viewing source code. + +This is written relative to the Mosaic 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 Mosaic + > 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/Mosaic/tool_shared/third_party/jdk-11 + + > which jdb + /var/user_data/Thomas-developer/Mosaic/tool_shared/third_party/jdk-11/bin/jdb + +3. invocation from a shell command: + + jdb -sourcepath $SOURCEPATH + + 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 resource project, developer/emacs/emacs.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. + + + + + + diff --git a/document/variable_suffix_conventions.txt b/document/variable_suffix_conventions.txt new file mode 100644 index 0000000..e3ad587 --- /dev/null +++ b/document/variable_suffix_conventions.txt @@ -0,0 +1,31 @@ +# 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.