# HG changeset patch # User Richard Westhaver # Date 1717303361 14400 # Node ID 411eeaebc6d28530f2729d7c9ee4a06c36e373bb # Parent 889970442a125a7ee75d5421ef679ae299f95f14 doc updates diff -r 889970442a12 -r 411eeaebc6d2 core/api.org --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/core/api.org Sun Jun 02 00:42:41 2024 -0400 @@ -0,0 +1,16 @@ +#+title: Core API +#+author: Richard Westhaver +#+options: ^:nil toc:nil num:nil html-postamble:nil +#+export_file_name: index + +This documentation is automatically generated based on the default +branch of the [[https://vc.compiler.company/comp/core][core]]. + +#+begin_src lisp :results silent +(ql:quickload :user) +#+end_src + +#+begin_src lisp :results output replace +#+end_src + +#+RESULTS: diff -r 889970442a12 -r 411eeaebc6d2 core/api/readme.org --- a/core/api/readme.org Mon May 27 22:04:39 2024 -0400 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,41 +0,0 @@ -{{{header(Core API Docs,Richard Westhaver,ellis@rwest.io)}}} -#+OPTIONS: ^:nil toc:nil num:nil html-postamble:nil -#+EXPORT_FILE_NAME: index - -=TODO= - -This documentation is automatically generated based on the default -branch of the [[https://vc.compiler.company/comp/core][core]]. - -#+begin_src lisp :results silent -(ql:quickload :dot) -#+end_src - -#+begin_src lisp :results output replace - (defmethod dot:graph-object-node ((graph (eql 'core-api)) (obj cons)) - (make-instance 'dot:node - :attributes '(:shape :box))) - - (defmethod dot:graph-object-points-to ((graph (eql 'core-api)) (obj cons)) - (list (car obj) - (make-instance 'dot:attributed - :object (cdr obj) - :attributes '(:weight 3)))) - - (defmethod graph-object-node ((graph (eql 'core-api)) (obj symbol)) - (make-instance 'dot:node - :attributes `(:label ,obj - :shape :hexagon))) - - - (dot:print-graph - (dot:generate-graph-from-roots 'core-api (list) - '(:rankdir "LR" :layout "twopi" :labelloc "t"))) -#+end_src - -#+RESULTS: -: digraph { -: rankdir=LR; -: layout="twopi"; -: labelloc="t"; -: } diff -r 889970442a12 -r 411eeaebc6d2 core/app/cc-init.org --- a/core/app/cc-init.org Mon May 27 22:04:39 2024 -0400 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,16 +0,0 @@ -{{{header(cc-init,Richard Westhaver,ellis@rwest.io)}}} -* help -#+begin_src shell :results pp replace -cc-init -h -#+end_src - -#+RESULTS: -: cc-init 0.1.0-0941fa04c53d+ (x86_64-linux-gnu) -: -: Usage: cc-init [OPTIONS] -: -: Options: -: -y Disable confirmation prompts -: -l, --level... Set the log level -: -h, --help Print help -: -V, --version Print version diff -r 889970442a12 -r 411eeaebc6d2 core/app/diz.org --- a/core/app/diz.org Mon May 27 22:04:39 2024 -0400 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,8 +0,0 @@ -{{{header(diz,Richard Westhaver,ellis@rwest.io)}}} - -The ~diz~ disassembly tool. - -* help -#+begin_src shell -diz -h -#+end_src diff -r 889970442a12 -r 411eeaebc6d2 core/app/homer.org --- a/core/app/homer.org Mon May 27 22:04:39 2024 -0400 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,20 +0,0 @@ -{{{header(homer,Richard Westhaver,ellis@rwest.io)}}} -* help -#+begin_src shell :results pp replace -homer -h -#+end_src - -#+RESULTS: -#+begin_example -homer v0.1.0 - usage: homer [global] [] - - home manager - options: - -l/--level* : set the log level - -h/--help* : print help - -v/--version* : print version - commands: - show - -#+end_example diff -r 889970442a12 -r 411eeaebc6d2 core/app/krypt.org --- a/core/app/krypt.org Mon May 27 22:04:39 2024 -0400 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,25 +0,0 @@ -{{{header(kyrpt,Richard Westhaver,ellis@rwest.io)}}} -* help -#+begin_src shell :results pp replace -krypt -h -#+end_src - -#+RESULTS: -#+begin_example -Krypt CLI - -Usage: krypt [OPTIONS] [COMMAND] - -Commands: - check check service providers and config - show Show Krypt info - search Query the Krypt - help Print this message or the help of the given subcommand(s) - -Options: - -c, --cfg Set the default config file [env: KRYPT_CONFIG_FILE=] - -u, --user Set a user for this command [env: USER=ellis] - -l, --level... Set log level - -h, --help Print help - -V, --version Print version -#+end_example diff -r 889970442a12 -r 411eeaebc6d2 core/app/mailman.org --- a/core/app/mailman.org Mon May 27 22:04:39 2024 -0400 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,26 +0,0 @@ -{{{header(mailman,Richard Westhaver,ellis@rwest.io)}}} -* help -#+begin_src shell :results pp replace -mailman -h -#+end_src - -#+RESULTS: -#+begin_example -Mail client util - -Usage: mailman [OPTIONS] [COMMAND] - -Commands: - ping Ping the server - search Search for items - import Import an account - export Export an account - help Print this message or the help of the given subcommand(s) - -Options: - -c, --cfg Set the default config file [env: MAILMAN_CONFIG_FILE=] - -u, --user Set a user for this command [env: USER=ellis] - -l, --level... Set log level - -h, --help Print help - -V, --version Print version -#+end_example diff -r 889970442a12 -r 411eeaebc6d2 core/app/organ.org --- a/core/app/organ.org Mon May 27 22:04:39 2024 -0400 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,46 +0,0 @@ -{{{header(organ,Richard Westhaver,ellis@rwest.io)}}} - -The =organ= CLI tool is used to manipulate [[https://orgmode.org/][Org Mode]] files. - -* Overview -=Org-mode= the application depends on Emacs (it's written in Emacs -Lisp) but that doesn't mean we need to. To solve the issue of -interoperability between different systems, we are developing a tool -called [[https://lab.rwest.io/comp/core/-/tree/branch/default/lisp/lib/organ][organ]]. The purpose of =organ= is to provide an external API for -Org documents that doesn't depend on GNU Emacs. - -If we were designing a /personal/ note-taking system, I would argue -that we don't need this tool. The problem is it's /not/ personal - we -have a much wider intended audience and need to present information in -many different ways. This means thinking about hundreds to thousands -of documents instead of tens, about processing those documents into a -full-text search database, and reducing cost along the way. - -Emacs can do all of these things, but do you really want it to? - -* help -#+begin_src shell :results pp replace -organ -h -#+end_src - -#+RESULTS: -#+begin_example -organ v0.0.1 - usage: organ [global] [] - - org-mode toolbox - options: - -l/--level* : set the log level - -h/--help* : print help - -v/--version* : print version - commands: - inspect : inspect an org file - -i/--input : path to org file - - show : display local org info - - parse - -i/--input : input source - -o/--output : compiler output - -#+end_example diff -r 889970442a12 -r 411eeaebc6d2 core/app/packy.org --- a/core/app/packy.org Mon May 27 22:04:39 2024 -0400 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,10 +0,0 @@ -{{{header(packy,Richard Westhaver,ellis@rwest.io)}}} - -Packy is a universal package manager. The packy CLI tool is used to -query and download resources from local or remote stores. -* help -#+begin_src shell :results pp replace -packy -h -#+end_src - -#+RESULTS: diff -r 889970442a12 -r 411eeaebc6d2 core/app/rdb.org --- a/core/app/rdb.org Mon May 27 22:04:39 2024 -0400 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,19 +0,0 @@ -{{{header(rdb,Richard Westhaver,ellis@rwest.io)}}} - -The =rdb= cli tool is a simple RocksDB management utility. - -* help -#+begin_src shell :results pp replace -rdb -h -#+end_src - -#+RESULTS: -: rdb v0.1.0 -: usage: rdb [global] [] -: -: richard's database -: options: -: -l/--level* : set the log level -: -h/--help* : print help -: -v/--version* : print version -: commands: diff -r 889970442a12 -r 411eeaebc6d2 core/app/readme.org --- a/core/app/readme.org Mon May 27 22:04:39 2024 -0400 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,13 +0,0 @@ -{{{header(Core App Docs,Richard Westhaver,ellis@rwest.io)}}} -#+OPTIONS: ^:nil toc:nil num:nil html-postamble:nil -#+EXPORT_FILE_NAME: index -* [[file:skel.org][skel]] :lisp: -* [[file:organ.org][organ]] :lisp: -* [[file:packy.org][packy]] :lisp: -* [[file:homer.org][homer]] :lisp: -* [[file:rdb.org][rdb]] :lisp: -* [[file:diz.org][diz]] :lisp: -* [[file:tz.org][tz]] :rust: -* [[file:mailman.org][mailman]] :rust: -* [[file:cc-init.org][cc-init]] :rust: -* [[file:krypt.org][krypt]] :rust: diff -r 889970442a12 -r 411eeaebc6d2 core/app/skel.org --- a/core/app/skel.org Mon May 27 22:04:39 2024 -0400 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,187 +0,0 @@ -{{{header(skel,Richard Westhaver,ellis@rwest.io)}}} - -The =skel= CLI is the primary build tool for contributors and serves a -similar role to language-agnostic build tools like [[https://www.gnu.org/software/make/][GNU Make]], but with -the features and ease-of-use of language-specific build tools like -Rust's [[https://github.com/rust-lang/cargo][Cargo]]. - -* features -** configuration -The ~skel~ tool can be configured at runtime using the CLI flags, or -via local configuration files. The configuration files are in the -~skelfile~ format and are assigned the following locations by default: -- ~*default-user-skelrc*~ :: =$HOME/.skelrc= -- ~*default-system-skelrc*~ :: =/etc/skel/skelrc= - -Both files are optional and the user skelrc takes precedence over -system. - -Example =~/.skelrc=: -#+begin_src skel :results pp replace :exports both - ;;; .skelrc @ 2023-10-12.02:58:08 -*- mode: skel; -*- - :author "Richard Westhaver " - :user "ellis" - :version "0.1.0" - :tags ("auto") - :fmt :collapsed - :vc :hg - :auto-insert t - :license "MPL" - :log-level nil - :shed "~/lab/shed" - :stash "~/lab/stash" - :scripts "~/bin/sh" - :alias-list - (("p" "vc push") - ("P" "vc pull") - ("ci" "vc commit")) -#+end_src - -** projects -Projects are the main top-level object users interact with. A project -consists of a list of slots which are populated automatically or by -the user. Once a project is initialized the slots can be accessed and -a set of high-level operations can be performed. - -The easiest way to initialize a project is with a ~skelfile~. These -files are parsed as a simplified Lisp dialect and generate -~sk-project~ objects based on their contents. - -The simplest project looks like this: - -#+begin_src skel :results pp replace :exports both -:name hello-world -#+end_src - -Don't worry, this is still lisp - the parentheses are implied. All we -actually need is a name to generate an object, and we can fill in the -blanks later as the project develops. - -Here is a more verbose example, still with only metadata: - -#+begin_src skel :results pp replace :exports both -;;; skelfile --- core skelfile -*- mode: skel; -*- -:name "core" -:author "Richard Westhaver " -:version "0.1.0" -:license "MPL" -:description "The Compiler Company Core" -:vc :hg -:tags ("core") -:docs ((:org "readme") (:org "install") (:org "tests") (:org "todo")) -:imports ("lisp/lisp.sk" "rust/rust.sk") -#+end_src - -Another example with rules and components: - -#+begin_src skel -;;; skelfile @ 2023-10-08.02:37:25 -*- mode: skel; -*- -:name skel -:author "ellis" -:version "0.1.0" -:description "a hacker's project compiler" -:license "MPL" -:vc :hg -:tags ("lisp") -:rules ((build () (print (asdf:make :skel/cli))) - (clean () #$rm -rf */*.fasl$#)) -:docs ((:org "readme")) -:components -((:elisp "sk")) -:stash "~/dev/comp/stash" -:shed "~/dev/comp/shed" -:snippets -((autogen #$sbcl --eval '(ql:quickload :app/cli/skel)' --eval '(asdf:make :app/cli/skel)'$#)) -#+end_src -** version control -=skel= integrates closely with our Version Control System (VCS) which -is built on [[https://www.mercurial-scm.org/][Mercurial]], but we also interact with and host many [[https://git-scm.com/][Git]] -repositories. - -The =skel= tool helps us abstract away the differences between git/hg -and make maximum use of their utility. When you run a =skel vc= -command the currently active ~sk-project~ and configuration are used -to determine the appropriate VC backend to call. New backends can of -course be added as extensions. - -** TODO compilers -- State "TODO" from [2023-12-09 Sat 19:28] -One of the most unusual features of =skel= is the compiler set. With -the =skel= CLI you can compile the following types of files for your -project directly from a ~skelfile~: -- Makefile (.mk) -- Lisp system defs (.asd) -- Cargo.toml -- Containerfile -- .hgignore/.gitignore - -We treat skelfiles as the mother of all build formats and consolidate -different formats into our own project DSL. This helps reduce -complexity while increasing capability and portability. - -Project compilation occurs on demand with the =sk compile= command. - -** TODO virtualization -- State "TODO" from [2023-12-09 Sat 18:55] - - =skel= offers a mechanism for generating and running Virtual - Machines (VMs) and Containers. Under the hood we depend on [[https://podman.io/][podman]] - for our container runtime as well as [[https://www.qemu.org/][QEMU]] for some - functionality. - -** TODO emacs integration -- State "TODO" from [2023-12-09 Sat 19:30] -=sk.el= is the Emacs support package for skel. It contains a -=skel-mode= for working with skelfiles and will soon contain -additional built-in integrations for =project.el=, =vc.el=, and more. -** TODO deployment -- State "TODO" from [2023-12-09 Sat 19:37] -** TODO visualization -- State "TODO" from [2023-12-09 Sat 19:37] -* help -#+begin_src shell :results pp replace :exports both -skel -h -#+end_src - -#+RESULTS: -#+begin_example -skel v0.1.1 - usage: skel [global] [] - - A hacker's project compiler and build tool. - options: - -h/--help* : print this message - -v/--version* : print version - -d/--debug* : set log level (debug,info,trace,warn) - -c/--config* : set a custom skel user config - -i/--input : input source - -o/--output : output target - commands: - init : initialize a skelfile in the current directory - -n/--name : project name - - show : describe the project skelfile - -f/--file : path to skelfile - - inspect : inspect the project skelfile - -f/--file : path to skelfile - - make : build project targets - -t/--target : target to build - - run : run a script or command - - push : push the current project upstream - - pull : pull the current project from remote - - clone : clone a remote project - - commit : commit changes to the project vc - - edit : edit a project file - - shell : open the sk-shell interpreter - -#+end_example - diff -r 889970442a12 -r 411eeaebc6d2 core/app/tz.org --- a/core/app/tz.org Mon May 27 22:04:39 2024 -0400 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,12 +0,0 @@ -{{{header(tz,Richard Westhaver,ellis@rwest.io)}}} - -=tz= is a small binary for packing and unpacking compressed archives -(tar+zstd). - -* help -#+begin_src shell :results pp replace -tz -h -#+end_src - -#+RESULTS: -: mtz [pack|unpack|unpackr] PATH diff -r 889970442a12 -r 411eeaebc6d2 core/bin/homer.org --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/core/bin/homer.org Sun Jun 02 00:42:41 2024 -0400 @@ -0,0 +1,26 @@ +#+title: homer +#+author: Richard Westhaver +* help +#+begin_src shell :results pp replace +homer -h +#+end_src + +#+RESULTS: +#+begin_example +homer v0.1.0 --- user home manager + + usage: homer [global] [] + +options: + -l/--level* : set the log level + -h/--help* : print help + -v/--version* : print version + -f/--force* : use force + +commands: + show + check + push + pull + install +#+end_example diff -r 889970442a12 -r 411eeaebc6d2 core/bin/krypt.org --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/core/bin/krypt.org Sun Jun 02 00:42:41 2024 -0400 @@ -0,0 +1,26 @@ +#+title: krypt +#+author: Richard Westhaver +* help +#+begin_src shell :results pp replace +krypt -h +#+end_src + +#+RESULTS: +#+begin_example +Krypt CLI + +Usage: krypt [OPTIONS] [COMMAND] + +Commands: + check check service providers and config + show Show Krypt info + search Query the Krypt + help Print this message or the help of the given subcommand(s) + +Options: + -c, --cfg Set the default config file [env: KRYPT_CONFIG_FILE=] + -u, --user Set a user for this command [env: USER=ellis] + -l, --level... Set log level + -h, --help Print help + -V, --version Print version +#+end_example diff -r 889970442a12 -r 411eeaebc6d2 core/bin/mailman.org --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/core/bin/mailman.org Sun Jun 02 00:42:41 2024 -0400 @@ -0,0 +1,27 @@ +#+title: mailman +#+author: Richard Westhaver +* help +#+begin_src shell :results pp replace +mailman -h +#+end_src + +#+RESULTS: +#+begin_example +Mail client util + +Usage: mailman [OPTIONS] [COMMAND] + +Commands: + ping Ping the server + search Search for items + import Import an account + export Export an account + help Print this message or the help of the given subcommand(s) + +Options: + -c, --cfg Set the default config file [env: MAILMAN_CONFIG_FILE=] + -u, --user Set a user for this command [env: USER=ellis] + -l, --level... Set log level + -h, --help Print help + -V, --version Print version +#+end_example diff -r 889970442a12 -r 411eeaebc6d2 core/bin/organ.org --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/core/bin/organ.org Sun Jun 02 00:42:41 2024 -0400 @@ -0,0 +1,43 @@ +#+title: organ +#+author: Richard Westhaver + +The =organ= CLI tool is used to manipulate [[https://orgmode.org/][Org Mode]] files. + +* Overview +=Org-mode= the application depends on Emacs (it's written in Emacs +Lisp) but that doesn't mean we need to. To solve the issue of +interoperability between different systems, we are developing a tool +called [[https://lab.rwest.io/comp/core/-/tree/branch/default/lisp/lib/organ][organ]]. The purpose of =organ= is to provide an external API for +Org documents that doesn't depend on GNU Emacs. + +If we were designing a /personal/ note-taking system, I would argue +that we don't need this tool. The problem is it's /not/ personal - we +have a much wider intended audience and need to present information in +many different ways. This means thinking about hundreds to thousands +of documents instead of tens, about processing those documents into a +full-text search database, and reducing cost along the way. + +Emacs can do all of these things, but do you really want it to? + +* help +#+begin_src shell :results pp replace +organ -h +#+end_src + +#+RESULTS: +#+begin_example +organ v0.0.1 --- org-mode toolbox + + usage: organ [global] [] + +options: + -l/--level* : set the log level + -h/--help* : print help + -v/--version* : print version + +commands: + inspect : inspect an org file + show : display local org info + describe : describe local org info + parse +#+end_example diff -r 889970442a12 -r 411eeaebc6d2 core/bin/packy.org --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/core/bin/packy.org Sun Jun 02 00:42:41 2024 -0400 @@ -0,0 +1,31 @@ +#+title: packy +#+author: Richard Westhaver + +Packy is a universal package manager. The packy CLI tool is used to +query and download resources from local or remote stores. +* help +#+begin_src shell :results pp replace +packy -h +#+end_src + +#+RESULTS: +#+begin_example +#:debug 0.190001; (#S(CLI-NODE + :KIND OPT + :FORM #)) +packy v0.1.0 --- Universal Package Manager + + usage: packy [global] [] + +options: + -l/--level* : set the log level + -h/--help* : print help + -v/--version* : print version + +commands: + show +#:debug 0.193334; /home/ellis/comp/org/docs/core/bin +; #(#) +; NIL +; #() +#+end_example diff -r 889970442a12 -r 411eeaebc6d2 core/bin/rdb.org --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/core/bin/rdb.org Sun Jun 02 00:42:41 2024 -0400 @@ -0,0 +1,11 @@ +#+title: rdb +#+author: Richard Westhaver + +The =rdb= cli tool is a simple RocksDB management utility. + +* help +#+begin_src shell :results pp replace +rdb -h +#+end_src + +#+RESULTS: diff -r 889970442a12 -r 411eeaebc6d2 core/bin/readme.org --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/core/bin/readme.org Sun Jun 02 00:42:41 2024 -0400 @@ -0,0 +1,12 @@ +#+title: +#+author: Richard Westhaver +#+description: Core Program Docs +#+options: ^:nil toc:nil num:nil html-postamble:nil +#+export_file_name: index +* [[file:skel.org][skel]] :lisp: +* [[file:organ.org][organ]] :lisp: +* [[file:packy.org][packy]] :lisp: +* [[file:homer.org][homer]] :lisp: +* [[file:rdb.org][rdb]] :lisp: +* [[file:mailman.org][mailman]] :rust: +* [[file:krypt.org][krypt]] :rust:lisp: diff -r 889970442a12 -r 411eeaebc6d2 core/bin/skel.org --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/core/bin/skel.org Sun Jun 02 00:42:41 2024 -0400 @@ -0,0 +1,192 @@ +#+title: skel +#+author: Richard Westhaver + +The =skel= CLI is the primary build tool for contributors and serves a +similar role to language-agnostic build tools like [[https://www.gnu.org/software/make/][GNU Make]], but with +the features and ease-of-use of language-specific build tools like +Rust's [[https://github.com/rust-lang/cargo][Cargo]]. + +* features +** configuration +The ~skel~ tool can be configured at runtime using the CLI flags, or +via local configuration files. The configuration files are in the +~skelfile~ format and are assigned the following locations by default: +- ~*default-user-skelrc*~ :: =$HOME/.skelrc= +- ~*default-system-skelrc*~ :: =/etc/skel/skelrc= + +Both files are optional and the user skelrc takes precedence over +system. + +Example =~/.skelrc=: +#+begin_src shell :results output +cat ~/.skelrc +#+end_src + +#+RESULTS: +#+begin_example +;;; .skelrc @ 2023-10-12.02:58:08 -*- mode: skel; -*- +:name "Richard Westhaver " +:user "ellis" +:version "0.1.0" +:tags ("auto") +:fmt :pretty +:vc :hg +:auto-insert t +:license :mpl2 +:log-level :info +:stash ".stash" +;; :scratch ".stash/scratch" +:cache ".cache" +:registry ".data/skel/registry" +:scripts ("/usr/local/share/stash/scripts" "~/stash/scripts") +:alias-list +(("p" "vc push") + ("P" "vc pull") + ("ci" "vc commit")) +#+end_example + +** projects +Projects are the highest-level objects int the ~skel~ system. A project +consists of a list of slots which are populated automatically or by +the user. Once a project is initialized the slots can be accessed and +a set of high-level operations can be performed. + +The easiest way to initialize a project is with a ~skelfile~. These +files are parsed as a simplified Lisp dialect and generate +~sk-project~ objects based on their contents. + +The simplest project looks like this: + +#+begin_src skel :results pp replace :exports both +:name hello-world +#+end_src + +Don't worry, this is still lisp - the parentheses are implied. All we +actually need is a name to generate an object, and we can fill in the +blanks later as the project develops. + +Here is a more verbose example, still with only metadata: + +#+begin_src skel :results pp replace :exports both +;;; skelfile --- core skelfile -*- mode: skel; -*- +:name "core" +:author "Richard Westhaver " +:version "0.1.0" +:license "MPL" +:description "The Compiler Company Core" +:vc :hg +:tags ("core") +:docs ((:org "readme") (:org "install") (:org "tests") (:org "todo")) +:import ("lisp/lisp.sk" "rust/rust.sk") +#+end_src + +Another example with rules and components: + +#+begin_src skel +;;; skelfile @ 2023-10-08.02:37:25 -*- mode: skel; -*- +:name skel +:author "ellis" +:version "0.1.0" +:description "a hacker's project compiler" +:license "MPL" +:vc :hg +:tags ("lisp") +:rules ((build () (print (asdf:make :skel/cli))) + (clean () #$rm -rf */*.fasl$#)) +:docs ((:org "readme")) +:components +((:elisp "sk")) +:stash "~/dev/comp/stash" +#+end_src +** version control +=skel= integrates closely with our Version Control System (VCS) which +is built on [[https://www.mercurial-scm.org/][Mercurial]], but we also interact with and host many [[https://git-scm.com/][Git]] +repositories. + +The =skel= tool helps us abstract away the differences between git/hg +and make maximum use of their utility. When you run a =skel vc= +command the currently active ~sk-project~ and configuration are used +to determine the appropriate VC backend to call. New backends can of +course be added as extensions. + +** TODO compilers +- State "TODO" from [2023-12-09 Sat 19:28] +One of the most unusual features of =skel= is the compiler set. With +the =skel= CLI you can compile the following types of files for your +project directly from a ~skelfile~: +- Makefile (.mk) +- Lisp system defs (.asd) +- Cargo.toml +- Containerfile +- .hgignore/.gitignore + +We treat skelfiles as the mother of all build formats and consolidate +different formats into our own project DSL. This helps reduce +complexity while increasing capability and portability. + +Project compilation occurs on demand with the =sk compile= command. + +** TODO virtualization +- State "TODO" from [2023-12-09 Sat 18:55] + + =skel= offers a mechanism for generating and running Virtual + Machines (VMs) and Containers. Under the hood we depend on [[https://podman.io/][podman]] + for our container runtime as well as [[https://www.qemu.org/][QEMU]] for some + functionality. + +** TODO emacs integration +- State "TODO" from [2023-12-09 Sat 19:30] +=sk.el= is the Emacs support package for skel. It contains a +=skel-mode= for working with skelfiles and will soon contain +additional built-in integrations for =project.el=, =vc.el=, and more. +** TODO deployment +- State "TODO" from [2023-12-09 Sat 19:37] +** TODO visualization +- State "TODO" from [2023-12-09 Sat 19:37] +* help +#+begin_src shell :results pp replace :exports both +skel -h +#+end_src + +#+RESULTS: +#+begin_example +skel v0.1.1 --- A hacker's project compiler. + + usage: skel [global] [] + +options: + -h/--help* : print this message + -v/--version* : print version + -l/--level* : set log level (warn,info,debug,trace) + -c/--config* : set a custom skel user config + -i/--input* : input source + -o/--output* : output target + +commands: + init : initialize a skelfile in the current directory + -n/--name : project name + new : make a new skel project + -n/--name : project name + describe : describe a skelfile + show : show project slots + -f/--file : path to skelfile + -u/--user : print user configuration + -s/--system : print system configuration + vc : version control + -r/--root : repository path + id : print the project id + rev : print the current vc revision id + inspect : inspect the project skelfile + -f/--file : path to skelfile + make : build project targets + -t/--target : target to build + run : run a script or command + status : print the vc status + push : push the current project upstream + pull : pull the current project from remote + clone : clone a remote project + commit : commit changes to the project vc + edit : edit a project file in emacs. + shell : open the sk-shell interpreter +#+end_example + diff -r 889970442a12 -r 411eeaebc6d2 core/ffi.org --- a/core/ffi.org Mon May 27 22:04:39 2024 -0400 +++ b/core/ffi.org Sun Jun 02 00:42:41 2024 -0400 @@ -1,5 +1,5 @@ -{{{header(core/ffi,Richard Westhaver,ellis@rwest.io)}}} - +#+title: ffi +#+author: Richard Westhaver This doc is about the [[https://en.wikipedia.org/wiki/Foreign_function_interface][Foreign Function Interface]] (FFI) features of the =core=. diff -r 889970442a12 -r 411eeaebc6d2 core/install.org --- a/core/install.org Mon May 27 22:04:39 2024 -0400 +++ b/core/install.org Sun Jun 02 00:42:41 2024 -0400 @@ -1,30 +1,12 @@ -{{{header(core/install,Richard Westhaver,ellis@rwest.io,core installation -guide)}}} -#+property: header-args :dir /home/ellis/dev/comp/core/ +#+title: install +#+author: Richard Westhaver +#+email: ellis@rwest.io +#+property: header-args :dir /home/ellis/comp/core/ The core is distributed via our public package registry: [[https://packy.compiler.company][packy.compiler.company]]. You can install any part of the core - from a complete Linux system to individual packages. Refer to the packy documentation for details. -The simplest way to get started is by getting the installer for your -platform with the following script: - -#+begin_src shell :results pp replace :exports both :noeval t -curl --proto '=https' --tlsv1.2 -sSf https://packy.compiler.company/do/init.sh | sh # -s -- --help -#+end_src - -#+RESULTS: -#+begin_example - -cc-init 0.1.0-0941fa04c53d+ - -Usage: cc-init [OPTIONS] - -Options: - -y Disable confirmation prompts - -l, --level... Set the log level - -h, --help Print help - -V, --version Print version #+end_example * TODO Packages - State "TODO" from [2023-11-25 Sat 18:28] diff -r 889970442a12 -r 411eeaebc6d2 core/readme.org --- a/core/readme.org Mon May 27 22:04:39 2024 -0400 +++ b/core/readme.org Sun Jun 02 00:42:41 2024 -0400 @@ -10,14 +10,16 @@ - [[file:todo.org][Todo]] :: Project Tasks - [[file:notes.org][Notes]] :: Internal Notes +* [[file:api.org][API]] +API Docs + * [[file:app][APP]] App Docs - * [[file:lib][LIB]] Library Docs - * [[file:ffi.org][FFI]] FFI Docs - -* [[file:api][API]] -API Reference +* [[file:ref][REF]] +Reference Manual +* [[file:man][MAN]] +User Manual diff -r 889970442a12 -r 411eeaebc6d2 core/stats.org --- a/core/stats.org Mon May 27 22:04:39 2024 -0400 +++ b/core/stats.org Sun Jun 02 00:42:41 2024 -0400 @@ -1,5 +1,6 @@ # -*- org-export-babel-evaluate: nil -*- -{{{header(docs/core,Richard Westhaver,ellis@rwest.io)}}} +#+title: stats +#+author: Richard Westhaver #+property: header-args :dir /home/ellis/comp/core/ * vc #+begin_src shell :results pp :exports results @@ -14,7 +15,8 @@ : 2024-02 5701 ***** : 2024-03 27292 *************************** : 2024-04 23322 *********************** -: 2024-05 15468 *************** +: 2024-05 24141 *********************** +: 2024-06 341 * files #+begin_src shell :results pp :exports results diff -r 889970442a12 -r 411eeaebc6d2 core/tests.org --- a/core/tests.org Mon May 27 22:04:39 2024 -0400 +++ b/core/tests.org Sun Jun 02 00:42:41 2024 -0400 @@ -1,5 +1,6 @@ # -*- org-export-babel-evaluate: nil -*- -{{{header(tests,Richard Westhaver,ellis@rwest.io,core test results)}}} +#+title: tests +#+author: Richard Westhaver #+property: header-args :dir /home/ellis/dev/comp/core/ Unit tests are performed on a per-lang basis and described in the sections below. diff -r 889970442a12 -r 411eeaebc6d2 demo/readme.org --- a/demo/readme.org Mon May 27 22:04:39 2024 -0400 +++ b/demo/readme.org Sun Jun 02 00:42:41 2024 -0400 @@ -1,4 +1,5 @@ -{{{header(docs/demo,Richard Westhaver,ellis@rwest.io)}}} +#+title: demo +#+author: Richard Westhaver #+EXPORT_FILE_NAME: index - [[file:stats.org][Stats]] :: Project Statistics diff -r 889970442a12 -r 411eeaebc6d2 demo/stats.org --- a/demo/stats.org Mon May 27 22:04:39 2024 -0400 +++ b/demo/stats.org Sun Jun 02 00:42:41 2024 -0400 @@ -1,5 +1,18 @@ -{{{header(demo/stats,Richard Westhaver,ellis@rwest.io)}}} -#+property: header-args :dir /home/ellis/dev/comp/demo/ +#+title: stats +#+author: Richard Westhaver +#+property: header-args :dir /home/ellis/comp/demo/ +#+begin_src shell :results pp :exports results + hg churn -f "%Y-%m" -s +#+end_src + +#+RESULTS: +: 2023-04 949 * +: 2023-05 7233 *********** +: 2023-06 37455 ************************************************************* +: 2023-08 99 +: 2023-12 350 +: 2024-04 737 * + #+begin_src shell :results pp :exports results tokei #+end_src @@ -9,11 +22,11 @@ =============================================================================== Language Files Lines Code Comments Blanks =============================================================================== - Lisp 22 688 505 63 120 + Lisp 41 3077 2346 243 488 Makefile 1 23 20 3 0 - Org 2 131 127 0 4 - Shell 1 592 459 63 70 - Plain Text 2 2 0 2 0 + Org 2 45 45 0 0 + Shell 2 618 477 64 77 + Plain Text 4 6 0 6 0 TOML 6 85 81 0 4 ------------------------------------------------------------------------------- HTML 1 7 7 0 0 @@ -24,6 +37,6 @@ |- Markdown 9 36 0 32 4 (Total) 779 635 35 109 =============================================================================== - Total 52 2271 1834 134 303 + Total 74 4604 3611 319 674 =============================================================================== #+end_example diff -r 889970442a12 -r 411eeaebc6d2 infra/quickstart.org --- a/infra/quickstart.org Mon May 27 22:04:39 2024 -0400 +++ b/infra/quickstart.org Sun Jun 02 00:42:41 2024 -0400 @@ -4,8 +4,7 @@ Infra Quickstart Guide)}}} #+property: header-args :dir /home/ellis/comp/infra/ -The CC =infra= project can be thought of as one big Makefile, and -currently it is one. +The CC =infra= project is the CC software deployment toolkit. - *Host Requirements* - x86_64 4 core CPU @@ -59,21 +58,12 @@ | CARGO_HOME= | | RUSTUP_HOME= | -* TODO install.sh -Install core dependencies. - -This script will install missing core binaries and libraries to the -=infra= stash directory. -- sbcl -- librocksdb -- rust - * TODO bootstrap.sh Bootstrap the core. -- download and run =cc-install= -- install the latest =infra= lisp core from - https://packy.compiler.company to the stash +- download and prepare target-specific dependencies +- install the latest =sk= binary from https://packy.compiler.company + to the stash - compile and load =bootstrap.lisp= Upon completion a local =stash= directory is provisioned. At this @@ -95,3 +85,7 @@ the build-config and skelfile slots. Production deployments end up at https://packy.compiler.company. + + +* TODO install.lisp +Install core packages locally. diff -r 889970442a12 -r 411eeaebc6d2 infra/stats.org --- a/infra/stats.org Mon May 27 22:04:39 2024 -0400 +++ b/infra/stats.org Sun Jun 02 00:42:41 2024 -0400 @@ -1,8 +1,26 @@ -{{{header(docs/core,Richard Westhaver,ellis@rwest.io)}}} +#+title: stats +#+author: Richard Westhaver +#+email: ellis@rwest.io #+property: header-args :dir /home/ellis/comp/infra/ +#+begin_src shell :results pp + hg churn -f "%Y-%m" -s +#+end_src + +#+RESULTS: +: 2023-07 61 +: 2023-11 5004 *************************** +: 2023-12 2690 ************** +: 2024-01 11278 ************************************************************* +: 2024-02 1021 ***** +: 2024-03 21 +: 2024-04 2063 *********** +: 2024-05 8443 ********************************************* +: 2024-06 35 + + #+begin_src shell :results pp :exports results - tokei -e{build,cdn,dist}/* + tokei -e{.stash}/* #+end_src #+RESULTS: @@ -11,10 +29,10 @@ Language Files Lines Code Comments Blanks =============================================================================== Lisp 4 208 144 21 43 - Makefile 1 276 213 28 35 + Makefile 1 277 214 28 35 Org 3 36 30 0 6 - Shell 56 1726 1276 270 180 + Shell 70 1584 1147 283 154 =============================================================================== - Total 64 2246 1663 319 264 + Total 78 2105 1535 332 238 =============================================================================== #+end_example diff -r 889970442a12 -r 411eeaebc6d2 readme.org --- a/readme.org Mon May 27 22:04:39 2024 -0400 +++ b/readme.org Sun Jun 02 00:42:41 2024 -0400 @@ -1,12 +1,24 @@ -{{{header( - docs, - Richard Westhaver, - ellis@rwest.io, - The Compiler Company Documentation)}}} +#+title: Documentation +#+author: Richard Westhaver +#+email: ellis@rwest.io +#+description: The Compiler Company Documentation Repository #+EXPORT_FILE_NAME: index +This project contains the sources for all CC documentation. Choose one +of the categories below to get started. + * [[file:meta][Meta]] +Meta-docs. Contains some internal system ramblings. * [[file:core][Core]] +Documentation for the Core software suite. * [[file:infra][Infra]] +Infrastructure Documentation. * products +Products are a moving target for us at the moment. This section is +bound to change. ** [[https://compiler.company/docs/nas-t][NAS-T]] +Network Attached Storage Technology. + +LAN Boxes and modules. Storage Tech Consulting, Distributed +Infra/Compute. +** OTOM8