skel
skel is the primary build tool for contributors and serves a
similar role to language-agnostic build tools like GNU Make, but with
the features and ease-of-use of language-specific build tools like
Rust's 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:
cat ~/.skelrc
;;; .skelrc @ 2023-10-12.02:58:08 -*- mode: skel; -*-
:name "Richard Westhaver"
:email "richard.westhaver@gmail.com"
:version "0.1.0"
:tags ("auto")
:fmt :pretty
:vc :hg
:auto-insert t
:license :mpl2
:log-level :info
:stash ".stash"
;; :scratch ".stash/scratch"
:cache ".stash/cache"
:registry ".data/skel/registry"
:scripts ("/usr/local/share/stash/scripts" "~/.stash/scripts")
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:
:name hello-world
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:
;;; skelfile --- core skelfile -*- mode: skel; -*- :name "core" :author "Richard Westhaver <ellis@rwest.io>" :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 ("emacs/emacs.sk")
Another example with rules and components:
;;; 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 "~/.stash"
version control
skel integrates closely with our Version Control System which
is built on Mercurial, but we also interact with and host many 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
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
TODO emacs integration
- State "TODO" from
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
TODO visualization
- State "TODO" from
example
Here is the default output when running skel in a project directory:
skel
:project 15bc-b763-ec92-1cf5
:name core
:path /home/ellis/comp/core/skelfile
:author (Richard Westhaver . ellis@rwest.io)
:version 0.1.0
:tags (core lisp rust emacs c)
:description The Compiler Company Core
:license MPL
:ast nil
:id 1566328410216733941
:vc #<hg-repo (default . https://vc.compiler.company/core)
(cb . ssh://git@codeberg.org/c-c/core)
(gh . ssh://git@github.com/richardwesthaver/core)>
:src /home/ellis/comp/core/
:stash .stash
:store .store
:components
[ #<org-file readme> #<lisp-system prelude> #<lisp-system user>
#<lisp-system core> #<mod std> #<mod ffi> #<mod lib> #<mod bin> ... ]
:bind ((stash .stash))
:phases
{ (:link-pod #<rule link-pod-core>)
(:build-all #<rule build-all-core (%stash)>)
(:compile #<rule compile-bench> #<rule compile-tests> #<rule compile-core>
#<rule compile-user> #<rule compile-prelude>)
(:save #<rule save-tests> #<rule save-core> #<rule save-infra>
#<rule save-user> #<rule save-prelude> #<rule save-std>)
(:build-gui #<rule build-gui-skel>)
(:install #<rule install-core> #<rule install-skel> #<rule install-rdb>
#<rule install-swm> #<rule install-zstd-alien>
#<rule install-tree-sitter-alien>)
(:build #<rule build-core (%stash)> #<rule build-packy> #<rule build-gen>
#<rule build-homer> #<rule build-organ> #<rule build-vc> #<rule build-skc>
#<rule build-skel> #<rule build-rdb> #<rule build-swm>
#<rule build-zstd-alien> #<rule build-tree-sitter-alien>)
(:run #<rule run-swank>) ... }
:include
[ #<project core/emacs :components 0 :rules 2> ]
You can also view specific slots which will print all values without an ellipses:
skel :rules
:rules
[ #<rule all (%stash psl.dat rgb.txt build-zstd-alien build-tree-sitter-alien
build-core)>
#<rule upstream> #<rule clean> #<rule update-readme> #<rule run-swank>
#<rule build-tree-sitter-alien> #<rule install-tree-sitter-alien>
#<rule build-zstd-alien> #<rule build-tree-sitter-alien>
#<rule install-zstd-alien> #<rule install-tree-sitter-alien>
#<rule psl.dat (%stash)> #<rule rgb.txt (%stash)>
#<rule x11.lisp (rgb.txt)> #<rule parquet.thrift (%stash)>
#<rule parquet.json (%stash)> #<rule freedesktop.org.xml (%stash)>
#<rule parquet-test-data (%stash)> #<rule %stash> #<rule ssl-certs>
#<rule ssl-client-certs> #<rule build-swm> #<rule build-zstd-alien>
#<rule build-tree-sitter-alien> #<rule install-swm>
#<rule install-zstd-alien> #<rule install-tree-sitter-alien>
#<rule build-rdb> #<rule build-swm> #<rule build-zstd-alien>
#<rule build-tree-sitter-alien> #<rule install-rdb> #<rule install-swm>
#<rule install-zstd-alien> #<rule install-tree-sitter-alien>
#<rule build-skel> #<rule build-rdb> #<rule build-swm>
#<rule build-zstd-alien> #<rule build-tree-sitter-alien>
#<rule build-gui-skel> #<rule install-skel> #<rule install-rdb>
#<rule install-swm> #<rule install-zstd-alien>
#<rule install-tree-sitter-alien> #<rule build-skc> #<rule build-skel>
#<rule build-rdb> #<rule build-swm> #<rule build-zstd-alien>
#<rule build-tree-sitter-alien> #<rule build-vc> #<rule build-skc>
#<rule build-skel> #<rule build-rdb> #<rule build-swm>
#<rule build-zstd-alien> #<rule build-tree-sitter-alien>
#<rule build-organ> #<rule build-vc> #<rule build-skc> #<rule build-skel>
#<rule build-rdb> #<rule build-swm> #<rule build-zstd-alien>
#<rule build-tree-sitter-alien> #<rule build-homer> #<rule build-organ>
#<rule build-vc> #<rule build-skc> #<rule build-skel> #<rule build-rdb>
#<rule build-swm> #<rule build-zstd-alien> #<rule build-tree-sitter-alien>
#<rule build-gen> #<rule build-homer> #<rule build-organ> #<rule build-vc>
#<rule build-skc> #<rule build-skel> #<rule build-rdb> #<rule build-swm>
#<rule build-zstd-alien> #<rule build-tree-sitter-alien>
#<rule build-packy> #<rule build-gen> #<rule build-homer>
#<rule build-organ> #<rule build-vc> #<rule build-skc> #<rule build-skel>
#<rule build-rdb> #<rule build-swm> #<rule build-zstd-alien>
#<rule build-tree-sitter-alien> #<rule save-std> #<rule save-prelude>
#<rule save-std> #<rule compile-prelude> #<rule save-user>
#<rule save-prelude> #<rule save-std> #<rule compile-user>
#<rule compile-prelude> #<rule save-infra> #<rule save-user>
#<rule save-prelude> #<rule save-std> #<rule build-core (%stash)>
#<rule build-packy> #<rule build-gen> #<rule build-homer>
#<rule build-organ> #<rule build-vc> #<rule build-skc> #<rule build-skel>
#<rule build-rdb> #<rule build-swm> #<rule build-zstd-alien>
#<rule build-tree-sitter-alien> #<rule build-all-core (%stash)>
#<rule save-core> #<rule save-infra> #<rule save-user> #<rule save-prelude>
#<rule save-std> #<rule compile-core> #<rule compile-user>
#<rule compile-prelude> #<rule install-core> #<rule install-skel>
#<rule install-rdb> #<rule install-swm> #<rule install-zstd-alien>
#<rule install-tree-sitter-alien> #<rule link-pod-core> #<rule save-tests>
#<rule save-core> #<rule save-infra> #<rule save-user> #<rule save-prelude>
#<rule save-std> #<rule compile-tests> #<rule compile-core>
#<rule compile-user> #<rule compile-prelude> #<rule compile-bench>
#<rule compile-tests> #<rule compile-core> #<rule compile-user>
#<rule compile-prelude>
#<rule fasls (compile-core compile-bench compile-user compile-prelude)>
#<rule install (install-core)> #<rule syms.sxp> #<rule dist>
#<rule dist-source> #<rule dist-core (clean %stash build-core)>
#<rule deploy (all dist)> ]
help
skel -h
skel v0.1.1:2c9483d1edd0+ --- The hackable devtool.
options:
-h/--help print help
:doc Print help and exit.
-v/--version print version
:doc Print version and exit.
-a/--ast save the intermediate skel AST
:doc Set the *KEEP-AST* variable.
-l/--level set log level (warn,info,debug,trace)
:doc Set the *LOG-LEVEL* for this CLI session.
-c/--config set a custom skel user config
-i/--interactive enter the lisp image after running commands
commands:
init initialize a skelfile in the current directory
-n/--name project name
id print the current project id
inspect inspect the project skelfile
-f/--file path to skelfile
new make a new skel project
-n/--name project name
describe describe a skelfile
edit edit a project file in emacs.
show* show skel objects slots
-f/--file path to skelfile
list list skel objects
make build project targets
search search the current project
:doc Search the current project and return a date-frame of results.
run run a script or command
compile compile source code
build build programs and libraries
update update components
save save a file
dist distribute build artifacts
install install stuff
pack pack stuff
unpack unpack stuff
bundle bundle source code
unbundle unbundle source code
clean clean up the project
test run tests
bench run benchmark
shell open the sk-shell interpreter
db interact with the skel database
net communicate with skel clients and servers
vc version control
pk packages
kr cryptography