skel

skel is a hacker's project compiler and build tool. It is an extensible software library designed for managing projects.

The cli is the main entry point for typical users. This documentation is for library developers and internal use.

Architecture

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 in other packages - the ast class for example provides a default method for AST functions (load-ast build-ast) and is defined in the obj/ast package.

In addition to the core objects we provide a set of sk-component definitions 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.

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 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.

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.

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"
:cache "/opt/stash/cache/skel"
:data "/opt/stash/data/skel"
: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 [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 podman for our container runtime as well as 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]

CLI

help

skel -h

skel v0.1.1:8cf017006940+ --- 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
  status                  show the current project status
  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