2 #+author: Richard Westhaver
3 #+setupfile: ../../../clean.theme
5 #+INFOJS_OPT: toc:nil view:content
7 The
=skel= CLI is the primary build tool for contributors and serves a
8 similar role to language-agnostic build tools like
[[https://www.gnu.org/software/make/][GNU Make]], but with
9 the features and ease-of-use of language-specific build tools like
10 Rust's
[[https://github.com/rust-lang/cargo][Cargo]].
14 The
~skel~ tool can be configured at runtime using the CLI flags, or
15 via local configuration files. The configuration files are in the
16 ~skelfile~ format and are assigned the following locations by default:
17 - ~*default-user-skelrc*~ :: =$HOME/.skelrc= 18 - ~*default-system-skelrc*~ :: =/etc/skel/skelrc= 20 Both files are optional and the user skelrc takes precedence over
24 #+begin_src shell :results output 30 ;;; .skelrc @ 2023-10-12.02:58:08 -*- mode: skel; -*-
31 :name "Richard Westhaver"
32 :email "richard.westhaver@gmail.com"
42 ;; :scratch ".stash/scratch"
44 :registry ".data/skel/registry"
45 :scripts ("/usr/local/share/stash/scripts" "~/stash/scripts")
49 Projects are the highest-level objects int the
~skel~ system. A project
50 consists of a list of slots which are populated automatically or by
51 the user. Once a project is initialized the slots can be accessed and
52 a set of high-level operations can be performed.
54 The easiest way to initialize a project is with a
~skelfile~. These
55 files are parsed as a simplified Lisp dialect and generate
56 ~sk-project~ objects based on their contents.
58 The simplest project looks like this:
60 #+begin_src skel :noeval t 64 Don't worry, this is still lisp - the parentheses are implied. All we
65 actually need is a name to generate an object, and we can fill in the
66 blanks later as the project develops.
68 Here is a more verbose example, still with only metadata:
70 #+begin_src skel :noeval t 71 ;;; skelfile --- core skelfile -*- mode: skel; -*-
73 :author "Richard Westhaver <ellis@rwest.io>"
76 :description "The Compiler Company Core"
79 :docs ((:org "readme") (:org "install") (:org "tests") (:org "todo"))
80 :import ("lisp/lisp.sk" "rust/rust.sk")
83 Another example with rules and components:
85 #+begin_src skel :noeval t 86 ;;; skelfile @ 2023-10-08.02:37:25 -*- mode: skel; -*-
90 :description "a hacker's project compiler"
94 :rules ((build () (print (asdf:make :skel/cli)))
95 (clean () #$rm -rf */*.fasl$#))
96 :docs ((:org "readme"))
99 :stash "~/dev/comp/stash"
102 =skel= integrates closely with our Version Control System (VCS) which
103 is built on
[[https://www.mercurial-scm.org/][Mercurial]], but we also interact with and host many
[[https://git-scm.com/][Git]] 106 The
=skel= tool helps us abstract away the differences between git/hg
107 and make maximum use of their utility. When you run a
=skel vc= 108 command the currently active
~sk-project~ and configuration are used
109 to determine the appropriate VC backend to call. New backends can of
110 course be added as extensions.
113 - State "TODO" from [2023-12-09 Sat 19:28]
114 One of the most unusual features of
=skel= is the compiler set. With
115 the
=skel= CLI you can compile the following types of files for your
116 project directly from a
~skelfile~:
118 - Lisp system defs (.asd)
121 - .hgignore/.gitignore
123 We treat skelfiles as the mother of all build formats and consolidate
124 different formats into our own project DSL. This helps reduce
125 complexity while increasing capability and portability.
127 Project compilation occurs on demand with the
=sk compile= command.
129 ** TODO virtualization 130 - State "TODO" from [2023-12-09 Sat 18:55]
132 =skel= offers a mechanism for generating and running Virtual
133 Machines (VMs) and Containers. Under the hood we depend on
[[https://podman.io/][podman]] 134 for our container runtime as well as
[[https://www.qemu.org/][QEMU]] for some
137 ** TODO emacs integration 138 - State "TODO" from [2023-12-09 Sat 19:30]
139 =sk.el= is the Emacs support package for skel. It contains a
140 =skel-mode= for working with skelfiles and will soon contain
141 additional built-in integrations for
=project.el=,
=vc.el=, and more.
143 - State "TODO" from [2023-12-09 Sat 19:37]
144 ** TODO visualization 145 - State "TODO" from [2023-12-09 Sat 19:37]
147 #+begin_src shell :results pp replace :exports both 153 skel v0.1.1 --- A hacker's project compiler.
155 usage: skel [global] <command> [<arg>]
158 -h/--help* : print this message
159 -v/--version* : print version
160 -l/--level* : set log level (warn,info,debug,trace)
161 -c/--config* : set a custom skel user config
162 -i/--input* : input source
163 -o/--output* : output target
166 init : initialize a skelfile in the current directory
167 -n/--name : project name
168 new : make a new skel project
169 -n/--name : project name
170 describe : describe a skelfile
171 show : show project slots
172 -f/--file : path to skelfile
173 -u/--user : print user configuration
174 -s/--system : print system configuration
176 -r/--root : repository path
177 id : print the project id
178 rev : print the current vc revision id
179 inspect : inspect the project skelfile
180 -f/--file : path to skelfile
181 make : build project targets
182 -t/--target : target to build
183 run : run a script or command
184 status : print the vc status
185 push : push the current project upstream
186 pull : pull the current project from remote
187 clone : clone a remote project
188 commit : commit changes to the project vc
189 edit : edit a project file in emacs.
190 shell : open the sk-shell interpreter