# HG changeset patch # User ellis # Date 1702173045 18000 # Node ID d0a90a87b8241bf3ba9c751dd7f9347bff8748be # Parent b38886ced111d5d2a339eb69024a5d31b38c1e68 populate diff -r b38886ced111 -r d0a90a87b824 core/app/cc-init.org --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/core/app/cc-init.org Sat Dec 09 20:50:45 2023 -0500 @@ -0,0 +1,16 @@ +{{{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 b38886ced111 -r d0a90a87b824 core/app/homer.org --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/core/app/homer.org Sat Dec 09 20:50:45 2023 -0500 @@ -0,0 +1,20 @@ +{{{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 b38886ced111 -r d0a90a87b824 core/app/krypt.org --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/core/app/krypt.org Sat Dec 09 20:50:45 2023 -0500 @@ -0,0 +1,25 @@ +{{{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 b38886ced111 -r d0a90a87b824 core/app/mailman.org --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/core/app/mailman.org Sat Dec 09 20:50:45 2023 -0500 @@ -0,0 +1,26 @@ +{{{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 b38886ced111 -r d0a90a87b824 core/app/organ.org --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/core/app/organ.org Sat Dec 09 20:50:45 2023 -0500 @@ -0,0 +1,30 @@ +{{{header(organ,Richard Westhaver,ellis@rwest.io)}}} + +The =organ= CLI tool is used to manipulate [[https://orgmode.org/][Org Mode]] files. + +* 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 b38886ced111 -r d0a90a87b824 core/app/packy.org --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/core/app/packy.org Sat Dec 09 20:50:45 2023 -0500 @@ -0,0 +1,10 @@ +{{{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 b38886ced111 -r d0a90a87b824 core/app/rdb.org --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/core/app/rdb.org Sat Dec 09 20:50:45 2023 -0500 @@ -0,0 +1,19 @@ +{{{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 b38886ced111 -r d0a90a87b824 core/app/readme.org --- a/core/app/readme.org Wed Dec 06 23:27:11 2023 -0500 +++ b/core/app/readme.org Sat Dec 09 20:50:45 2023 -0500 @@ -1,3 +1,12 @@ {{{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:tz.org][tz]] :rust: +* [[file:mailman.org][mailman]] :rust: +* [[file:cc-init.org][cc-init]] :rust: +* [[file:krypt.org][krypt]] :rust: diff -r b38886ced111 -r d0a90a87b824 core/app/skel.org --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/core/app/skel.org Sat Dec 09 20:50:45 2023 -0500 @@ -0,0 +1,166 @@ +{{{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 + +** 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 b38886ced111 -r d0a90a87b824 core/app/tz.org --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/core/app/tz.org Sat Dec 09 20:50:45 2023 -0500 @@ -0,0 +1,12 @@ +{{{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 b38886ced111 -r d0a90a87b824 core/lib/alch.org --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/core/lib/alch.org Sat Dec 09 20:50:45 2023 -0500 @@ -0,0 +1,1 @@ +{{{header(alch,Richard Westhaver,ellis@rwest.io)}}} diff -r b38886ced111 -r d0a90a87b824 core/lib/audio.org --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/core/lib/audio.org Sat Dec 09 20:50:45 2023 -0500 @@ -0,0 +1,1 @@ +{{{header(audio,Richard Westhaver,ellis@rwest.io)}}} diff -r b38886ced111 -r d0a90a87b824 core/lib/crypto.org --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/core/lib/crypto.org Sat Dec 09 20:50:45 2023 -0500 @@ -0,0 +1,1 @@ +{{{header(crypto,Richard Westhaver,ellis@rwest.io)}}} diff -r b38886ced111 -r d0a90a87b824 core/lib/db.org --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/core/lib/db.org Sat Dec 09 20:50:45 2023 -0500 @@ -0,0 +1,1 @@ +{{{header(db,Richard Westhaver,ellis@rwest.io)}}} diff -r b38886ced111 -r d0a90a87b824 core/lib/dl.org --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/core/lib/dl.org Sat Dec 09 20:50:45 2023 -0500 @@ -0,0 +1,1 @@ +{{{header(dl,Richard Westhaver,ellis@rwest.io)}}} diff -r b38886ced111 -r d0a90a87b824 core/lib/dot.org --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/core/lib/dot.org Sat Dec 09 20:50:45 2023 -0500 @@ -0,0 +1,1 @@ +{{{header(dot,Richard Westhaver,ellis@rwest.io)}}} diff -r b38886ced111 -r d0a90a87b824 core/lib/flate.org --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/core/lib/flate.org Sat Dec 09 20:50:45 2023 -0500 @@ -0,0 +1,1 @@ +{{{header(flate,Richard Westhaver,ellis@rwest.io)}}} diff -r b38886ced111 -r d0a90a87b824 core/lib/hash.org --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/core/lib/hash.org Sat Dec 09 20:50:45 2023 -0500 @@ -0,0 +1,1 @@ +{{{header(hash,Richard Westhaver,ellis@rwest.io)}}} diff -r b38886ced111 -r d0a90a87b824 core/lib/krypt.org --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/core/lib/krypt.org Sat Dec 09 20:50:45 2023 -0500 @@ -0,0 +1,1 @@ +{{{header(krypt,Richard Westhaver,ellis@rwest.io)}}} diff -r b38886ced111 -r d0a90a87b824 core/lib/logger.org --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/core/lib/logger.org Sat Dec 09 20:50:45 2023 -0500 @@ -0,0 +1,1 @@ +{{{header(logger,Richard Westhaver,ellis@rwest.io)}}} diff -r b38886ced111 -r d0a90a87b824 core/lib/net.org --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/core/lib/net.org Sat Dec 09 20:50:45 2023 -0500 @@ -0,0 +1,1 @@ +{{{header(net,Richard Westhaver,ellis@rwest.io)}}} diff -r b38886ced111 -r d0a90a87b824 core/lib/nlp.org --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/core/lib/nlp.org Sat Dec 09 20:50:45 2023 -0500 @@ -0,0 +1,1 @@ +{{{header(nlp,Richard Westhaver,ellis@rwest.io)}}} diff -r b38886ced111 -r d0a90a87b824 core/lib/obj.org --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/core/lib/obj.org Sat Dec 09 20:50:45 2023 -0500 @@ -0,0 +1,1 @@ +{{{header(obj,Richard Westhaver,ellis@rwest.io)}}} diff -r b38886ced111 -r d0a90a87b824 core/lib/organ.org --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/core/lib/organ.org Sat Dec 09 20:50:45 2023 -0500 @@ -0,0 +1,1 @@ +{{{header(organ,Richard Westhaver,ellis@rwest.io)}}} diff -r b38886ced111 -r d0a90a87b824 core/lib/packy.org --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/core/lib/packy.org Sat Dec 09 20:50:45 2023 -0500 @@ -0,0 +1,1 @@ +{{{header(packy,Richard Westhaver,ellis@rwest.io)}}} diff -r b38886ced111 -r d0a90a87b824 core/lib/rdb.org --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/core/lib/rdb.org Sat Dec 09 20:50:45 2023 -0500 @@ -0,0 +1,1 @@ +{{{header(rdb,Richard Westhaver,ellis@rwest.io)}}} diff -r b38886ced111 -r d0a90a87b824 core/lib/readme.org --- a/core/lib/readme.org Wed Dec 06 23:27:11 2023 -0500 +++ b/core/lib/readme.org Sat Dec 09 20:50:45 2023 -0500 @@ -1,3 +1,25 @@ {{{header(Core Lib 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:rdb.org][rdb]] :lisp: +* [[file:nlp.org][nlp]] :lisp: +* [[file:dot.org][dot]] :lisp: +* [[file:alch.org][alch]] :rust: +* [[file:audio.org][audio]] :rust: +* [[file:crypto.org][crypto]] :rust: +* [[file:logger.org][logger]] :rust: +* [[file:krypt.org][krypt]] :rust: +* [[file:sxp.org][sxp]] :rust: +* [[file:tenex.org][tenex]] :rust: +* [[file:util.org][util]] :rust: +* [[file:obj.org][obj]] :rust: +* [[file:net.org][net]] :rust: +* [[file:flate.org][flate]] :rust: +* [[file:db.org][db]] :rust: +* [[file:dl.org][dl]] :rust: +* [[file:hash.org][hash]] :rust: diff -r b38886ced111 -r d0a90a87b824 core/lib/skel.org --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/core/lib/skel.org Sat Dec 09 20:50:45 2023 -0500 @@ -0,0 +1,51 @@ +{{{header(skel,Richard Westhaver,ellis@rwest.io)}}} + +=skel= is /a hacker's project compiler and build tool/. It is an +extensible software library designed for managing /projects/. + +The [[https://compiler.company/docs/core/app/skel.html][cli]] is the main entry point for typical users. This documentation +is for library developers and internal use. + +* Overview +This library started as a Rust crate but was re-written in Lisp as the +purpose of the library grew from managing a small collection of +user-space libraries (also written in Rust) to managing large +collections in many different langs. + +It is obvious in hindsight, that this project needs Lisp. Today we are +built on CLOS with classes and methods exposing the library API. + +* Design +The library core is built on CLOS. Most important data structures are +represented with classes, slots, and methods such as the ~sk-project~ +class which has a slot named ~:components~ and a method specialized on +it called ~load-ast~. + +We make use of mixins defined within the library like ~sk-meta~ as +well as classes defined downstream - the ~sxp~ class for example +provides a default method for AST functions (~load-ast~ ~build-ast~) +and is defined in the ~std/sxp~ package. + +On top of the core we build our compilers or 'translators' which +convert core objects to a corresponding external representation. For +example the ~makefile~ and ~mk-*~ classes defined in ~skel/comp/make~ +can be built from a ~sk-project~ and ~sk-*~ instances. Once built, the +~sk-compile~ method can be used to actually generate the GNU Make +output as a stream of bytes. + +The remainder of the ~skel~ system is dedicated to extensions. These +are all optional. There are built-in extension called ~tools~ which +run within the ~skel~ system and external extensions (~ext~) which +integrate with a particular external system. + +The ~tools~ we provide are similar to Cargo's [[https://doc.rust-lang.org/book/ch14-05-extending-cargo.html][custom commands]], but +they don't need to be a separate binary - they can be compiled into +the core image. The downside is that this requires re-compiling ~skel~ +every time you want to add a new tool. However since this is Lisp not +Rust, we can compile anywhere - including from within ~skel~ +itself. + +~ext~ contains extensions for external systems. These modules are the +'edges' of the system and provide support to programs which need to be +able to access ~skel~ data at runtime. These modules always compiled +separately and aren't built into the default core image. diff -r b38886ced111 -r d0a90a87b824 core/lib/sxp.org --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/core/lib/sxp.org Sat Dec 09 20:50:45 2023 -0500 @@ -0,0 +1,1 @@ +{{{header(sxp,Richard Westhaver,ellis@rwest.io)}}} diff -r b38886ced111 -r d0a90a87b824 core/lib/tenex.org --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/core/lib/tenex.org Sat Dec 09 20:50:45 2023 -0500 @@ -0,0 +1,1 @@ +{{{header(tenex,Richard Westhaver,ellis@rwest.io)}}} diff -r b38886ced111 -r d0a90a87b824 core/lib/util.org --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/core/lib/util.org Sat Dec 09 20:50:45 2023 -0500 @@ -0,0 +1,1 @@ +{{{header(util,Richard Westhaver,ellis@rwest.io)}}}