Mercurial > org > docs / core/bin/skel.org

 #+title: skel
 #+author: Richard Westhaver
 #+setupfile: ../../../clean.theme
 #+OPTIONS: num:nil
 #+INFOJS_OPT: toc:nil view:content
 
 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
 :PROPERTIES:
 :ID:       90d78420-e6d9-4f18-8222-89c4670633b4
 :END:
 ** configuration
 :PROPERTIES:
 :ID:       2658a3d1-cfa5-436e-b2b0-9cf42a6f66c6
 :END:
 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"
 :email "richard.westhaver@gmail.com"
 :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 ".stash/cache"
 :registry ".data/skel/registry"
 :scripts ("/usr/local/share/stash/scripts" "~/stash/scripts")
 #+end_example
 
 ** projects
 :PROPERTIES:
 :ID:       359441da-1b61-4d73-8563-605ea7262b58
 :END:
 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 :noeval t
 :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 :noeval t
 ;;; 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 ("lisp/lisp.sk" "rust/rust.sk")
 #+end_src
 
 Another example with rules and components:
 
 #+begin_src skel :noeval t
 ;;; 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
 :PROPERTIES:
 :ID:       c15f58b5-d55e-425b-acf5-7001ef4591e4
 :END:
 =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
 :PROPERTIES:
 :ID:       5ec3ae9d-8846-4374-a42b-5701606ad119
 :END:
 - 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
 :PROPERTIES:
 :ID:       fea87861-30c2-4739-b964-1ecb87d3ddff
 :END:
 - 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
 :PROPERTIES:
 :ID:       3df22a04-3f6b-4738-bd5f-3eb91977d3af
 :END:
 - 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
 :PROPERTIES:
 :ID:       7e66bdf6-304e-423e-8db4-783e7f6ccfd7
 :END:
 - State "TODO"       from              [2023-12-09 Sat 19:37]
 ** TODO visualization
 :PROPERTIES:
 :ID:       efa22675-70d6-453f-b377-8e76875e5f1f
 :END:
 - State "TODO"       from              [2023-12-09 Sat 19:37]
 * help
 :PROPERTIES:
 :ID:       f8e9fab4-67dc-4e7f-b172-7e0fc21047ad
 :END:
 #+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] <command> [<arg>]
 
 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