changelog shortlog graph tags branches changeset files revisions annotate raw help

Mercurial > org > docs / core/lib/skel.org

changeset 45: 517e7b6fb42d
parent: bc53e27c0163
author: Richard Westhaver <ellis@rwest.io>
date: Sun, 25 Aug 2024 00:15:40 -0400
permissions: -rw-r--r--
description: meta and task work 
     1 #+title: skel
     2 #+author: Richard Westhaver
     3 #+setupfile: ../../../clean.theme
     4 =skel= is /a hacker's project compiler and build tool/. It is an
     5 extensible software library designed for managing /projects/.
     6 
     7 The [[https://compiler.company/docs/core/app/skel.html][cli]] is the main entry point for typical users. This documentation
     8 is for library developers and internal use.
     9 
    10 * Overview
    11 :PROPERTIES:
    12 :ID:       daebd915-628a-4792-8653-8a01c690a329
    13 :END:
    14 This library started as a Rust crate but was re-written in Lisp as the
    15 purpose of the library grew from managing a small collection of
    16 user-space libraries (also written in Rust) to managing large
    17 collections in many different langs.
    18 
    19 It is obvious in hindsight, that this project needs Lisp. Today,
    20 =skel= built on [[https://en.wikipedia.org/wiki/Common_Lisp_Object_System][CLOS]] with classes and methods exposing the core API.
    21 
    22 * Architecture
    23 :PROPERTIES:
    24 :ID:       4fd2d7eb-e738-4e2f-8de1-3b8f5671d488
    25 :END:
    26 The library core is built on CLOS. Most important data structures are
    27 represented with classes, slots, and methods such as the ~sk-project~
    28 class which has a slot named ~:components~ and a method specialized on
    29 it called ~load-ast~.
    30 
    31 We make use of mixins defined within the library like ~sk-meta~ as
    32 well as classes defined downstream - the ~sxp~ class for example
    33 provides a default method for AST functions (~load-ast~ ~build-ast~)
    34 and is defined in the ~std/sxp~ package.
    35 
    36 On top of the core we build our compilers or 'translators' which
    37 convert core objects to a corresponding external representation. For
    38 example the ~makefile~ and ~mk-*~ classes defined in ~skel/comp/make~
    39 can be built from a ~sk-project~ and ~sk-*~ instances. Once built, the
    40 ~sk-compile~ method can be used to actually generate the GNU Make
    41 output as a stream of bytes.
    42 
    43 The remainder of the ~skel~ system is dedicated to extensions. These
    44 are all optional. There are built-in extension called ~tools~ which
    45 run within the ~skel~ system and external extensions (~ext~) which
    46 integrate with a particular external system.
    47 
    48 The ~tools~ we provide are similar to Cargo's [[https://doc.rust-lang.org/book/ch14-05-extending-cargo.html][custom commands]], but
    49 they don't need to be a separate binary - they can be compiled into
    50 the core image. The downside is that this requires re-compiling ~skel~
    51 every time you want to add a new tool. However since this is Lisp not
    52 Rust, we can compile anywhere - including from within ~skel~
    53 itself.
    54 
    55 ~ext~ contains extensions for external systems. These modules are the
    56 'edges' of the system and provide support to programs which need to be
    57 able to access ~skel~ data at runtime. These modules always compiled
    58 separately and aren't built into the default core image.