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 <ellis@rwest.io>"
41 ;; :scratch ".stash/scratch"
43 :registry ".data/skel/registry"
44 :scripts ("/usr/local/share/stash/scripts" "~/stash/scripts")
52 Projects are the highest-level objects int the
~skel~ system. A project
53 consists of a list of slots which are populated automatically or by
54 the user. Once a project is initialized the slots can be accessed and
55 a set of high-level operations can be performed.
57 The easiest way to initialize a project is with a
~skelfile~. These
58 files are parsed as a simplified Lisp dialect and generate
59 ~sk-project~ objects based on their contents.
61 The simplest project looks like this:
63 #+begin_src skel :noeval t 67 Don't worry, this is still lisp - the parentheses are implied. All we
68 actually need is a name to generate an object, and we can fill in the
69 blanks later as the project develops.
71 Here is a more verbose example, still with only metadata:
73 #+begin_src skel :noeval t 74 ;;; skelfile --- core skelfile -*- mode: skel; -*-
76 :author "Richard Westhaver <ellis@rwest.io>"
79 :description "The Compiler Company Core"
82 :docs ((:org "readme") (:org "install") (:org "tests") (:org "todo"))
83 :import ("lisp/lisp.sk" "rust/rust.sk")
86 Another example with rules and components:
88 #+begin_src skel :noeval t 89 ;;; skelfile @ 2023-10-08.02:37:25 -*- mode: skel; -*-
93 :description "a hacker's project compiler"
97 :rules ((build () (print (asdf:make :skel/cli)))
98 (clean () #$rm -rf */*.fasl$#))
99 :docs ((:org "readme"))
102 :stash "~/dev/comp/stash"
105 =skel= integrates closely with our Version Control System (VCS) which
106 is built on
[[https://www.mercurial-scm.org/][Mercurial]], but we also interact with and host many
[[https://git-scm.com/][Git]] 109 The
=skel= tool helps us abstract away the differences between git/hg
110 and make maximum use of their utility. When you run a
=skel vc= 111 command the currently active
~sk-project~ and configuration are used
112 to determine the appropriate VC backend to call. New backends can of
113 course be added as extensions.
116 - State "TODO" from [2023-12-09 Sat 19:28]
117 One of the most unusual features of
=skel= is the compiler set. With
118 the
=skel= CLI you can compile the following types of files for your
119 project directly from a
~skelfile~:
121 - Lisp system defs (.asd)
124 - .hgignore/.gitignore
126 We treat skelfiles as the mother of all build formats and consolidate
127 different formats into our own project DSL. This helps reduce
128 complexity while increasing capability and portability.
130 Project compilation occurs on demand with the
=sk compile= command.
132 ** TODO virtualization 133 - State "TODO" from [2023-12-09 Sat 18:55]
135 =skel= offers a mechanism for generating and running Virtual
136 Machines (VMs) and Containers. Under the hood we depend on
[[https://podman.io/][podman]] 137 for our container runtime as well as
[[https://www.qemu.org/][QEMU]] for some
140 ** TODO emacs integration 141 - State "TODO" from [2023-12-09 Sat 19:30]
142 =sk.el= is the Emacs support package for skel. It contains a
143 =skel-mode= for working with skelfiles and will soon contain
144 additional built-in integrations for
=project.el=,
=vc.el=, and more.
146 - State "TODO" from [2023-12-09 Sat 19:37]
147 ** TODO visualization 148 - State "TODO" from [2023-12-09 Sat 19:37]
150 #+begin_src shell :results pp replace :exports both 156 skel v0.1.1 --- A hacker's project compiler.
158 usage: skel [global] <command> [<arg>]
161 -h/--help* : print this message
162 -v/--version* : print version
163 -l/--level* : set log level (warn,info,debug,trace)
164 -c/--config* : set a custom skel user config
165 -i/--input* : input source
166 -o/--output* : output target
169 init : initialize a skelfile in the current directory
170 -n/--name : project name
171 new : make a new skel project
172 -n/--name : project name
173 describe : describe a skelfile
174 show : show project slots
175 -f/--file : path to skelfile
176 -u/--user : print user configuration
177 -s/--system : print system configuration
179 -r/--root : repository path
180 id : print the project id
181 rev : print the current vc revision id
182 inspect : inspect the project skelfile
183 -f/--file : path to skelfile
184 make : build project targets
185 -t/--target : target to build
186 run : run a script or command
187 status : print the vc status
188 push : push the current project upstream
189 pull : pull the current project from remote
190 clone : clone a remote project
191 commit : commit changes to the project vc
192 edit : edit a project file in emacs.
193 shell : open the sk-shell interpreter