# HG changeset patch # User ellis # Date 1701742151 18000 # Node ID 9a3d82d9072aa66970a1c39857930763ae6890ee # Parent 4cb5e087f588ce7fa49e50c926adeb17845d3f3d refactoring diff -r 4cb5e087f588 -r 9a3d82d9072a business.org --- a/business.org Thu Nov 30 20:55:41 2023 -0500 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,17 +0,0 @@ -{{{header(business, -Richard Westhaver, -ellis@rwest.io, -The Compiler Company Business Model)}}} - -In short, this document describes the business aspects of The Compiler -Company LLC. We are designed to be small, fast, and agile. We -infiltrate a market, apply our methodology, and develop solutions that -are simply years ahead of the competition. We treat the market like -we're the only supplier, because we can. This is in part due to our -internal research & development pursuits, but also our approach to -business. We build businesses and revenue streams the exact same way -we build software -- with a bottom up approach. This is our secret -weapon, and what gives us the ability to adapt to any environment -where our interests lie. - -#+TOC: headlines 3 diff -r 4cb5e087f588 -r 9a3d82d9072a core/api/readme.org --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/core/api/readme.org Mon Dec 04 21:09:11 2023 -0500 @@ -0,0 +1,3 @@ +{{{header(Core API Docs,Richard Westhaver,ellis@rwest.io)}}} +#+OPTIONS: ^:nil toc:nil num:nil html-postamble:nil +#+EXPORT_FILE_NAME: index diff -r 4cb5e087f588 -r 9a3d82d9072a core/app/readme.org --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/core/app/readme.org Mon Dec 04 21:09:11 2023 -0500 @@ -0,0 +1,3 @@ +{{{header(Core App Docs,Richard Westhaver,ellis@rwest.io)}}} +#+OPTIONS: ^:nil toc:nil num:nil html-postamble:nil +#+EXPORT_FILE_NAME: index diff -r 4cb5e087f588 -r 9a3d82d9072a core/lib/readme.org --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/core/lib/readme.org Mon Dec 04 21:09:11 2023 -0500 @@ -0,0 +1,3 @@ +{{{header(Core Lib Docs,Richard Westhaver,ellis@rwest.io)}}} +#+OPTIONS: ^:nil toc:nil num:nil html-postamble:nil +#+EXPORT_FILE_NAME: index diff -r 4cb5e087f588 -r 9a3d82d9072a core/notes.org --- a/core/notes.org Thu Nov 30 20:55:41 2023 -0500 +++ b/core/notes.org Mon Dec 04 21:09:11 2023 -0500 @@ -0,0 +1,3 @@ +{{{header(Core Notes,Richard Westhaver,ellis@rwest.io)}}} +#+OPTIONS: ^:nil toc:nil num:nil html-postamble:nil + diff -r 4cb5e087f588 -r 9a3d82d9072a core/readme.org --- a/core/readme.org Thu Nov 30 20:55:41 2023 -0500 +++ b/core/readme.org Mon Dec 04 21:09:11 2023 -0500 @@ -1,4 +1,10 @@ {{{header(docs/core,Richard Westhaver,ellis@rwest.io)}}} #+EXPORT_FILE_NAME: index -- [[file:notes.org][Notes]] :: Internal Notes. +- [[file:notes.org][Notes]] :: Internal Notes + +- [[file:app][App Docs]] :: High-level App Documentation + +- [[file:lib][Lib Docs]] :: High-level Lib Documentation + +- [[file:api][API Docs]] :: API Reference diff -r 4cb5e087f588 -r 9a3d82d9072a infra/scripts.org diff -r 4cb5e087f588 -r 9a3d82d9072a meta/business.org --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/meta/business.org Mon Dec 04 21:09:11 2023 -0500 @@ -0,0 +1,17 @@ +{{{header(business, +Richard Westhaver, +ellis@rwest.io, +The Compiler Company Business Model)}}} + +In short, this document describes the business aspects of The Compiler +Company LLC. We are designed to be small, fast, and agile. We +infiltrate a market, apply our methodology, and develop solutions that +are simply years ahead of the competition. We treat the market like +we're the only supplier, because we can. This is in part due to our +internal research & development pursuits, but also our approach to +business. We build businesses and revenue streams the exact same way +we build software -- with a bottom up approach. This is our secret +weapon, and what gives us the ability to adapt to any environment +where our interests lie. + +#+TOC: headlines 3 diff -r 4cb5e087f588 -r 9a3d82d9072a meta/readme.org --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/meta/readme.org Mon Dec 04 21:09:11 2023 -0500 @@ -0,0 +1,10 @@ +{{{header(Meta Docs,Richard Westhaver,ellis@rwest.io)}}} +#+OPTIONS: ^:nil toc:nil num:nil html-postamble:nil +#+EXPORT_FILE_NAME: index +* [[file:ulang.org][ulang]] +* [[file:style.org][style]] +* [[file:tech.org][tech]] +* [[file:business.org][business]] + + + diff -r 4cb5e087f588 -r 9a3d82d9072a meta/style.org --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/meta/style.org Mon Dec 04 21:09:11 2023 -0500 @@ -0,0 +1,43 @@ +{{{header(style, +Richard Westhaver, +ellis@rwest.io, +The Compiler Company Styleguide)}}} + +As an organization we maintain a styleguide[fn:1] which lists all of +the style guidelines we use for our code. If you are contributing to +one of our projects, you should review and understand the relevant +sections below. + +You should also review the [[file:ulang.org][ulang]] document, which may shine some light +on code comments and developer docs. + +[fn:1] https://google.github.io/styleguide/ + +* General Programming +- indent-offset = 2 +- max-line-width = 80 +- page-length ~ 32 +- module-length ~ 512 +- file-size ~ 1024 + +- start every source-file with a header comment +- use outline headings to organize your program +- use ulang-comments as needed for referencing bugs, notes, etc. +- inline documentation should be declarative. your code explains your + comments for you. +- variables, imports, and exports belong at the top of a file +- =main= functions belong at the bottom of a file +* Common Lisp + +- prefer symbol docs to comments +- use stdin/stdout/stderr correctly - see [[https://zenodo.org/records/3414191][CDR-11]] +- always prefer =core= libraries over vendored dependencies +- use the compiler internals - if a function or class is generally + useful, add it to the core +* Rust +- don't make =mod.rs= files + - use the =foo.rs=, =foo/*= pattern instead +* Emacs Lisp +* Org-mode +* Shell +* Python diff -r 4cb5e087f588 -r 9a3d82d9072a meta/tech.org --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/meta/tech.org Mon Dec 04 21:09:11 2023 -0500 @@ -0,0 +1,24 @@ +{{{header(tech, +Richard Westhaver, +ellis@rwest.io, +The Compiler Company Core Technologies)}}} + +* OS +We primarily support [[https://unix.org][Unix-based]] Operating Systems. Check +project-specific docs for officially supported targets. + +Development and CI is ran on [[https://archlinux.org/][Arch Linux]] (btw). +* Core +** [[https://lisp-lang.org/][Lisp]] +** [[https://www.rust-lang.org/][Rust]] +** [[https://www.gnu.org/software/emacs/][Emacs]] +* Libs +** [[https://rocksdb.org/][rocksdb]] +** [[https://archlinux.org/pacman/][pacman]] +** [[https://docs.kernel.org/filesystems/btrfs.html][btrfs]] +** [[https://tree-sitter.github.io/tree-sitter/][tree-sitter]] +** [[https://kernel.dk/io_uring.pdf][uring]] +** [[https://github.com/BLAKE3-team/BLAKE3-specs/blob/master/blake3.pdf][blake3]] +* Extras +** [[https://ngn.codeberg.page/k][k]] +** [[https://mlochbaum.github.io/BQN/][BQN]] diff -r 4cb5e087f588 -r 9a3d82d9072a meta/ulang.org --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/meta/ulang.org Mon Dec 04 21:09:11 2023 -0500 @@ -0,0 +1,166 @@ +{{{header(ulang, +Richard Westhaver, +ellis@rwest.io, +The Universal Language)}}} +#+OPTIONS: toc:t + +This document describes a *U-Language* as described by the late great +[[https://iep.utm.edu/haskell-brooks-curry/][Haskell Curry]]: + +#+begin_quote +Every investigation, including the present one, has to be communicated +from one person to another by means of language. It is expedient to +begin our study by calling attention to this obvious fact, by giving a +name to the language being used, and by being explicit about a few of +its features. We shall call the language being used the +U-Language. [...] There would be no point in calling attention to it, +if it were not for the fact that language is more intimately related +to our job than of most others. +#+end_quote + +In this document, we will be calling attention to our own language - +examining it, and describing how it works. + +Our job is to solve problems. Hard problems preferred. So we ought to +pay close attention to the language we use because it brings the +reader and writer /closer/ to the problem at hand. + +For starters, we are primarily concerned with /written languages/ like +the one you're reading now. We will skip past the obvious details - +English is our primary form of communication for example. The line you +are reading currently is a sentence which is part of a paragraph. + +There are some non-obvious questions which deserve inquiry though. + +- *Who is this for?* \\ + This document is for authors and readers alike. It is a loose + specification, but also serves as introductory material into our + communication and design philosophy. + +- *What is this for?* \\ + The purpose of this document is to provide a /standard of + communication/. + + All sources we write attempt to conform to this standard but this is + not strictly enforced. If there is a reason to not comply with a + rule, it is already broken. + +* Org Mode +:PROPERTIES: +:CUSTOM_ID: 98a02bb2-3f39-49c6-898a-68ccd8f3cbe1 +:END: +[[https://www.gnu.org/software/emacs/][GNU Emacs]] is our text editor, so naturally [[https://orgmode.org/][Org Mode]] is our word +processor. + +If you are already familiar with Emacs and Org-Mode, I recommend +opening the source of this document in Emacs and following along. + +If not, I recommend browsing through the [[https://orgmode.org/worg/][Worg resources]], but we won't +be getting too deep into tribal hacker knowledge of Emacs. + +What's important to know is this: There is /Org Syntax/ and +/Org-mode/ - these are different things. + +Our =ulang= is almost /exclusively/ based on /Org Syntax/ and we are +not concerned about /Org-mode/ the application in this document. + +* ulang +:PROPERTIES: +:ID: ulang +:END: +As the title suggest we refer to our *U-Language* as *ulang*. Each +section of this document describes a feature. +** Outlines +In Org, headings can be summarize as any line starting with a star: =* +H1=. Headings can be nested or 'demoted' by prepending another star: +=** H2=. + +This is a useful pattern which we apply outside of Org - most commonly +in our code comments. + +In our source code, we use the comment character instead of a star: +#+begin_src lisp +;;; foo +(print "H1") ;; just an inline comment +;;;; bar +(print "H2") +;;; baz +(print "H1") +#+end_src + +A collection of /headings/ is what we call an *Outline* - which is +also the name of the major-mode utilized for this feature and of +course - what Org itself is derived from. + +** Keywords +:PROPERTIES: +:CUSTOM_ID: 2cadda9a-22a3-4b42-ad4e-d7a774f74cba +:END: + +The following keywords indicate the state of an element. They often +appear as the first word in a heading to indicate a [[*Tasks][Task]]. + +- TBD :: A task to be done at a later date. +- TODO :: A task yet to be done. +- FIXME :: Item that needs fixing. +- WIP :: Work In Progress task. +- WAIT :: A suspended task. +- DEAD :: Item that will not be completed. +- DONE :: Completed task. +- BUG :: Designate a bug item. +- IDEA :: Designate an idea item. +- NOTE :: Designates a note item. +- DRAFT :: Designates a draft item. +- COMMENT :: A 'commented' item. +** Tasks +Tasks as they are known in Org, usually consist of a heading that +starts with a [[#2cadda9a-22a3-4b42-ad4e-d7a774f74cba][Keyword]]. Here we describe some additional sections and +metadata which are present in our collection of tasks. + +Our task management system is roughly a hybrid of two more +conventional methods: GTD and Agile. For convenience I will describe +these styles and how I use them separately, but the concepts may be +spliced differently in real tasks. + +- *GTD* \\ +- *Agile* \\ + It's a dirty word in some tech circles - the dreaded PIs, daily + standups, and still nobody knows what's going on, Oh my! Do not + worry. For the most part we just borrow the vocabulary. + + Our /Agile/ workflow consists of roadmaps, features (epics/ARTs), + issues (user stories), and of course, tasks. +** Ids +We reference two different types of identifiers in documentation: +- UUID :: CUSTOM_ID property +- User-defined :: ID property + +UUIDs on =CUSTOM_ID= property is admittedly a kludge. This is done for +reasons of portability. We may at some point rename this property +=UUID= (TBD). + +Most of the time these Ids don't add any information for the reader - +the UUIDs are used to index and graph documents, IDs are for +convenience. +** Macros +:PROPERTIES: +:CUSTOM_ID: cdb4976b-1d0d-49df-bfb1-3dbd5d99590e +:END: +Several *global* [[https://orgmode.org/manual/Macro-Replacement.html][Org Macros]] are used throughout our documents. They are listed +here for convenience. + +#+name: ulang-macros +#+begin_src emacs-lisp :exports both :results replace pp + org-export-global-macros +#+end_src + +#+RESULTS: ulang-macros +: (("header" . +: "#+TITLE: $1\n#+AUTHOR: $2\n#+EMAIL: $3\n#+DESCRIPTION: $4\n#+SUBTITLE: $4\n#+OPTIONS: ^:nil toc:nil num:nil html-postamble:nil\n#+HTML_HEAD: \n#+HTML_HEAD: \n#+HTML_HEAD: \n") +: ("opts" . "#+OPTIONS: $1\n")) + +Macros /are not expanded/ in source files - you will see them in the +form ={{{NAME(ARGS)}}}=. You will need the relevant macro definition +(in =ulang.el=) in order to use some Org-Mode functions (org-export) +with our docs. + diff -r 4cb5e087f588 -r 9a3d82d9072a readme.org --- a/readme.org Thu Nov 30 20:55:41 2023 -0500 +++ b/readme.org Mon Dec 04 21:09:11 2023 -0500 @@ -5,11 +5,8 @@ The Compiler Company Documentation)}}} #+EXPORT_FILE_NAME: index -* [[https://compiler.company/docs/ulang.html][ulang]] -* [[https://compiler.company/docs/style.html][style]] -* [[https://compiler.company/docs/tech.html][tech]] -* [[https://compiler.company/docs/core][core]] -* [[https://compiler.company/docs/infra][infra]] -* [[https://compiler.company/docs/business.html][business]] -* projects +* [[file:meta][Meta]] +* [[file:core][Core]] +* [[file:infra][Infra]] +* products ** [[https://compiler.company/docs/nas-t][NAS-T]] diff -r 4cb5e087f588 -r 9a3d82d9072a style.org --- a/style.org Thu Nov 30 20:55:41 2023 -0500 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,43 +0,0 @@ -{{{header(style, -Richard Westhaver, -ellis@rwest.io, -The Compiler Company Styleguide)}}} - -As an organization we maintain a styleguide[fn:1] which lists all of -the style guidelines we use for our code. If you are contributing to -one of our projects, you should review and understand the relevant -sections below. - -You should also review the [[file:ulang.org][ulang]] document, which may shine some light -on code comments and developer docs. - -[fn:1] https://google.github.io/styleguide/ - -* General Programming - -- indent-offset = 2 -- max-line-width = 80 -- page-length ~ 32 -- module-length ~ 512 -- file-size ~ 1024 - -- start every source-file with a header comment -- use outline headings to organize your program -- use ulang-comments as needed for referencing bugs, notes, etc. -- inline documentation should be declarative. your code explains your - comments for you. - -* Common Lisp - -- prefer symbol docs to comments -- use stdin/stdout/stderr correctly - see [[https://zenodo.org/records/3414191][CDR-11]] -- prefer =core= libraries over vendored - -** File templates -* Rust -- don't make =mod.rs= files - - use the =foo.rs=, =foo/*= pattern instead -* Emacs Lisp -* Org-mode -* Shell -* Python diff -r 4cb5e087f588 -r 9a3d82d9072a tech.org --- a/tech.org Thu Nov 30 20:55:41 2023 -0500 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,24 +0,0 @@ -{{{header(tech, -Richard Westhaver, -ellis@rwest.io, -The Compiler Company Core Technologies)}}} - -* OS -We primarily support [[https://unix.org][Unix-based]] Operating Systems. Check -project-specific docs for officially supported targets. - -Development and CI is ran on [[https://archlinux.org/][Arch Linux]] (btw). -* Core -** [[https://lisp-lang.org/][Lisp]] -** [[https://www.rust-lang.org/][Rust]] -** [[https://www.gnu.org/software/emacs/][Emacs]] -* Libs -** [[https://rocksdb.org/][rocksdb]] -** [[https://archlinux.org/pacman/][pacman]] -** [[https://docs.kernel.org/filesystems/btrfs.html][btrfs]] -** [[https://tree-sitter.github.io/tree-sitter/][tree-sitter]] -** [[https://kernel.dk/io_uring.pdf][uring]] -** [[https://github.com/BLAKE3-team/BLAKE3-specs/blob/master/blake3.pdf][blake3]] -* Extras -** [[https://ngn.codeberg.page/k][k]] -** [[https://mlochbaum.github.io/BQN/][BQN]] diff -r 4cb5e087f588 -r 9a3d82d9072a ulang.org --- a/ulang.org Thu Nov 30 20:55:41 2023 -0500 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,166 +0,0 @@ -{{{header(ulang, -Richard Westhaver, -ellis@rwest.io, -The Universal Language)}}} -#+OPTIONS: toc:t - -This document describes a *U-Language* as described by the late great -[[https://iep.utm.edu/haskell-brooks-curry/][Haskell Curry]]: - -#+begin_quote -Every investigation, including the present one, has to be communicated -from one person to another by means of language. It is expedient to -begin our study by calling attention to this obvious fact, by giving a -name to the language being used, and by being explicit about a few of -its features. We shall call the language being used the -U-Language. [...] There would be no point in calling attention to it, -if it were not for the fact that language is more intimately related -to our job than of most others. -#+end_quote - -In this document, we will be calling attention to our own language - -examining it, and describing how it works. - -Our job is to solve problems. Hard problems preferred. So we ought to -pay close attention to the language we use because it brings the -reader and writer /closer/ to the problem at hand. - -For starters, we are primarily concerned with /written languages/ like -the one you're reading now. We will skip past the obvious details - -English is our primary form of communication for example. The line you -are reading currently is a sentence which is part of a paragraph. - -There are some non-obvious questions which deserve inquiry though. - -- *Who is this for?* \\ - This document is for authors and readers alike. It is a loose - specification, but also serves as introductory material into our - communication and design philosophy. - -- *What is this for?* \\ - The purpose of this document is to provide a /standard of - communication/. - - All sources we write attempt to conform to this standard but this is - not strictly enforced. If there is a reason to not comply with a - rule, it is already broken. - -* Org Mode -:PROPERTIES: -:CUSTOM_ID: 98a02bb2-3f39-49c6-898a-68ccd8f3cbe1 -:END: -[[https://www.gnu.org/software/emacs/][GNU Emacs]] is our text editor, so naturally [[https://orgmode.org/][Org Mode]] is our word -processor. - -If you are already familiar with Emacs and Org-Mode, I recommend -opening the source of this document in Emacs and following along. - -If not, I recommend browsing through the [[https://orgmode.org/worg/][Worg resources]], but we won't -be getting too deep into tribal hacker knowledge of Emacs. - -What's important to know is this: There is /Org Syntax/ and -/Org-mode/ - these are different things. - -Our =ulang= is almost /exclusively/ based on /Org Syntax/ and we are -not concerned about /Org-mode/ the application in this document. - -* ulang -:PROPERTIES: -:ID: ulang -:END: -As the title suggest we refer to our *U-Language* as *ulang*. Each -section of this document describes a feature. -** Outlines -In Org, headings can be summarize as any line starting with a star: =* -H1=. Headings can be nested or 'demoted' by prepending another star: -=** H2=. - -This is a useful pattern which we apply outside of Org - most commonly -in our code comments. - -In our source code, we use the comment character instead of a star: -#+begin_src lisp -;;; foo -(print "H1") ;; just an inline comment -;;;; bar -(print "H2") -;;; baz -(print "H1") -#+end_src - -A collection of /headings/ is what we call an *Outline* - which is -also the name of the major-mode utilized for this feature and of -course - what Org itself is derived from. - -** Keywords -:PROPERTIES: -:CUSTOM_ID: 2cadda9a-22a3-4b42-ad4e-d7a774f74cba -:END: - -The following keywords indicate the state of an element. They often -appear as the first word in a heading to indicate a [[*Tasks][Task]]. - -- TBD :: A task to be done at a later date. -- TODO :: A task yet to be done. -- FIXME :: Item that needs fixing. -- WIP :: Work In Progress task. -- WAIT :: A suspended task. -- DEAD :: Item that will not be completed. -- DONE :: Completed task. -- BUG :: Designate a bug item. -- IDEA :: Designate an idea item. -- NOTE :: Designates a note item. -- DRAFT :: Designates a draft item. -- COMMENT :: A 'commented' item. -** Tasks -Tasks as they are known in Org, usually consist of a heading that -starts with a [[#2cadda9a-22a3-4b42-ad4e-d7a774f74cba][Keyword]]. Here we describe some additional sections and -metadata which are present in our collection of tasks. - -Our task management system is roughly a hybrid of two more -conventional methods: GTD and Agile. For convenience I will describe -these styles and how I use them separately, but the concepts may be -spliced differently in real tasks. - -- *GTD* \\ -- *Agile* \\ - It's a dirty word in some tech circles - the dreaded PIs, daily - standups, and still nobody knows what's going on, Oh my! Do not - worry. For the most part we just borrow the vocabulary. - - Our /Agile/ workflow consists of roadmaps, features (epics/ARTs), - issues (user stories), and of course, tasks. -** Ids -We reference two different types of identifiers in documentation: -- UUID :: CUSTOM_ID property -- User-defined :: ID property - -UUIDs on =CUSTOM_ID= property is admittedly a kludge. This is done for -reasons of portability. We may at some point rename this property -=UUID= (TBD). - -Most of the time these Ids don't add any information for the reader - -the UUIDs are used to index and graph documents, IDs are for -convenience. -** Macros -:PROPERTIES: -:CUSTOM_ID: cdb4976b-1d0d-49df-bfb1-3dbd5d99590e -:END: -Several *global* [[https://orgmode.org/manual/Macro-Replacement.html][Org Macros]] are used throughout our documents. They are listed -here for convenience. - -#+name: ulang-macros -#+begin_src emacs-lisp :exports both :results replace pp - org-export-global-macros -#+end_src - -#+RESULTS: ulang-macros -: (("header" . -: "#+TITLE: $1\n#+AUTHOR: $2\n#+EMAIL: $3\n#+DESCRIPTION: $4\n#+SUBTITLE: $4\n#+OPTIONS: ^:nil toc:nil num:nil html-postamble:nil\n#+HTML_HEAD: \n#+HTML_HEAD: \n#+HTML_HEAD: \n") -: ("opts" . "#+OPTIONS: $1\n")) - -Macros /are not expanded/ in source files - you will see them in the -form ={{{NAME(ARGS)}}}=. You will need the relevant macro definition -(in =ulang.el=) in order to use some Org-Mode functions (org-export) -with our docs. -