# HG changeset patch # User Richard Westhaver # Date 1723385371 14400 # Node ID e8da1c55dcbe884d4c55d561000c919bfc325d61 init meta diff -r 000000000000 -r e8da1c55dcbe .hgignore --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/.hgignore Sun Aug 11 10:09:31 2024 -0400 @@ -0,0 +1,1 @@ +[.]html \ No newline at end of file diff -r 000000000000 -r e8da1c55dcbe business.org --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/business.org Sun Aug 11 10:09:31 2024 -0400 @@ -0,0 +1,17 @@ +#+title: business +#+author: Richard Westhaver +#+email: ellis@rwest.io +#+description: The Compiler Company Business Model +#+setupfile: ../../clean.theme +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 000000000000 -r e8da1c55dcbe mindset.org --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/mindset.org Sun Aug 11 10:09:31 2024 -0400 @@ -0,0 +1,4 @@ +#+title: mindset +#+author: Richard Westhaver +#+description: A Reflection on the CC Mindset +#+setupfile: ../../clean.theme diff -r 000000000000 -r e8da1c55dcbe pitch.org --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/pitch.org Sun Aug 11 10:09:31 2024 -0400 @@ -0,0 +1,31 @@ +#+title: the big picture +#+author: Richard Westhaver +#+setupfile: ../../clean.theme +* Get Off of My Cloud + - industry has moved away from client-side, distributed compute in + favor of centralized server-side compute resources behind API + gateways. + - entire businesses are built on a single Cloud Provider and are + fundamentally incapable of moving off that Cloud. + - they /think/ in terms of that Provider. The Provider influences + all of their decisions. + - users control very little compute power + - personal computing hardware (consumer-grade) is limited in capability + - non-servicable architectures, planned obsolescence, closed firmware + - mainstream operating systems don't optimize for resource + efficiency - they maximize for the volume of telemetry data they + can collect and profit from + +* Death of the Programmer + - The role of the programmer is changing + - programmers are no longer required to understand how computers + work to have a successful career + - Cloud Providers wrap all low-level details in their own + proprietary vocabulary and APIs + - To program on the cloud, you need to use the Cloud vocabulary + and are discouraged from thinking of computers as they actually + exist in the real world + - Cloud Providers influence college cirruculums, replacing compute + and systems theory with courses designed to teach you how to + configure Cloud Services. + diff -r 000000000000 -r e8da1c55dcbe readme.org --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/readme.org Sun Aug 11 10:09:31 2024 -0400 @@ -0,0 +1,12 @@ +#+title: Meta Docs +#+author: Richard Westhaver +#+email: ellis@rwest.io +#+OPTIONS: ^:nil toc:nil num:nil html-postamble:nil +#+EXPORT_FILE_NAME: index +#+setupfile: ../../clean.theme +* [[file:ulang.org][ulang]] +* [[file:style.org][style]] +* [[file:tech.org][tech]] +* [[file:business.org][business]] +* [[file:mindset.org][mindset]] +* [[file:workflows.org][workflows]] diff -r 000000000000 -r e8da1c55dcbe style.org --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/style.org Sun Aug 11 10:09:31 2024 -0400 @@ -0,0 +1,66 @@ +#+title: The Compiler Company Styleguide +#+author: Richard Westhaver +#+email: ellis@rwest.io +#+setupfile: ../../clean.theme +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 +- use LSP wherever possible (eglot, slime) +* 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 built-ins - if a function or class is generally + useful, add it to the core +- use conditions, restarts, and error handling where appropriate +- save type declarations and hairy optimizations for when the API is + polished +- don't be afraid of macros +** Systems +- define systems using keyword symbols +- use slash instead of dash for path separation in system names: =:foo/bar= +- define your test system in the same file with a name of: =:foo/tests= +- where possible, avoid collisions with systems in Quicklisp +** Packages +- declare packages in a file named =pkg.lisp= +- when multiple packages are being declared, consider a wrapper + package + - declare with ~UIOP:DEFINE-PACKAGE~ and ~:USE-REEXPORT~ +- package names are either the same as their system name or have the + system name as their root path. +- use ~:NICKNAMES~ to declare alternative names for your package +** CLOS +- prefer =:default-initargs= over =:initform=. +* Rust +- always prefer =core= libraries to vendored dependencies +- don't make =mod.rs= files + - use the =foo.rs=, =foo/*= pattern instead +- derive =Debug= and =Clone= always +- write a sensible =Display= impl +- derive default methods for =Default=, =Hash=, =Copy=, etc where possible +- use generics where appropriate: =foo>(path:P){p.as_ref();}= +* Emacs Lisp +* Org-mode +* Shell +* Python diff -r 000000000000 -r e8da1c55dcbe tech.org --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/tech.org Sun Aug 11 10:09:31 2024 -0400 @@ -0,0 +1,66 @@ +#+title: tech +#+author: Richard Westhaver +#+email: ellis@rwest.io +#+description: The Compiler Company Core Technologies +#+setupfile: ../../clean.theme + +* 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]] + +* Our Software +The software provided by /The Compiler Company/ is a powerful but +opinionated programming environment. It consists of a GNU/Linux +kernel, some vendored programs and libraries, and a suite of custom +software. + +The software is modular by design. You can pick and choose which +components to embed in your own projects and you are encouraged to +modify any part of the system to meet your goals. + +In general, our software is designed for: +- early adoption :: integrate research, protocols, libraries, and + hardware features from leading research orgs faster than anyone else +- rapid development :: interaction, code introspection, tooling, and + automation built for prototyping at massive scale +- power :: using our environment should feel like cheating - macros, + DSLs, and unmatched hackability + +** Langs +/The Compiler Company/ is above all, a =Lisp Company=. The most +powerful software requires the most powerful code. + +Lisp isn't enough though. =Rust= is our imperative language of choice +at the time of writing and generally suited for system-level software +components. + +We make use of the Steel Bank Common Lisp compiler (SBCL) and the +nightly Rust compiler toolchain. + +** OS +/The Compiler Company/ is a =Linux Company=. There may be minimal +support for Darwin-based systems, but Microsoft Windows systems will +never be officially supported. + +One of the /anti-goals/ of our software is ~portability~. For all of +the features we optimize for, portability becomes a burden, especially +with closed-source OS kernels. We are also explicitly driven to reduce +consumer dependence on these closed-source systems, especially in a +distributed network. They are simply unfit for use with the software +we produce and the systems we build. diff -r 000000000000 -r e8da1c55dcbe ulang.org --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/ulang.org Sun Aug 11 10:09:31 2024 -0400 @@ -0,0 +1,163 @@ +#+title: Universal Languages +#+author: Richard Westhaver +#+email: ellis@rwest.io +#+OPTIONS: toc:t +#+setupfile: ../../clean.theme + +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: +: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: +: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 :: ID property +- User-defined :: CUSTOM_ID property + +Most of the time these Ids don't add any information for the reader - +the UUIDs are used to index and graph documents, CUSTOM_IDs are for +convenience but are rarely necessary given the many ways of +identifying a headline. +** Macros +:PROPERTIES: +: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 000000000000 -r e8da1c55dcbe workflows.org --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/workflows.org Sun Aug 11 10:09:31 2024 -0400 @@ -0,0 +1,17 @@ +#+title: meta/workflows +#+author: Richard Westhaver +#+email: ellis@rwest.io +#+description: Meta Workflows +#+setupfile: ../../clean.theme + +* Task Management + +* Project Management + +* Roadmap + +* Source Code Management + +* Data Management + +* Resource Management