1.1--- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2+++ b/core/bin/skel.org Sun Jun 02 00:42:41 2024 -0400
1.3@@ -0,0 +1,192 @@
1.4+#+title: skel
1.5+#+author: Richard Westhaver
1.6+
1.7+The =skel= CLI is the primary build tool for contributors and serves a
1.8+similar role to language-agnostic build tools like [[https://www.gnu.org/software/make/][GNU Make]], but with
1.9+the features and ease-of-use of language-specific build tools like
1.10+Rust's [[https://github.com/rust-lang/cargo][Cargo]].
1.11+
1.12+* features
1.13+** configuration
1.14+The ~skel~ tool can be configured at runtime using the CLI flags, or
1.15+via local configuration files. The configuration files are in the
1.16+~skelfile~ format and are assigned the following locations by default:
1.17+- ~*default-user-skelrc*~ :: =$HOME/.skelrc=
1.18+- ~*default-system-skelrc*~ :: =/etc/skel/skelrc=
1.19+
1.20+Both files are optional and the user skelrc takes precedence over
1.21+system.
1.22+
1.23+Example =~/.skelrc=:
1.24+#+begin_src shell :results output
1.25+cat ~/.skelrc
1.26+#+end_src
1.27+
1.28+#+RESULTS:
1.29+#+begin_example
1.30+;;; .skelrc @ 2023-10-12.02:58:08 -*- mode: skel; -*-
1.31+:name "Richard Westhaver <ellis@rwest.io>"
1.32+:user "ellis"
1.33+:version "0.1.0"
1.34+:tags ("auto")
1.35+:fmt :pretty
1.36+:vc :hg
1.37+:auto-insert t
1.38+:license :mpl2
1.39+:log-level :info
1.40+:stash ".stash"
1.41+;; :scratch ".stash/scratch"
1.42+:cache ".cache"
1.43+:registry ".data/skel/registry"
1.44+:scripts ("/usr/local/share/stash/scripts" "~/stash/scripts")
1.45+:alias-list
1.46+(("p" "vc push")
1.47+ ("P" "vc pull")
1.48+ ("ci" "vc commit"))
1.49+#+end_example
1.50+
1.51+** projects
1.52+Projects are the highest-level objects int the ~skel~ system. A project
1.53+consists of a list of slots which are populated automatically or by
1.54+the user. Once a project is initialized the slots can be accessed and
1.55+a set of high-level operations can be performed.
1.56+
1.57+The easiest way to initialize a project is with a ~skelfile~. These
1.58+files are parsed as a simplified Lisp dialect and generate
1.59+~sk-project~ objects based on their contents.
1.60+
1.61+The simplest project looks like this:
1.62+
1.63+#+begin_src skel :results pp replace :exports both
1.64+:name hello-world
1.65+#+end_src
1.66+
1.67+Don't worry, this is still lisp - the parentheses are implied. All we
1.68+actually need is a name to generate an object, and we can fill in the
1.69+blanks later as the project develops.
1.70+
1.71+Here is a more verbose example, still with only metadata:
1.72+
1.73+#+begin_src skel :results pp replace :exports both
1.74+;;; skelfile --- core skelfile -*- mode: skel; -*-
1.75+:name "core"
1.76+:author "Richard Westhaver <ellis@rwest.io>"
1.77+:version "0.1.0"
1.78+:license "MPL"
1.79+:description "The Compiler Company Core"
1.80+:vc :hg
1.81+:tags ("core")
1.82+:docs ((:org "readme") (:org "install") (:org "tests") (:org "todo"))
1.83+:import ("lisp/lisp.sk" "rust/rust.sk")
1.84+#+end_src
1.85+
1.86+Another example with rules and components:
1.87+
1.88+#+begin_src skel
1.89+;;; skelfile @ 2023-10-08.02:37:25 -*- mode: skel; -*-
1.90+:name skel
1.91+:author "ellis"
1.92+:version "0.1.0"
1.93+:description "a hacker's project compiler"
1.94+:license "MPL"
1.95+:vc :hg
1.96+:tags ("lisp")
1.97+:rules ((build () (print (asdf:make :skel/cli)))
1.98+ (clean () #$rm -rf */*.fasl$#))
1.99+:docs ((:org "readme"))
1.100+:components
1.101+((:elisp "sk"))
1.102+:stash "~/dev/comp/stash"
1.103+#+end_src
1.104+** version control
1.105+=skel= integrates closely with our Version Control System (VCS) which
1.106+is built on [[https://www.mercurial-scm.org/][Mercurial]], but we also interact with and host many [[https://git-scm.com/][Git]]
1.107+repositories.
1.108+
1.109+The =skel= tool helps us abstract away the differences between git/hg
1.110+and make maximum use of their utility. When you run a =skel vc=
1.111+command the currently active ~sk-project~ and configuration are used
1.112+to determine the appropriate VC backend to call. New backends can of
1.113+course be added as extensions.
1.114+
1.115+** TODO compilers
1.116+- State "TODO" from [2023-12-09 Sat 19:28]
1.117+One of the most unusual features of =skel= is the compiler set. With
1.118+the =skel= CLI you can compile the following types of files for your
1.119+project directly from a ~skelfile~:
1.120+- Makefile (.mk)
1.121+- Lisp system defs (.asd)
1.122+- Cargo.toml
1.123+- Containerfile
1.124+- .hgignore/.gitignore
1.125+
1.126+We treat skelfiles as the mother of all build formats and consolidate
1.127+different formats into our own project DSL. This helps reduce
1.128+complexity while increasing capability and portability.
1.129+
1.130+Project compilation occurs on demand with the =sk compile= command.
1.131+
1.132+** TODO virtualization
1.133+- State "TODO" from [2023-12-09 Sat 18:55]
1.134+
1.135+ =skel= offers a mechanism for generating and running Virtual
1.136+ Machines (VMs) and Containers. Under the hood we depend on [[https://podman.io/][podman]]
1.137+ for our container runtime as well as [[https://www.qemu.org/][QEMU]] for some
1.138+ functionality.
1.139+
1.140+** TODO emacs integration
1.141+- State "TODO" from [2023-12-09 Sat 19:30]
1.142+=sk.el= is the Emacs support package for skel. It contains a
1.143+=skel-mode= for working with skelfiles and will soon contain
1.144+additional built-in integrations for =project.el=, =vc.el=, and more.
1.145+** TODO deployment
1.146+- State "TODO" from [2023-12-09 Sat 19:37]
1.147+** TODO visualization
1.148+- State "TODO" from [2023-12-09 Sat 19:37]
1.149+* help
1.150+#+begin_src shell :results pp replace :exports both
1.151+skel -h
1.152+#+end_src
1.153+
1.154+#+RESULTS:
1.155+#+begin_example
1.156+skel v0.1.1 --- A hacker's project compiler.
1.157+
1.158+ usage: skel [global] <command> [<arg>]
1.159+
1.160+options:
1.161+ -h/--help* : print this message
1.162+ -v/--version* : print version
1.163+ -l/--level* : set log level (warn,info,debug,trace)
1.164+ -c/--config* : set a custom skel user config
1.165+ -i/--input* : input source
1.166+ -o/--output* : output target
1.167+
1.168+commands:
1.169+ init : initialize a skelfile in the current directory
1.170+ -n/--name : project name
1.171+ new : make a new skel project
1.172+ -n/--name : project name
1.173+ describe : describe a skelfile
1.174+ show : show project slots
1.175+ -f/--file : path to skelfile
1.176+ -u/--user : print user configuration
1.177+ -s/--system : print system configuration
1.178+ vc : version control
1.179+ -r/--root : repository path
1.180+ id : print the project id
1.181+ rev : print the current vc revision id
1.182+ inspect : inspect the project skelfile
1.183+ -f/--file : path to skelfile
1.184+ make : build project targets
1.185+ -t/--target : target to build
1.186+ run : run a script or command
1.187+ status : print the vc status
1.188+ push : push the current project upstream
1.189+ pull : pull the current project from remote
1.190+ clone : clone a remote project
1.191+ commit : commit changes to the project vc
1.192+ edit : edit a project file in emacs.
1.193+ shell : open the sk-shell interpreter
1.194+#+end_example
1.195+
