1.1--- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2+++ b/core/app/skel.org Sat Sep 07 22:34:47 2024 -0400
1.3@@ -0,0 +1,236 @@
1.4+#+title: skel
1.5+#+author: Richard Westhaver
1.6+#+setupfile: ../../../clean.theme
1.7+#+OPTIONS: num:nil
1.8+
1.9+=skel= is the primary build tool for contributors and serves a
1.10+similar role to language-agnostic build tools like [[https://www.gnu.org/software/make/][GNU Make]], but with
1.11+the features and ease-of-use of language-specific build tools like
1.12+Rust's [[https://github.com/rust-lang/cargo][Cargo]].
1.13+
1.14+* features
1.15+:PROPERTIES:
1.16+:ID: 90d78420-e6d9-4f18-8222-89c4670633b4
1.17+:END:
1.18+** configuration
1.19+:PROPERTIES:
1.20+:ID: 2658a3d1-cfa5-436e-b2b0-9cf42a6f66c6
1.21+:END:
1.22+The ~skel~ tool can be configured at runtime using the CLI flags, or
1.23+via local configuration files. The configuration files are in the
1.24+~skelfile~ format and are assigned the following locations by default:
1.25+- ~*default-user-skelrc*~ :: =$HOME/.skelrc=
1.26+- ~*default-system-skelrc*~ :: =/etc/skel/skelrc=
1.27+
1.28+Both files are optional and the user skelrc takes precedence over
1.29+system.
1.30+
1.31+Example =~/.skelrc=:
1.32+#+begin_src shell :results output
1.33+cat ~/.skelrc
1.34+#+end_src
1.35+
1.36+#+RESULTS:
1.37+#+begin_example
1.38+;;; .skelrc @ 2023-10-12.02:58:08 -*- mode: skel; -*-
1.39+:name "Richard Westhaver"
1.40+:email "richard.westhaver@gmail.com"
1.41+:user "ellis"
1.42+:version "0.1.0"
1.43+:tags ("auto")
1.44+:fmt :pretty
1.45+:vc :hg
1.46+:auto-insert t
1.47+:license :mpl2
1.48+:log-level :info
1.49+:stash ".stash"
1.50+;; :scratch ".stash/scratch"
1.51+:cache ".stash/cache"
1.52+:registry ".data/skel/registry"
1.53+:scripts ("/usr/local/share/stash/scripts" "~/stash/scripts")
1.54+#+end_example
1.55+
1.56+** projects
1.57+:PROPERTIES:
1.58+:ID: 359441da-1b61-4d73-8563-605ea7262b58
1.59+:END:
1.60+Projects are the highest-level objects int the ~skel~ system. A project
1.61+consists of a list of slots which are populated automatically or by
1.62+the user. Once a project is initialized the slots can be accessed and
1.63+a set of high-level operations can be performed.
1.64+
1.65+The easiest way to initialize a project is with a ~skelfile~. These
1.66+files are parsed as a simplified Lisp dialect and generate
1.67+~sk-project~ objects based on their contents.
1.68+
1.69+The simplest project looks like this:
1.70+
1.71+#+begin_src skel :noeval t
1.72+:name hello-world
1.73+#+end_src
1.74+
1.75+Don't worry, this is still lisp - the parentheses are implied. All we
1.76+actually need is a name to generate an object, and we can fill in the
1.77+blanks later as the project develops.
1.78+
1.79+Here is a more verbose example, still with only metadata:
1.80+
1.81+#+begin_src skel :noeval t
1.82+;;; skelfile --- core skelfile -*- mode: skel; -*-
1.83+:name "core"
1.84+:author "Richard Westhaver <ellis@rwest.io>"
1.85+:version "0.1.0"
1.86+:license "MPL"
1.87+:description "The Compiler Company Core"
1.88+:vc :hg
1.89+:tags ("core")
1.90+:docs ((:org "readme") (:org "install") (:org "tests") (:org "todo"))
1.91+:import ("lisp/lisp.sk" "rust/rust.sk")
1.92+#+end_src
1.93+
1.94+Another example with rules and components:
1.95+
1.96+#+begin_src skel :noeval t
1.97+;;; skelfile @ 2023-10-08.02:37:25 -*- mode: skel; -*-
1.98+:name skel
1.99+:author "ellis"
1.100+:version "0.1.0"
1.101+:description "a hacker's project compiler"
1.102+:license "MPL"
1.103+:vc :hg
1.104+:tags ("lisp")
1.105+:rules ((build () (print (asdf:make :skel/cli)))
1.106+ (clean () #$rm -rf */*.fasl$#))
1.107+:docs ((:org "readme"))
1.108+:components
1.109+((:elisp "sk"))
1.110+:stash "~/dev/comp/stash"
1.111+#+end_src
1.112+** version control
1.113+:PROPERTIES:
1.114+:ID: c15f58b5-d55e-425b-acf5-7001ef4591e4
1.115+:END:
1.116+=skel= integrates closely with our Version Control System which
1.117+is built on [[https://www.mercurial-scm.org/][Mercurial]], but we also interact with and host many [[https://git-scm.com/][Git]]
1.118+repositories.
1.119+
1.120+The =skel= tool helps us abstract away the differences between git/hg
1.121+and make maximum use of their utility. When you run a =skel vc=
1.122+command the currently active ~sk-project~ and configuration are used
1.123+to determine the appropriate VC backend to call. New backends can of
1.124+course be added as extensions.
1.125+
1.126+** TODO compilers
1.127+:PROPERTIES:
1.128+:ID: 5ec3ae9d-8846-4374-a42b-5701606ad119
1.129+:END:
1.130+- State "TODO" from [2023-12-09 Sat 19:28]
1.131+One of the most unusual features of =skel= is the compiler set. With
1.132+the =skel= CLI you can compile the following types of files for your
1.133+project directly from a ~skelfile~:
1.134+- Makefile (.mk)
1.135+- Lisp system defs (.asd)
1.136+- Cargo.toml
1.137+- Containerfile
1.138+- .hgignore/.gitignore
1.139+
1.140+We treat skelfiles as the mother of all build formats and consolidate
1.141+different formats into our own project DSL. This helps reduce
1.142+complexity while increasing capability and portability.
1.143+
1.144+Project compilation occurs on demand with the =sk compile= command.
1.145+
1.146+** TODO virtualization
1.147+:PROPERTIES:
1.148+:ID: fea87861-30c2-4739-b964-1ecb87d3ddff
1.149+:END:
1.150+- State "TODO" from [2023-12-09 Sat 18:55]
1.151+
1.152+ =skel= offers a mechanism for generating and running Virtual
1.153+ Machines (VMs) and Containers. Under the hood we depend on [[https://podman.io/][podman]]
1.154+ for our container runtime as well as [[https://www.qemu.org/][QEMU]] for some functionality.
1.155+
1.156+** TODO emacs integration
1.157+:PROPERTIES:
1.158+:ID: 3df22a04-3f6b-4738-bd5f-3eb91977d3af
1.159+:END:
1.160+- State "TODO" from [2023-12-09 Sat 19:30]
1.161+=sk.el= is the Emacs support package for skel. It contains a
1.162+=skel-mode= for working with skelfiles and will soon contain
1.163+additional built-in integrations for =project.el=, =vc.el=, and more.
1.164+** TODO deployment
1.165+:PROPERTIES:
1.166+:ID: 7e66bdf6-304e-423e-8db4-783e7f6ccfd7
1.167+:END:
1.168+- State "TODO" from [2023-12-09 Sat 19:37]
1.169+** TODO visualization
1.170+:PROPERTIES:
1.171+:ID: efa22675-70d6-453f-b377-8e76875e5f1f
1.172+:END:
1.173+- State "TODO" from [2023-12-09 Sat 19:37]
1.174+* help
1.175+:PROPERTIES:
1.176+:ID: f8e9fab4-67dc-4e7f-b172-7e0fc21047ad
1.177+:END:
1.178+#+begin_src shell :results pp replace :exports both
1.179+skel -h
1.180+#+end_src
1.181+
1.182+#+RESULTS:
1.183+#+begin_example
1.184+skel v0.1.1:97dd03beda03+ --- A hacker's project compiler.
1.185+
1.186+ usage: skel [global] <command> [<arg>]
1.187+
1.188+options:
1.189+ -h/--help* : print this message
1.190+ -v/--version* : print version
1.191+ -l/--level* : set log level (warn,info,debug,trace)
1.192+ -c/--config* : set a custom skel user config
1.193+ -i/--input* : input source
1.194+ -o/--output* : output target
1.195+
1.196+commands:
1.197+ init : initialize a skelfile in the current directory
1.198+ -n/--name*
1.199+ -n/--name
1.200+ -d/--description*
1.201+ -p/--project name
1.202+ -k/--kind*
1.203+ -s/--string*
1.204+ new : make a new skel project
1.205+ -n/--name : project name
1.206+ describe : describe a skelfile
1.207+ show : show project slots
1.208+ -f/--file : path to skelfile
1.209+ -u/--user : print user configuration
1.210+ -s/--system : print system configuration
1.211+ vc : version control
1.212+ -r/--root : repository path
1.213+ id : print the project id
1.214+ inspect : inspect the project skelfile
1.215+ -f/--file : path to skelfile
1.216+ make : build project targets
1.217+ -t/--target : target to build
1.218+ run : run a script or command
1.219+ compile : compile source code
1.220+ build : build programs and libraries
1.221+ dist : distribute build artifacts
1.222+ install : install stuff
1.223+ pack : pack stuff
1.224+ unpack : unpack stuff
1.225+ bundle : bundle source code
1.226+ unbundle : unbundle source code
1.227+ clean : clean up the project
1.228+ test : run tests
1.229+ bench : run benchmark
1.230+ status : print the vc status
1.231+ push : push the current project upstream
1.232+ pull : pull the current project from remote
1.233+ clone : clone a remote project
1.234+ commit : commit changes to the project vc
1.235+ edit : edit a project file in emacs.
1.236+ shell : open the sk-shell interpreter
1.237+
1.238+#+end_example
1.239+
