From 4871ff3c2ec564c481b666cf31f79ebbfbc103a2 Mon Sep 17 00:00:00 2001 From: Thomas Walker Lynch Date: Wed, 9 Oct 2024 15:15:11 +0000 Subject: [PATCH] a more reasoanble directory name explanation doc --- developer/javac/PaintItBlack.java | 2 + developer/{executable => tool}/env_build | 0 developer/{executable => tool}/make.sh | 0 developer/{executable => tool}/release | 14 +- developer/{executable => tool}/version | 0 document/directory_naming.txt | 153 ---------------- document/directory_structure_description.html | 169 ++++++++++++++++++ tester/{executor => tool}/#make.sh# | 0 tester/{executor => tool}/env_tester | 0 tester/{executor => tool}/make.sh | 0 tool/.gitignore | 5 - {executable => tool}/env_base | 0 {executable => tool}/env_dev | 0 {executable => tool}/env_pm | 0 {executable => tool}/env_tester | 0 {executable => tool_shared/bespoke}/version | 0 tool_shared/customized/.githolder | 0 tool_shared/document/#install_java.txt# | 11 ++ tool_shared/document/install_groovy.txt | 29 +++ tool_shared/document/install_java.txt | 11 ++ tool_shared/third_party/.gitignore | 4 + .../third_party}/upstream/.gitignore | 0 22 files changed, 231 insertions(+), 167 deletions(-) rename developer/{executable => tool}/env_build (100%) rename developer/{executable => tool}/make.sh (100%) rename developer/{executable => tool}/release (77%) rename developer/{executable => tool}/version (100%) delete mode 100644 document/directory_naming.txt create mode 100644 document/directory_structure_description.html rename tester/{executor => tool}/#make.sh# (100%) rename tester/{executor => tool}/env_tester (100%) rename tester/{executor => tool}/make.sh (100%) delete mode 100644 tool/.gitignore rename {executable => tool}/env_base (100%) rename {executable => tool}/env_dev (100%) rename {executable => tool}/env_pm (100%) rename {executable => tool}/env_tester (100%) rename {executable => tool_shared/bespoke}/version (100%) create mode 100644 tool_shared/customized/.githolder create mode 100644 tool_shared/document/#install_java.txt# create mode 100644 tool_shared/document/install_groovy.txt create mode 100644 tool_shared/document/install_java.txt create mode 100644 tool_shared/third_party/.gitignore rename {tool => tool_shared/third_party}/upstream/.gitignore (100%) diff --git a/developer/javac/PaintItBlack.java b/developer/javac/PaintItBlack.java index 60f27b8..7f41717 100644 --- a/developer/javac/PaintItBlack.java +++ b/developer/javac/PaintItBlack.java @@ -1,3 +1,5 @@ +import com.ReasoningTechnology.Ariadna.*; + public class PaintItBlack { public static void main(String[] args) { System.out.println("Paint it black."); diff --git a/developer/executable/env_build b/developer/tool/env_build similarity index 100% rename from developer/executable/env_build rename to developer/tool/env_build diff --git a/developer/executable/make.sh b/developer/tool/make.sh similarity index 100% rename from developer/executable/make.sh rename to developer/tool/make.sh diff --git a/developer/executable/release b/developer/tool/release similarity index 77% rename from developer/executable/release rename to developer/tool/release index 74690cb..aabc46a 100755 --- a/developer/executable/release +++ b/developer/tool/release @@ -43,17 +43,13 @@ def install_file(source_fp, target_dp, perms) { println "Starting release process..." -def build_fp = "${repo_home}/developer/groovy/build" -def ariadne_class_files = new File("${repo_home}/developer/groovyc").listFiles().findAll { - it.name.startsWith("AriadneGraph") && it.name.endsWith(".class") -} +def build_fp = "${repo_home}/developer/shell/build" +def ariadne_jar_fp = "${repo_home}/developer/jvm/AriadneGraph.jar" // Install the build script -install_file(build_fp, release_dir, "ug+r,ug+x") +install_file(build_fp, release_dir, "ug+r") -// Install all matching class files -ariadne_class_files.each { class_file -> - install_file(class_file.absolutePath, release_dir, "ug+r") -} +// Install the JAR file +install_file(ariadne_jar_fp, release_dir, "ug+r") println "Release process completed successfully." diff --git a/developer/executable/version b/developer/tool/version similarity index 100% rename from developer/executable/version rename to developer/tool/version diff --git a/document/directory_naming.txt b/document/directory_naming.txt deleted file mode 100644 index bd6ebb9..0000000 --- a/document/directory_naming.txt +++ /dev/null @@ -1,153 +0,0 @@ - -Directories Naming Convention ------------------------------ - -Property based file organization - - I am experimenting with a file system where instead of having directories, we - have collections of files that have property in common. - - In this distribution the project is on a conventional file system, but we still - have the directory names. These following properties have been used, in - order of preference: - - 1. Who the file is for. This is typically a role of a contributor - to the project, or the name of a program. - - 2. The role that the file plays in the project. This is more general than - saying a file is for a specific program, or even kind of program. As an - example, the 'tool' directory. - - 3. A role that the directory plays. As an example, 'scratch_pad'. Another - example is 'deprecated' which is a short term archived file. - - In this third category the file property is imposed upon the file, - rather than being a description of the file's contents. - - One side effect of grouping files based on a shared property is that - the directory name, coming from the property name, is often singular. - -Who the file is for - - These file groups fit the model well: developer, tester, user. Also in the - developer directory, directories named after programs work well, as examples, - python, groovy, cc, linker, javac, etc. - -Generalization of who the file is for, e.g. executor - - Sometimes multiple related actors operate on the files in a directory. In - which case we give the directory a more general name that describes the - actors as a group. - - So if we had a directory that held a mix of files for various compilers we might - name the directory 'compiler_input' or even 'compiler'. If the files are - interpreted and multiple interpreters are involved, then 'interpreter_input'. - - A such generalization you will see in this project is 'executor'. An executor - is any program that runs another program; examples include shells that - interpret shell scripts; various language interpreter; and most famously the - machine loader, which will load an instruction sequence into memory and point - the program counter at it. - -document - - What role do people play when reading documents? That this question does not - have an obvious direct answer says something about our values, and this in - turn might explain why so few people actually read the documents. - - An author will call the person reading his work 'the reader', perhaps even - addressing a reader directly, 'Dear Reader'. However, the are a large number - of reader programs and devices, such as Adobe Reader and a bar card reader. - Unlike toolsmith, developer, and tester, being a 'reader' is not a job - title that a person is going to be addressed by. - - A person might reach for latin and use the word, 'lector'. However it is - a stretch to get the meaning from this one. Perhaps we move to Greek, and - imagine the role 'projectologist'. lol. Perhaps shortened to 'ologist'? - - Actually, there is a word for a person who studies books, articles, and - documents, a 'student'. It is actually a fairly accurate description of the - role a person plays while trying to learn about the project. The only drawback - is that it is not a professional role title. Perhaps it is not much of a - stretch to say someone is still in the student phase learning about a project. - I tried this label out for a while, but it did not really fit. - - There is a clear property choice. Each file in the document directory has the - property of being a document, hence, the directory name is 'document'. The - document directory at the top level is for the project manager, while the - document directory in the developer's directory is about the code being - developed and hold to build it. - - -Purpose - tool, temporary, deprecated - - For some other directories it is even more of a stretch to try and say - they are for an actor. - - Ancient man would make up spirits in such situations. Perhaps then files in a - temporary directory are for the 'tanuki', a real animal in Japan who that has - taken on mythical proportions causing things to disappear or playing tricks. A - directory of deprecated files could said to be for 'Lethe', the river that - carries away the memories of those who are reincarnated - which reminds me of - the rivers in so many places that carry away trash. I tried these names - out. It was good entertainment, but when trying to explain them I met with - blank expressions. - - Since in these cases we can not answer the question of who the files are for, - we instead choose another common property shared by each and every file in the - directory. Hence we end up with 'tool' for the directory with tools, instead - of saying they are for the tool smith, or even for Hephaestus, besides tool - smiths such as Hephaestus create tools, and the tool directory is full of - tools that were already created. - -Top level directory - - The top level of a github project is of course named after the project. Here - to us programmers have appealed to mythology to find actors. Just look at all - the mythical animals on the covers of the O'Reilley manuals. - - The top level directory of our git project is reserved for project manager to - use. The 'project manager', in this context, builds the directory structure, - initializes the repository, installs tools that will be needed, and generally - administers the project. - - In the environment, the top level directory is located at `$REPO_HOME` - -developer - - The developer's directory is located at `$REPO_HOME/developer`. - - This directory contains the developer's workspace. Developers are free to - organize it in any manner they see fit, though they should continue to follow - the convention of naming directories after properties when it is practical to - do so. - - As examples, - - - Files for the **C compiler** are placed in the `cc` directory, since they - are "for" the C compiler. - - - Files for the **Java compiler** (javac) are stored in the `javac` directory. - - - Similar naming conventions are followed for other tools. For instance, if - the project involves files for another tool or compiler, the directory is - named after that tool. - -scratch_pad - - This is a temporary directory used by programs. Files in this directory are - typically removed by the program that placed the file, or by a `clean` script. - There is no reason a developer can not manually add a file, but scripts such - as `make clean`, might delete it. Directories with this name should be git - ignored. - -deprecated - - As a developer I often have files that I set aside just in case I want to look - at them again. Sometimes I plan to bring them back later. Unlike temporary files, - they are not deleted by any clean script or any program that is using them as - intermediate files. This directory is similar in intent to `git stash` or - using to and going back to look at old versions. The contents of this directory - do end up in the repo. - -LocalWords: projectologist diff --git a/document/directory_structure_description.html b/document/directory_structure_description.html new file mode 100644 index 0000000..cbe1950 --- /dev/null +++ b/document/directory_structure_description.html @@ -0,0 +1,169 @@ + + + + + + Directory Structure Description + + + + +
+

