Mercurial > org > notes / skel-readme.org

 * Mock Skel Readme
 :PROPERTIES:
 :ID:       a072a011-0808-490b-b4ee-c665f68e4033
 :END:
 ** Overview 
 :PROPERTIES:
 :ID:       2ab70bb9-4f1e-4ba2-ad72-b2a32dacbd5b
 :END:
 + status :: WIP
 + forge :: [[https://lab.rwest.io/ellis/skel][Heptapod]]
 + mirror :: [[https://github.com/richardwesthaver/skel][Github]]
 
 This system provides functions and macros for building and deploying
 project skeletons. /This is not a general purpose templating
 system/. It is specifically for my software stack.
 
 *** Goals
 :PROPERTIES:
 :ID:       7881a92f-7406-4862-bf89-39970731f37d
 :END:
 - vaporize boilerplate code and docs
 - integrate reasonably well with my tools (Emacs/etc)
 - object-oriented project management
 *** Resources
 :PROPERTIES:
 :ID:       d0dd3e94-8c9e-4eac-847e-33a039beadbe
 :END:
 - [[https://www.gnu.org/software/emacs/manual/html_node/autotype/Skeleton-Language.html][skeleton-lanaguage (emacs)]]
 - [[https://github.com/emacs-mirror/emacs/tree/master/lisp/cedet/ede][cedet/ede (emacs)]]
 - [[https://www.gnu.org/software/make/manual/make.html][GNU make]]
 - [[https://docs.factorcode.org/content/article-vocabularies.html][Factor (forth) definitions]]
 ** Quickstart
 :PROPERTIES:
 :ID:       183bbf4c-bb3c-44f6-a4c1-49c548e0eab2
 :END:
 Make sure you have sbcl installed:
 #+begin_src shell :results pp :eval never
 sbcl --version
 #+end_src
 
 #+RESULTS:
 : SBCL 2.3.12+main
 
 Then compile the program. This command produces a binary called =skel=
 in the project root:
 #+begin_src shell :results raw silent
 sbcl --noinform  --non-interactive --eval '(ql:quickload :app/cli/skel)' --eval '(asdf:make :app/cli/skel)'
 #+end_src
 
 Run the binary without any args, which will print a skeleton of the
 current project directory (=*skel-project*=).
 
 #+begin_src shell :results output replace :eval never
   skel -h
 #+end_src
 
 #+RESULTS:
 #+begin_example
 skel v0.1.1
   usage: skel [global] <command> [<arg>]
 
   A hacker's project compiler and build tool.
   options:
      -h/--help* :  print this message
      -v/--version* :  print version
      -d/--debug* :  set log level (debug,info,trace,warn)
      -c/--config* :  set a custom skel user config
      -i/--input  :  input source
      -o/--output  :  output target
   commands:
     init  :  initialize a skelfile in the current directory
      -n/--name  :  project name
     
     show  :  describe the project skelfile
      -f/--file  :  path to skelfile
     
     inspect  :  inspect the project skelfile
      -f/--file  :  path to skelfile
     
     make  :  build project targets
      -t/--target  :  target to build
     
     run  :  run a script or command
     
     push  :  push the current project upstream
     
     pull  :  pull the current project from remote
     
     clone  :  clone a remote project
     
     commit  :  commit changes to the project vc
     
     edit  :  edit a project file
     
     shell  :  open the sk-shell interpreter
     
 #+end_example
 
 Here's skel's skelfile:
 
 #+begin_src shell :results output replace :wrap src skel :exports results
 cat skel.sk
 #+end_src
 
 #+RESULTS:
 #+begin_src skel
 ;;; skelfile @ 2023-10-08.02:37:25 -*- mode: skel; -*-
 :name skel
 :author "ellis"
 :version "0.1.0"
 :description "a hacker's project compiler"
 :license "MPL"
 :vc :hg
 :tags ("lisp")
 :rules ((build () (print (asdf:make :skel/cli)))
         (clean () #$rm -rf */*.fasl$#))
 :documents ((:org "readme"))
 :components 
 ((:elisp "sk")
  (:lisp-system 
   "skel"
   :version "0.1.0"
   :maintainer "ellis <ellis@rwest.io>"
   :bug-tracker "https://lab.rwest.io/ellis/skel/issues"
   :class :package-inferred-system
   :defsystem-depends-on (:asdf-package-system)
   :depends-on (:uiop :asdf :sb-posix :sb-bsd-sockets :sb-concurrency :cl-ppcre :std :organ :skel/pkg)
   :in-order-to ((test-op (test-op skel/tests)))
   :perform (test-op (op c) (uiop:symbol-call '#:rt '#:do-tests))))
 :stash "~/dev/comp/stash"
 :shed "~/dev/comp/shed"
 :abbrevs nil
 :snippets 
 ((autogen #$sbcl --eval '(ql:quickload :app/cli/skel)' --eval '(asdf:make :app/cli/skel)'$#))
 #+end_src
 
 This is just a form without the top-level parentheses - you're free to
 omit them in a skelfile.
 
 *** describe
 :PROPERTIES:
 :ID:       9ae1fe7b-c373-4101-88d3-439793eb38f3
 :END:
 The =describe= command can be used to check the currently active
 skelfile, printing any errors and the parsed object.
 
 #+begin_src shell :results output replace :eval never
   skel show
 #+end_src
 
 #+RESULTS:
 #+begin_example
 #<SKEL:SK-PROJECT :ID 1e61-38b1-c5fe-7eac>
   [standard-object]
 
 Slots with :INSTANCE allocation:
   NAME                           = SKEL
   PATH                           = #P"/home/ellis/dev/skel/skelfile"
   AUTHOR                         = "ellis"
   VERSION                        = "0.1.0"
   TAGS                           = ("lisp")
   DESCRIPTION                    = "a hacker's project compiler"
   LICENSE                        = "MPL"
   AST                            = NIL
   ID                             = 2189093230060928684
   VC                             = :HG
   RULES                          = ((BUILD NIL (PRINT (ASDF/OPERATE:MAKE :SKEL/CLI)))..
   DOCUMENTS                      = ((:ORG "readme"))
   COMPONENTS                     = ((:ELISP "sk")..
   SCRIPTS                        = NIL
   SNIPPETS                       = ((AUTOGEN "sbcl --eval '(asdf:make :skel/cli)'"))
   STASH                          = #P"~/stash"
   SHED                           = #P"~/shed"
   ABBREVS                        = NIL
   IMPORTS                        = NIL
 #+end_example
 
 *** TODO compile
 :PROPERTIES:
 :ID:       e43b7a81-c2f9-4dc9-8a09-66259602f91b
 :END:
 Skelfiles can be compiled to produce a new project skeleton or update
 an existing one.
 
 Try compiling skel's skelfile:
 
 #+begin_src shell :results output replace :exports code
   skel compile
 #+end_src
 
 You may also compile individual components of the project structure,
 for example, to compile the rules into a makefile:
 
 #+begin_src shell :results output replace :exports code
   skel compile --rules
 #+end_src
 
 #+begin_src shell :results output :wrap src makefile :eval never
 cat makefile
 #+end_src
 
 #+RESULTS:
 #+begin_src makefile
 ### SKEL @ 2023-09-14.01:47:59 --- A hacker's project compiler -*- mode:makefile ; -*-
 LISP=sbcl --noinform --non-interactive --eval "(asdf:load-asd \"skel.asd\")" --eval "(ql:quickload :skel)"
 .PHONY: compile clean
 compile:;$(LISP) --eval "(asdf:compile-system :skel)"
 test:compile;$(LISP) --eval "(ql:quickload :skel/tests)" --eval "(in-package :skel.tests)" --eval "(compile-file \"tests.lisp\")" --eval "(load-file \"tests.lisp\")" --eval "(do-tests :skel)"
 clean:;rm -rf *.fasl
 debug:compile;$(LISP) --eval "(start-repl)"
 #+end_src
 
 ** Examples
 :PROPERTIES:
 :ID:       61959899-98ec-4ee2-a862-7544674ffc7a
 :END:
 *** Default
 :PROPERTIES:
 :ID:       b9e5324c-059d-4416-a19a-3e5ffbac554e
 :END:
 When you run =skel init= this is the basic skelfile that will be
 generated in the current directory, depending on the following
 contexts:
 - default user config
 - directory contents
 - cli args
 With no cli args or user config and an empty directory the output
 looks like this:
 #+begin_src skel
 ;;; examples @ 2023-10-09.23:38:23 -*- mode: skel; -*-
 :name "examples"
 #+end_src
 *** Imports
 :PROPERTIES:
 :ID:       c7e2d0d9-8b0e-428d-aeb5-1b1447e2a1ed
 :END:
 *** Multi
 :PROPERTIES:
 :ID:       d6b6bbff-7713-4f2c-9dc8-b8331497b5b4
 :END:
 ** Tests
 :PROPERTIES:
 :ID:       37821915-2584-4303-a929-3cf25727fa1b
 :END:
 The unit tests may also be a useful reference:
 
 #+begin_src lisp :results output replace :wrap src lisp :eval never :package :skel.tests
   (ql:quickload :skel/tests)
   (in-package :skel.tests)
   (setq *log-level* nil)
   ;; (setq *catch-test-errors* nil)
   (setq *compile-tests* t)
   (list (multiple-value-list (do-tests :skel)) (test-results *test-suite*))
 #+end_src
 
 #+RESULTS:
 #+begin_src lisp
 To load "skel/tests":
   Load 1 ASDF system:
     skel/tests
 ; Loading "skel/tests"
 ..................................................
 [package skel.vc].................................
 [package skel.virt]...............................
 [package skel.comp.asd]...........................
 [package skel.make]...............................
 [package skel.ext.asdf]...........................
 [package skel.tests].
 in suite SKEL with 6/6 tests:
 #<PASS VM-TEST788> 
 #<PASS MAKEFILE-TEST787> 
 #<PASS SKELRC-TEST786> 
 #<PASS SKELFILE-TEST785> 
 #<PASS HEADER-COMMENTS-TEST784> 
 #<PASS SANITY-TEST783> 
 No tests failed.
 #+end_src
 
 ** API
 :PROPERTIES:
 :ID:       ae46b723-6d1e-4855-9ec1-ad0eb7093960
 :END:
 - TODO :: CLOS-based core classes
 - TODO :: EIEIO-based wrapper classes
 
 #+begin_src dot :file /tmp/api.svg :exports results
   digraph { splines=true; label="CLOS API"; labelloc="t"; node [shape=record];
     sk [label="(skel :ID :AST)"]
     methods [label="(sk-compile sk-expand sk-build\nsk-run sk-init sk-new sk-save\nsk-tangle sk-weave sk-call sk-print)"]
     skmet [label="(sk-meta :NAME :PATH :VERSION :DESCRIPTION)"]
     skvcs [label="(sk-vc-meta :VC)"]
     skcmd [label="(sk-command)"]
     sktar [label="(sk-target)"]
     sksrc [label="(sk-source)"]
     skrec [label="(sk-recipe :COMMANDS)"]
     skrul [label="(sk-rule :TARGET :SOURCE :RECIPE)"]
     skdoc [label="(sk-document)"]
     skscr [label="(sk-script)"]
     skcfg [label="(sk-config)"]
     sksni [label="(sk-snippet)"]    
     skabb [label="(sk-abbrev)"]
     skpro [label="(sk-project\l:RULES\l:DOCUMENTS\l:SCRIPTS\l:SNIPPETS\l:ABBREVS)\l"]
     sk -> skmet
     skmet -> skvcs
     sk -> skcfg
     sk -> sksni
     sk -> skabb
     sk -> sktar
     sk -> skrul
     sk -> sksrc
     sk -> skcmd
     skvcs -> skpro
     skmet -> skdoc    
     skmet -> skscr    
     skrul -> skpro
     skscr -> skpro
     skdoc -> skpro
     sksni -> skpro
     skabb -> skpro
     sktar -> skrul
     sksrc -> skrul
     skrec -> skrul
     skcmd -> skrec
   }
 #+end_src
 
 #+RESULTS:
 [[file:/tmp/api.svg]]