From: Thomas Walker Lynch Date: Wed, 2 Oct 2024 03:38:34 +0000 (+0000) Subject: initializing X-Git-Url: https://git.reasoningtechnology.com/style/static/git-favicon.png?a=commitdiff_plain;h=853579a8072b651effa6dc7939228c840de2ceda;p=Ariadne initializing --- diff --git a/README.md b/README.md index a37a035..8202030 100644 --- a/README.md +++ b/README.md @@ -1,20 +1,27 @@ -Ariadne is a project in progress. +Theseus volunteered to enter the inescapable maze designed by Daedalus to slay +the Minotaur and put an end to the Athenian sacrifices. Ariadne, fearing for his +life and desperate to help, thinks to give him a ball of string, which Theseus +then uses to trace his way out of the maze thus saving his life. -Ariadne had an idea, and gave a ball of string to Theseus, so he could find his way -back out of Daedalus's maze after killing the Minotaur. +Building experimental code for GQL_to_Cypher has proven to be as complex as +navigating Daedalus's maze. The traditional build tool `make` does not +backward-chain pattern rules. Gradle/Groovy tends to build projects in +layers. However, in experimental code, it is often the case that +no complete layer will build without errors. -Building experimental code for GQL_to_Cypher has turned out to be such a -maze. `make` for example does not backwards chain pattern rules, and gradle/grovy -is predisposed to build up the project in layers, although no full layer -ever seems to be working at one time. +Ariandne will attempt to build all that is buildable, no matter where in +a the dependency graph the buildable node is found, while leaving other +parts untouched. -To use the 'Ariadne' build tool, a developer uses the groovy language to define -a dependency grpah, while using a map and a list of regular expression mathching -functions. Then to build, or cleanup, the project, the developer calls Ariadne. +To use the Ariadne build tool, a developer writes their dependency graph in +Groovy, utilizing a map and a set of regular expression matching +functions. Then, to build or clean up the project, the developer invokes +Ariadne. -Ariadne was originally written in Groovy because it was incrementally developed -as part of a gradle script. It is planned to port the build tool to addiitonal -languages; however groovy turns out to be a reasonable language, so this is not -pressing. +Ariadne was originally written in Groovy because it evolved incrementally as +part of a Gradle script. While there are plans to port the build tool to other +languages, Groovy has proven to be a practical language for this purpose, so this +is currently not a priority. +Ariadne is a project in progress. diff --git a/developers/.githolder b/developers/.githolder deleted file mode 100644 index e69de29..0000000 diff --git a/developers/Somnus/.gitignore b/developers/Somnus/.gitignore new file mode 100644 index 0000000..120f485 --- /dev/null +++ b/developers/Somnus/.gitignore @@ -0,0 +1,2 @@ +* +!/.gitignore diff --git a/developers/executor/.githolder b/developers/executor/.githolder new file mode 100644 index 0000000..e69de29 diff --git a/developers/tanuki/.gitignore b/developers/tanuki/.gitignore new file mode 100644 index 0000000..120f485 --- /dev/null +++ b/developers/tanuki/.gitignore @@ -0,0 +1,2 @@ +* +!/.gitignore diff --git a/readers/directory_naming.txt b/readers/directory_naming.txt index e25af43..2de57e2 100644 --- a/readers/directory_naming.txt +++ b/readers/directory_naming.txt @@ -1,41 +1,84 @@ -Generally, project directories are named after the agent the files are for. +Naming Conventions for Directories -The top level directory is reserved for the project manager. The project -manager's directory will hold the git repo, virtual environment tool installs, -and one or more files to be sourced for initializing the environment. The -environment variable $REPO_HOME points to the top level directory. + Our shop has a convention of naming directories after the role of the person, + the name of the program, or generally, the agent, that is going to use + the files in the directory. In short, "directories are named after the agent the + files are for." -The developers' directory is $REPO_HOME/developer, which is the also -$DEVELOPER_HOME. + This convention makes it easier for people to make sense of directory names. It + is also natural for people to think in terms of the actors doing things. Indeed + our ancestors saw the hand of a person, spirit, or God behind everything. -When 'make' or 'build.gradle' is found in the top level directory, -i.e. $REPO_HOME, it is for building tools. The developer will have a separate -build file under $DEVELOPER_HOME. +Top Level Directory -When a project has files for the C compiler, cc, are put in a directory called "cc". -Files for the java compiler, javac, are in the directory "javac". Etc. + Sometimes this naming convention is not practical. The top level of a github + project must be named after the project. Though note here to the human + tendency to see actors. Look at all the mythical animals on the covers of the + O'Reilley manuals. -An `executor` is a generic name for a program that runs a file. Example -executors include the OS loader for binary files, the JVM for .jar files, -and bash for running shell scripts. A directory that holds a mix of such -files is called `executor`, as the files are for the `executor`. + The top level directory of our git project is reserved for project manager to + use. It will have files such as `.git`, and various scripts for maintaining + the project. The project manager will install the tools used in a directory + called 'toolsmiths. There is a sub directory for the developers, called + 'developers'. -A directory full of documents is then for 'readers'. + The top level directory is located at `$REPO_HOME` -Some directories are more difficult to name after an agent that uses the -files in them. Like our ancestors who personified nearly everything with -spirits, we will do the same. +Developers -When programs use a directory as a scratch pad, where files will disappear -seemingly without reason we will call the directory "tanuki". This is a Japanese -raccoon so famous for making things disappear that it has taken on mystical -proportions. + The developer’s directory is located at `$REPO_HOME/developers`, and is + known in the environment as `$DEVELOPERS_HOME`. -As a developer I often have files that I set aside just in case I want to look -at them again, or later make new versions. So I give them to the God of sleep, -Somnus. Maybe they will be woken up, maybe they won't. Unlike tanuki files, -they are not deleted by any of the tools. + This directory contains the developers' 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 the agents that operate on the contained files. -Files in tanuki and Soumnus are not placed into the repo. + 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. + +Executor + + Sometimes multiple actors operate on the files in a directory. In which case + we give the directory a more general name that describes the actors. + + 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'. + + One common generalization 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. + +Readers + + This refers to humans or AIs. It is short for 'Dear Readers,". These + files are for those rare individuals who read documents. + +Files for mythological beings + + I've had a bit of fun and introduced a couple of these. We wouldn't want too + many. + + tanuki, たぬき + + Both a mythical beast, and a real animal. A kind of raccoon, which like all + raccoons, will steal things, especially food. Files left within reach of a + tanuki, are likely to disappear without notice. Typically these are things + such as intermediate files during a build. + + Somnus + + 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 tanuki files, + they are not deleted by any clean script or any program that is using them as + intermediate files. However, they do not appear it the repo. Somnus is the + Roman god of sleep.