Directory Structure Description

+ +

Reference

+ + + + +

Name origin and rationale

+ +

Typically, developers and project administrators 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 other people or from documents.

+ +

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. +

+ +

However, when attempting this it became apparent that the recognition of + relationships was insufficient. Consider the directories `deprecated` and + `scratch_pad`. There is no 'Mr. Deprecated' or 'Mr. Scratch_Pad' 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 + saying a file has a relationship with an agent, these properties + (directory names) are states imposed by decree by an agent on a file. + Perhaps the developer, has decreed that a file is now deprecated, or a + build script has decreed that it is a scratch_pad file. Such decrees are + typically more dynamic than the relationship properties. Also, these + properties are also disconnected from the contents of the file. When, for + example, we say a file is for the java compiler we can surmise something + about its contents. However when we say a file is `deprecated` we can + surmise nothing about 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 to the conventional file + system, we can typically infer what it must be. It is beyond the scope of + discussion here, but in actuality, our collections are defined by + predicates that are given a file's properties and relationships as + arguments, where the predicate 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/tester/executor/#make.sh# b/tester/tool/#make.sh# similarity index 100% rename from tester/executor/#make.sh# rename to tester/tool/#make.sh# diff --git a/tester/executor/env_tester b/tester/tool/env_tester similarity index 100% rename from tester/executor/env_tester rename to tester/tool/env_tester diff --git a/tester/executor/make.sh b/tester/tool/make.sh similarity index 100% rename from tester/executor/make.sh rename to tester/tool/make.sh diff --git a/tool/.gitignore b/tool/.gitignore deleted file mode 100644 index de7fe7a..0000000 --- a/tool/.gitignore +++ /dev/null @@ -1,5 +0,0 @@ -* -!/.gitignore -!/document -# upstream has a .gitignore file in it -!/upstream diff --git a/executable/env_base b/tool/env_base similarity index 100% rename from executable/env_base rename to tool/env_base diff --git a/executable/env_dev b/tool/env_dev similarity index 100% rename from executable/env_dev rename to tool/env_dev diff --git a/executable/env_pm b/tool/env_pm similarity index 100% rename from executable/env_pm rename to tool/env_pm diff --git a/executable/env_tester b/tool/env_tester similarity index 100% rename from executable/env_tester rename to tool/env_tester diff --git a/executable/version b/tool_shared/bespoke/version similarity index 100% rename from executable/version rename to tool_shared/bespoke/version diff --git a/tool_shared/customized/.githolder b/tool_shared/customized/.githolder new file mode 100644 index 0000000..e69de29 diff --git a/tool_shared/document/#install_java.txt# b/tool_shared/document/#install_java.txt# new file mode 100644 index 0000000..0091eac --- /dev/null +++ b/tool_shared/document/#install_java.txt# @@ -0,0 +1,11 @@ + +#1. downlaod + +cd "$REPO_HOME/tool/upstream" +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 + +#2. extract + +cd "$REPO_HOME/tool" +mkdir -p jdk-11 +tar -xzf "$REPO_HOME/tool/upstream/OpenJDK11U-jdk_x64_linux_hotspot_11.0.16_8.tar.gz" -C jdk-11 --strip-components 1 diff --git a/tool_shared/document/install_groovy.txt b/tool_shared/document/install_groovy.txt new file mode 100644 index 0000000..76ec07e --- /dev/null +++ b/tool_shared/document/install_groovy.txt @@ -0,0 +1,29 @@ + +1. Docs + https://groovy-lang.org/documentation.html + +2. Install from source + + # 1.1 Download + + # https://dlcdn.apache.org/groovy/ + + cd $REPO_HOME/toolsmith/upstream + wget https://dlcdn.apache.org/groovy/4.0.23/sources/apache-groovy-src-4.0.23.zip + + # 1.2 then build them ;-) + +2. Install binaries + + #!/usr/bin/env bash + + # Define version of Groovy to be installed + version="4.0.9" + + # 2.1 Download using curl + cd "$REPO_HOME/toolsmith/upstream" + curl -o apache-groovy-binary-${version}.zip https://groovy.jfrog.io/artifactory/dist-release-local/groovy-zips/apache-groovy-binary-${version}.zip + + # 2.2 Extract + cd "$REPO_HOME/tools" + unzip "$REPO_HOME/tools/upstream/apache-groovy-binary-${version}.zip" -d . diff --git a/tool_shared/document/install_java.txt b/tool_shared/document/install_java.txt new file mode 100644 index 0000000..c9e5743 --- /dev/null +++ b/tool_shared/document/install_java.txt @@ -0,0 +1,11 @@ + +#1. downlaod + +cd "$REPO_HOME/tool/upstream" +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 + +#2. extract + +cd "$REPO_HOME/tool" +mkdir jdk-11 +tar -xzf "$REPO_HOME/tool/upstream/OpenJDK11U-jdk_x64_linux_hotspot_11.0.16_8.tar.gz" -C jdk-11 --strip-components 1 diff --git a/tool_shared/third_party/.gitignore b/tool_shared/third_party/.gitignore new file mode 100644 index 0000000..525ec6b --- /dev/null +++ b/tool_shared/third_party/.gitignore @@ -0,0 +1,4 @@ +* +!/.gitignore +# upstream has a .gitignore file in it, edit to keep anything precious +!/upstream diff --git a/tool/upstream/.gitignore b/tool_shared/third_party/upstream/.gitignore similarity index 100% rename from tool/upstream/.gitignore rename to tool_shared/third_party/upstream/.gitignore -- 2.20.1