1.1--- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2+++ b/.hgignore Sun Aug 11 10:09:31 2024 -0400
1.3@@ -0,0 +1,1 @@
1.4+[.]html
1.5\ No newline at end of file
2.1--- /dev/null Thu Jan 01 00:00:00 1970 +0000
2.2+++ b/business.org Sun Aug 11 10:09:31 2024 -0400
2.3@@ -0,0 +1,17 @@
2.4+#+title: business
2.5+#+author: Richard Westhaver
2.6+#+email: ellis@rwest.io
2.7+#+description: The Compiler Company Business Model
2.8+#+setupfile: ../../clean.theme
2.9+In short, this document describes the business aspects of The Compiler
2.10+Company LLC. We are designed to be small, fast, and agile. We
2.11+infiltrate a market, apply our methodology, and develop solutions that
2.12+are simply years ahead of the competition. We treat the market like
2.13+we're the only supplier, because we can. This is in part due to our
2.14+internal research & development pursuits, but also our approach to
2.15+business. We build businesses and revenue streams the exact same way
2.16+we build software -- with a bottom up approach. This is our secret
2.17+weapon, and what gives us the ability to adapt to any environment
2.18+where our interests lie.
2.19+
2.20+#+TOC: headlines 3
3.1--- /dev/null Thu Jan 01 00:00:00 1970 +0000
3.2+++ b/mindset.org Sun Aug 11 10:09:31 2024 -0400
3.3@@ -0,0 +1,4 @@
3.4+#+title: mindset
3.5+#+author: Richard Westhaver
3.6+#+description: A Reflection on the CC Mindset
3.7+#+setupfile: ../../clean.theme
4.1--- /dev/null Thu Jan 01 00:00:00 1970 +0000
4.2+++ b/pitch.org Sun Aug 11 10:09:31 2024 -0400
4.3@@ -0,0 +1,31 @@
4.4+#+title: the big picture
4.5+#+author: Richard Westhaver <ellis@rwest.io>
4.6+#+setupfile: ../../clean.theme
4.7+* Get Off of My Cloud
4.8+ - industry has moved away from client-side, distributed compute in
4.9+ favor of centralized server-side compute resources behind API
4.10+ gateways.
4.11+ - entire businesses are built on a single Cloud Provider and are
4.12+ fundamentally incapable of moving off that Cloud.
4.13+ - they /think/ in terms of that Provider. The Provider influences
4.14+ all of their decisions.
4.15+ - users control very little compute power
4.16+ - personal computing hardware (consumer-grade) is limited in capability
4.17+ - non-servicable architectures, planned obsolescence, closed firmware
4.18+ - mainstream operating systems don't optimize for resource
4.19+ efficiency - they maximize for the volume of telemetry data they
4.20+ can collect and profit from
4.21+
4.22+* Death of the Programmer
4.23+ - The role of the programmer is changing
4.24+ - programmers are no longer required to understand how computers
4.25+ work to have a successful career
4.26+ - Cloud Providers wrap all low-level details in their own
4.27+ proprietary vocabulary and APIs
4.28+ - To program on the cloud, you need to use the Cloud vocabulary
4.29+ and are discouraged from thinking of computers as they actually
4.30+ exist in the real world
4.31+ - Cloud Providers influence college cirruculums, replacing compute
4.32+ and systems theory with courses designed to teach you how to
4.33+ configure Cloud Services.
4.34+
5.1--- /dev/null Thu Jan 01 00:00:00 1970 +0000
5.2+++ b/readme.org Sun Aug 11 10:09:31 2024 -0400
5.3@@ -0,0 +1,12 @@
5.4+#+title: Meta Docs
5.5+#+author: Richard Westhaver
5.6+#+email: ellis@rwest.io
5.7+#+OPTIONS: ^:nil toc:nil num:nil html-postamble:nil
5.8+#+EXPORT_FILE_NAME: index
5.9+#+setupfile: ../../clean.theme
5.10+* [[file:ulang.org][ulang]]
5.11+* [[file:style.org][style]]
5.12+* [[file:tech.org][tech]]
5.13+* [[file:business.org][business]]
5.14+* [[file:mindset.org][mindset]]
5.15+* [[file:workflows.org][workflows]]
6.1--- /dev/null Thu Jan 01 00:00:00 1970 +0000
6.2+++ b/style.org Sun Aug 11 10:09:31 2024 -0400
6.3@@ -0,0 +1,66 @@
6.4+#+title: The Compiler Company Styleguide
6.5+#+author: Richard Westhaver
6.6+#+email: ellis@rwest.io
6.7+#+setupfile: ../../clean.theme
6.8+As an organization we maintain a styleguide[fn:1] which lists all of
6.9+the style guidelines we use for our code. If you are contributing to
6.10+one of our projects, you should review and understand the relevant
6.11+sections below.
6.12+
6.13+You should also review the [[file:ulang.org][ulang]] document, which may shine some light
6.14+on code comments and developer docs.
6.15+
6.16+[fn:1] https://google.github.io/styleguide/
6.17+
6.18+* General Programming
6.19+- indent-offset = 2
6.20+- max-line-width = 80
6.21+- page-length ~ 32
6.22+- module-length ~ 512
6.23+- file-size ~ 1024
6.24+
6.25+- start every source-file with a header comment
6.26+- use outline headings to organize your program
6.27+- use ulang-comments as needed for referencing bugs, notes, etc.
6.28+- inline documentation should be declarative. your code explains your
6.29+ comments for you.
6.30+- variables, imports, and exports belong at the top of a file
6.31+- =main= functions belong at the bottom of a file
6.32+- use LSP wherever possible (eglot, slime)
6.33+* Common Lisp
6.34+- prefer symbol docs to comments
6.35+- use stdin/stdout/stderr correctly - see [[https://zenodo.org/records/3414191][CDR-11]]
6.36+- always prefer =core= libraries over vendored dependencies
6.37+- use the compiler built-ins - if a function or class is generally
6.38+ useful, add it to the core
6.39+- use conditions, restarts, and error handling where appropriate
6.40+- save type declarations and hairy optimizations for when the API is
6.41+ polished
6.42+- don't be afraid of macros
6.43+** Systems
6.44+- define systems using keyword symbols
6.45+- use slash instead of dash for path separation in system names: =:foo/bar=
6.46+- define your test system in the same file with a name of: =:foo/tests=
6.47+- where possible, avoid collisions with systems in Quicklisp
6.48+** Packages
6.49+- declare packages in a file named =pkg.lisp=
6.50+- when multiple packages are being declared, consider a wrapper
6.51+ package
6.52+ - declare with ~UIOP:DEFINE-PACKAGE~ and ~:USE-REEXPORT~
6.53+- package names are either the same as their system name or have the
6.54+ system name as their root path.
6.55+- use ~:NICKNAMES~ to declare alternative names for your package
6.56+** CLOS
6.57+- prefer =:default-initargs= over =:initform=.
6.58+* Rust
6.59+- always prefer =core= libraries to vendored dependencies
6.60+- don't make =mod.rs= files
6.61+ - use the =foo.rs=, =foo/*= pattern instead
6.62+- derive =Debug= and =Clone= always
6.63+- write a sensible =Display= impl
6.64+- derive default methods for =Default=, =Hash=, =Copy=, etc where possible
6.65+- use generics where appropriate: =foo<P:AsRef<Path>>(path:P){p.as_ref();}=
6.66+* Emacs Lisp
6.67+* Org-mode
6.68+* Shell
6.69+* Python
7.1--- /dev/null Thu Jan 01 00:00:00 1970 +0000
7.2+++ b/tech.org Sun Aug 11 10:09:31 2024 -0400
7.3@@ -0,0 +1,66 @@
7.4+#+title: tech
7.5+#+author: Richard Westhaver
7.6+#+email: ellis@rwest.io
7.7+#+description: The Compiler Company Core Technologies
7.8+#+setupfile: ../../clean.theme
7.9+
7.10+* OS
7.11+We primarily support [[https://unix.org][Unix-based]] Operating Systems. Check
7.12+project-specific docs for officially supported targets.
7.13+
7.14+Development and CI is ran on [[https://archlinux.org/][Arch Linux]] (btw).
7.15+* Core
7.16+** [[https://lisp-lang.org/][Lisp]]
7.17+** [[https://www.rust-lang.org/][Rust]]
7.18+** [[https://www.gnu.org/software/emacs/][Emacs]]
7.19+* Libs
7.20+** [[https://rocksdb.org/][rocksdb]]
7.21+** [[https://archlinux.org/pacman/][pacman]]
7.22+** [[https://docs.kernel.org/filesystems/btrfs.html][btrfs]]
7.23+** [[https://tree-sitter.github.io/tree-sitter/][tree-sitter]]
7.24+** [[https://kernel.dk/io_uring.pdf][uring]]
7.25+** [[https://github.com/BLAKE3-team/BLAKE3-specs/blob/master/blake3.pdf][blake3]]
7.26+* Extras
7.27+** [[https://ngn.codeberg.page/k][k]]
7.28+** [[https://mlochbaum.github.io/BQN/][BQN]]
7.29+
7.30+* Our Software
7.31+The software provided by /The Compiler Company/ is a powerful but
7.32+opinionated programming environment. It consists of a GNU/Linux
7.33+kernel, some vendored programs and libraries, and a suite of custom
7.34+software.
7.35+
7.36+The software is modular by design. You can pick and choose which
7.37+components to embed in your own projects and you are encouraged to
7.38+modify any part of the system to meet your goals.
7.39+
7.40+In general, our software is designed for:
7.41+- early adoption :: integrate research, protocols, libraries, and
7.42+ hardware features from leading research orgs faster than anyone else
7.43+- rapid development :: interaction, code introspection, tooling, and
7.44+ automation built for prototyping at massive scale
7.45+- power :: using our environment should feel like cheating - macros,
7.46+ DSLs, and unmatched hackability
7.47+
7.48+** Langs
7.49+/The Compiler Company/ is above all, a =Lisp Company=. The most
7.50+powerful software requires the most powerful code.
7.51+
7.52+Lisp isn't enough though. =Rust= is our imperative language of choice
7.53+at the time of writing and generally suited for system-level software
7.54+components.
7.55+
7.56+We make use of the Steel Bank Common Lisp compiler (SBCL) and the
7.57+nightly Rust compiler toolchain.
7.58+
7.59+** OS
7.60+/The Compiler Company/ is a =Linux Company=. There may be minimal
7.61+support for Darwin-based systems, but Microsoft Windows systems will
7.62+never be officially supported.
7.63+
7.64+One of the /anti-goals/ of our software is ~portability~. For all of
7.65+the features we optimize for, portability becomes a burden, especially
7.66+with closed-source OS kernels. We are also explicitly driven to reduce
7.67+consumer dependence on these closed-source systems, especially in a
7.68+distributed network. They are simply unfit for use with the software
7.69+we produce and the systems we build.
8.1--- /dev/null Thu Jan 01 00:00:00 1970 +0000
8.2+++ b/ulang.org Sun Aug 11 10:09:31 2024 -0400
8.3@@ -0,0 +1,163 @@
8.4+#+title: Universal Languages
8.5+#+author: Richard Westhaver
8.6+#+email: ellis@rwest.io
8.7+#+OPTIONS: toc:t
8.8+#+setupfile: ../../clean.theme
8.9+
8.10+This document describes a *U-Language* as described by the late great
8.11+[[https://iep.utm.edu/haskell-brooks-curry/][Haskell Curry]]:
8.12+
8.13+#+begin_quote
8.14+Every investigation, including the present one, has to be communicated
8.15+from one person to another by means of language. It is expedient to
8.16+begin our study by calling attention to this obvious fact, by giving a
8.17+name to the language being used, and by being explicit about a few of
8.18+its features. We shall call the language being used the
8.19+U-Language. [...] There would be no point in calling attention to it,
8.20+if it were not for the fact that language is more intimately related
8.21+to our job than of most others.
8.22+#+end_quote
8.23+
8.24+In this document, we will be calling attention to our own language -
8.25+examining it, and describing how it works.
8.26+
8.27+Our job is to solve problems. Hard problems preferred. So we ought to
8.28+pay close attention to the language we use because it brings the
8.29+reader and writer /closer/ to the problem at hand.
8.30+
8.31+For starters, we are primarily concerned with /written languages/ like
8.32+the one you're reading now. We will skip past the obvious details -
8.33+English is our primary form of communication for example. The line you
8.34+are reading currently is a sentence which is part of a paragraph.
8.35+
8.36+There are some non-obvious questions which deserve inquiry though.
8.37+
8.38+- *Who is this for?* \\
8.39+ This document is for authors and readers alike. It is a loose
8.40+ specification, but also serves as introductory material into our
8.41+ communication and design philosophy.
8.42+
8.43+- *What is this for?* \\
8.44+ The purpose of this document is to provide a /standard of
8.45+ communication/.
8.46+
8.47+ All sources we write attempt to conform to this standard but this is
8.48+ not strictly enforced. If there is a reason to not comply with a
8.49+ rule, it is already broken.
8.50+
8.51+* Org Mode
8.52+:PROPERTIES:
8.53+:ID: 98a02bb2-3f39-49c6-898a-68ccd8f3cbe1
8.54+:END:
8.55+[[https://www.gnu.org/software/emacs/][GNU Emacs]] is our text editor, so naturally [[https://orgmode.org/][Org Mode]] is our word
8.56+processor.
8.57+
8.58+If you are already familiar with Emacs and Org-Mode, I recommend
8.59+opening the source of this document in Emacs and following along.
8.60+
8.61+If not, I recommend browsing through the [[https://orgmode.org/worg/][Worg resources]], but we won't
8.62+be getting too deep into tribal hacker knowledge of Emacs.
8.63+
8.64+What's important to know is this: There is /Org Syntax/ and
8.65+/Org-mode/ - these are different things.
8.66+
8.67+Our =ulang= is almost /exclusively/ based on /Org Syntax/ and we are
8.68+not concerned about /Org-mode/ the application in this document.
8.69+
8.70+* ulang
8.71+:PROPERTIES:
8.72+:ID: ulang
8.73+:END:
8.74+As the title suggest we refer to our *U-Language* as *ulang*. Each
8.75+section of this document describes a feature.
8.76+** Outlines
8.77+In Org, headings can be summarize as any line starting with a star: =*
8.78+H1=. Headings can be nested or 'demoted' by prepending another star:
8.79+=** H2=.
8.80+
8.81+This is a useful pattern which we apply outside of Org - most commonly
8.82+in our code comments.
8.83+
8.84+In our source code, we use the comment character instead of a star:
8.85+#+begin_src lisp
8.86+;;; foo
8.87+(print "H1") ;; just an inline comment
8.88+;;;; bar
8.89+(print "H2")
8.90+;;; baz
8.91+(print "H1")
8.92+#+end_src
8.93+
8.94+A collection of /headings/ is what we call an *Outline* - which is
8.95+also the name of the major-mode utilized for this feature and of
8.96+course - what Org itself is derived from.
8.97+
8.98+** Keywords
8.99+:PROPERTIES:
8.100+:ID: 2cadda9a-22a3-4b42-ad4e-d7a774f74cba
8.101+:END:
8.102+
8.103+The following keywords indicate the state of an element. They often
8.104+appear as the first word in a heading to indicate a [[*Tasks][Task]].
8.105+
8.106+- TBD :: A task to be done at a later date.
8.107+- TODO :: A task yet to be done.
8.108+- FIXME :: Item that needs fixing.
8.109+- WIP :: Work In Progress task.
8.110+- WAIT :: A suspended task.
8.111+- DEAD :: Item that will not be completed.
8.112+- DONE :: Completed task.
8.113+- BUG :: Designate a bug item.
8.114+- IDEA :: Designate an idea item.
8.115+- NOTE :: Designates a note item.
8.116+- DRAFT :: Designates a draft item.
8.117+- COMMENT :: A 'commented' item.
8.118+** Tasks
8.119+Tasks as they are known in Org, usually consist of a heading that
8.120+starts with a [[#2cadda9a-22a3-4b42-ad4e-d7a774f74cba][Keyword]]. Here we describe some additional sections and
8.121+metadata which are present in our collection of tasks.
8.122+
8.123+Our task management system is roughly a hybrid of two more
8.124+conventional methods: GTD and Agile. For convenience I will describe
8.125+these styles and how I use them separately, but the concepts may be
8.126+spliced differently in real tasks.
8.127+
8.128+- *GTD* \\
8.129+- *Agile* \\
8.130+ It's a dirty word in some tech circles - the dreaded PIs, daily
8.131+ standups, and still nobody knows what's going on, Oh my! Do not
8.132+ worry. For the most part we just borrow the vocabulary.
8.133+
8.134+ Our /Agile/ workflow consists of roadmaps, features (epics/ARTs),
8.135+ issues (user stories), and of course, tasks.
8.136+** IDs
8.137+We reference two different types of identifiers in documentation:
8.138+- UUID :: ID property
8.139+- User-defined :: CUSTOM_ID property
8.140+
8.141+Most of the time these Ids don't add any information for the reader -
8.142+the UUIDs are used to index and graph documents, CUSTOM_IDs are for
8.143+convenience but are rarely necessary given the many ways of
8.144+identifying a headline.
8.145+** Macros
8.146+:PROPERTIES:
8.147+:ID: cdb4976b-1d0d-49df-bfb1-3dbd5d99590e
8.148+:END:
8.149+Several *global* [[https://orgmode.org/manual/Macro-Replacement.html][Org Macros]] are used throughout our documents. They are listed
8.150+here for convenience.
8.151+
8.152+#+name: ulang-macros
8.153+#+begin_src emacs-lisp :exports both :results replace pp
8.154+ org-export-global-macros
8.155+#+end_src
8.156+
8.157+#+RESULTS: ulang-macros
8.158+: (("header" .
8.159+: "#+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: <link rel=\"stylesheet\" href=\"https://fonts.xz.style/serve/inter.css\"/>\n#+HTML_HEAD: <link rel=\"stylesheet\" type=\"text/css\" href=\"https://cdn.compiler.company/css/new.min.css\"/>\n#+HTML_HEAD: <link rel=\"stylesheet\" type=\"text/css\" href=\"https://cdn.compiler.company/css/night.css\"/>\n")
8.160+: ("opts" . "#+OPTIONS: $1\n"))
8.161+
8.162+Macros /are not expanded/ in source files - you will see them in the
8.163+form ={{{NAME(ARGS)}}}=. You will need the relevant macro definition
8.164+(in =ulang.el=) in order to use some Org-Mode functions (org-export)
8.165+with our docs.
8.166+
9.1--- /dev/null Thu Jan 01 00:00:00 1970 +0000
9.2+++ b/workflows.org Sun Aug 11 10:09:31 2024 -0400
9.3@@ -0,0 +1,17 @@
9.4+#+title: meta/workflows
9.5+#+author: Richard Westhaver
9.6+#+email: ellis@rwest.io
9.7+#+description: Meta Workflows
9.8+#+setupfile: ../../clean.theme
9.9+
9.10+* Task Management
9.11+
9.12+* Project Management
9.13+
9.14+* Roadmap
9.15+
9.16+* Source Code Management
9.17+
9.18+* Data Management
9.19+
9.20+* Resource Management
