1 {{{header(skel,Richard Westhaver,ellis@rwest.io)}}} 3 The
=skel= CLI is the primary build tool for contributors and serves a
4 similar role to language-agnostic build tools like
[[https://www.gnu.org/software/make/][GNU Make]], but with
5 the features and ease-of-use of language-specific build tools like
6 Rust's
[[https://github.com/rust-lang/cargo][Cargo]].
10 The
~skel~ tool can be configured at runtime using the CLI flags, or
11 via local configuration files. The configuration files are in the
12 ~skelfile~ format and are assigned the following locations by default:
13 - ~*default-user-skelrc*~ :: =$HOME/.skelrc= 14 - ~*default-system-skelrc*~ :: =/etc/skel/skelrc= 16 Both files are optional and the user skelrc takes precedence over
20 #+begin_src skel :results pp replace :exports both 21 ;;; .skelrc @ 2023-10-12.02:58:08 -*- mode: skel; -*-
22 :author "Richard Westhaver <ellis@rwest.io>"
41 Projects are the main top-level object users interact with. A project
42 consists of a list of slots which are populated automatically or by
43 the user. Once a project is initialized the slots can be accessed and
44 a set of high-level operations can be performed.
46 The easiest way to initialize a project is with a
~skelfile~. These
47 files are parsed as a simplified Lisp dialect and generate
48 ~sk-project~ objects based on their contents.
50 The simplest project looks like this:
52 #+begin_src skel :results pp replace :exports both 56 Don't worry, this is still lisp - the parentheses are implied. All we
57 actually need is a name to generate an object, and we can fill in the
58 blanks later as the project develops.
60 Here is a more verbose example, still with only metadata:
62 #+begin_src skel :results pp replace :exports both 63 ;;; skelfile --- core skelfile -*- mode: skel; -*-
65 :author "Richard Westhaver <ellis@rwest.io>"
68 :description "The Compiler Company Core"
71 :docs ((:org "readme") (:org "install") (:org "tests") (:org "todo"))
72 :imports ("lisp/lisp.sk" "rust/rust.sk")
76 =skel= integrates closely with our Version Control System (VCS) which
77 is built on
[[https://www.mercurial-scm.org/][Mercurial]], but we also interact with and host many
[[https://git-scm.com/][Git]] 80 The
=skel= tool helps us abstract away the differences between git/hg
81 and make maximum use of their utility. When you run a
=skel vc= 82 command the currently active
~sk-project~ and configuration are used
83 to determine the appropriate VC backend to call. New backends can of
84 course be added as extensions.
87 - State "TODO" from [2023-12-09 Sat 19:28]
88 One of the most unusual features of
=skel= is the compiler set. With
89 the
=skel= CLI you can compile the following types of files for your
90 project directly from a
~skelfile~:
92 - Lisp system defs (.asd)
95 - .hgignore/.gitignore
97 We treat skelfiles as the mother of all build formats and consolidate
98 different formats into our own project DSL. This helps reduce
99 complexity while increasing capability and portability.
101 Project compilation occurs on demand with the
=sk compile= command.
103 ** TODO virtualization 104 - State "TODO" from [2023-12-09 Sat 18:55]
106 =skel= offers a mechanism for generating and running Virtual
107 Machines (VMs) and Containers. Under the hood we depend on
[[https://podman.io/][podman]] 108 for our container runtime as well as
[[https://www.qemu.org/][QEMU]] for some
111 ** TODO emacs integration 112 - State "TODO" from [2023-12-09 Sat 19:30]
113 =sk.el= is the Emacs support package for skel. It contains a
114 =skel-mode= for working with skelfiles and will soon contain
115 additional built-in integrations for
=project.el=,
=vc.el=, and more.
117 - State "TODO" from [2023-12-09 Sat 19:37]
118 ** TODO visualization 119 - State "TODO" from [2023-12-09 Sat 19:37]
121 #+begin_src shell :results pp replace :exports both 128 usage: skel [global] <command> [<arg>]
130 A hacker's project compiler and build tool.
132 -h/--help* : print this message
133 -v/--version* : print version
134 -d/--debug* : set log level (debug,info,trace,warn)
135 -c/--config* : set a custom skel user config
136 -i/--input : input source
137 -o/--output : output target
139 init : initialize a skelfile in the current directory
140 -n/--name : project name
142 show : describe the project skelfile
143 -f/--file : path to skelfile
145 inspect : inspect the project skelfile
146 -f/--file : path to skelfile
148 make : build project targets
149 -t/--target : target to build
151 run : run a script or command
153 push : push the current project upstream
155 pull : pull the current project from remote
157 clone : clone a remote project
159 commit : commit changes to the project vc
161 edit : edit a project file
163 shell : open the sk-shell interpreter