2 #+author: Richard Westhaver
3 #+setupfile: ../../../clean.theme
6 =skel= is the primary build tool for contributors and serves a
7 similar role to language-agnostic build tools like
[[https://www.gnu.org/software/make/][GNU Make]], but with
8 the features and ease-of-use of language-specific build tools like
9 Rust's
[[https://github.com/rust-lang/cargo][Cargo]].
13 :ID: 90d78420-e6d9-4f18-8222-89c4670633b4 17 :ID: 2658a3d1-cfa5-436e-b2b0-9cf42a6f66c6 19 The
~skel~ tool can be configured at runtime using the CLI flags, or
20 via local configuration files. The configuration files are in the
21 ~skelfile~ format and are assigned the following locations by default:
22 - ~*default-user-skelrc*~ :: =$HOME/.skelrc= 23 - ~*default-system-skelrc*~ :: =/etc/skel/skelrc= 25 Both files are optional and the user skelrc takes precedence over
29 #+begin_src shell :results output 35 ;;; .skelrc @ 2023-10-12.02:58:08 -*- mode: skel; -*-
36 :name "Richard Westhaver"
37 :email "richard.westhaver@gmail.com"
47 ;; :scratch ".stash/scratch"
49 :registry ".data/skel/registry"
50 :scripts ("/usr/local/share/stash/scripts" "~/stash/scripts")
55 :ID: 359441da-1b61-4d73-8563-605ea7262b58 57 Projects are the highest-level objects int the
~skel~ system. A project
58 consists of a list of slots which are populated automatically or by
59 the user. Once a project is initialized the slots can be accessed and
60 a set of high-level operations can be performed.
62 The easiest way to initialize a project is with a
~skelfile~. These
63 files are parsed as a simplified Lisp dialect and generate
64 ~sk-project~ objects based on their contents.
66 The simplest project looks like this:
68 #+begin_src skel :noeval t 72 Don't worry, this is still lisp - the parentheses are implied. All we
73 actually need is a name to generate an object, and we can fill in the
74 blanks later as the project develops.
76 Here is a more verbose example, still with only metadata:
78 #+begin_src skel :noeval t 79 ;;; skelfile --- core skelfile -*- mode: skel; -*-
81 :author "Richard Westhaver <ellis@rwest.io>"
84 :description "The Compiler Company Core"
87 :docs ((:org "readme") (:org "install") (:org "tests") (:org "todo"))
88 :import ("lisp/lisp.sk" "rust/rust.sk")
91 Another example with rules and components:
93 #+begin_src skel :noeval t 94 ;;; skelfile @ 2023-10-08.02:37:25 -*- mode: skel; -*-
98 :description "a hacker's project compiler"
102 :rules ((build () (print (asdf:make :skel/cli)))
103 (clean () #$rm -rf */*.fasl$#))
104 :docs ((:org "readme"))
107 :stash "~/dev/comp/stash"
111 :ID: c15f58b5-d55e-425b-acf5-7001ef4591e4 113 =skel= integrates closely with our Version Control System which
114 is built on
[[https://www.mercurial-scm.org/][Mercurial]], but we also interact with and host many
[[https://git-scm.com/][Git]] 117 The
=skel= tool helps us abstract away the differences between git/hg
118 and make maximum use of their utility. When you run a
=skel vc= 119 command the currently active
~sk-project~ and configuration are used
120 to determine the appropriate VC backend to call. New backends can of
121 course be added as extensions.
125 :ID: 5ec3ae9d-8846-4374-a42b-5701606ad119 127 - State "TODO" from [2023-12-09 Sat 19:28]
128 One of the most unusual features of
=skel= is the compiler set. With
129 the
=skel= CLI you can compile the following types of files for your
130 project directly from a
~skelfile~:
132 - Lisp system defs (.asd)
135 - .hgignore/.gitignore
137 We treat skelfiles as the mother of all build formats and consolidate
138 different formats into our own project DSL. This helps reduce
139 complexity while increasing capability and portability.
141 Project compilation occurs on demand with the
=sk compile= command.
143 ** TODO virtualization 145 :ID: fea87861-30c2-4739-b964-1ecb87d3ddff 147 - State "TODO" from [2023-12-09 Sat 18:55]
149 =skel= offers a mechanism for generating and running Virtual
150 Machines (VMs) and Containers. Under the hood we depend on
[[https://podman.io/][podman]] 151 for our container runtime as well as
[[https://www.qemu.org/][QEMU]] for some functionality.
153 ** TODO emacs integration 155 :ID: 3df22a04-3f6b-4738-bd5f-3eb91977d3af 157 - State "TODO" from [2023-12-09 Sat 19:30]
158 =sk.el= is the Emacs support package for skel. It contains a
159 =skel-mode= for working with skelfiles and will soon contain
160 additional built-in integrations for
=project.el=,
=vc.el=, and more.
163 :ID: 7e66bdf6-304e-423e-8db4-783e7f6ccfd7 165 - State "TODO" from [2023-12-09 Sat 19:37]
166 ** TODO visualization 168 :ID: efa22675-70d6-453f-b377-8e76875e5f1f 170 - State "TODO" from [2023-12-09 Sat 19:37]
173 :ID: f8e9fab4-67dc-4e7f-b172-7e0fc21047ad 175 #+begin_src shell :results pp replace :exports both 181 skel v0.1.1:97dd03beda03+ --- A hacker's project compiler.
183 usage: skel [global] <command> [<arg>]
186 -h/--help* : print this message
187 -v/--version* : print version
188 -l/--level* : set log level (warn,info,debug,trace)
189 -c/--config* : set a custom skel user config
190 -i/--input* : input source
191 -o/--output* : output target
194 init : initialize a skelfile in the current directory
201 new : make a new skel project
202 -n/--name : project name
203 describe : describe a skelfile
204 show : show project slots
205 -f/--file : path to skelfile
206 -u/--user : print user configuration
207 -s/--system : print system configuration
209 -r/--root : repository path
210 id : print the project id
211 inspect : inspect the project skelfile
212 -f/--file : path to skelfile
213 make : build project targets
214 -t/--target : target to build
215 run : run a script or command
216 compile : compile source code
217 build : build programs and libraries
218 dist : distribute build artifacts
219 install : install stuff
221 unpack : unpack stuff
222 bundle : bundle source code
223 unbundle : unbundle source code
224 clean : clean up the project
226 bench : run benchmark
227 status : print the vc status
228 push : push the current project upstream
229 pull : pull the current project from remote
230 clone : clone a remote project
231 commit : commit changes to the project vc
232 edit : edit a project file in emacs.
233 shell : open the sk-shell interpreter