The asd-generator Reference Manual

Table of Contents

The asd-generator Reference Manual

This is the asd-generator Reference Manual, generated automatically by Declt version 3.0 "Montgomery Scott" on Tue Dec 22 11:42:50 2020 GMT+0.

1 Introduction

asd-generator

Automatic generator for ASDF's .asd files.

This is still in alpha, but I use it to build my own projects, if it means anything. :P

This autoregenerates an .asd file with a customizable :COMPONENTS field, based on the file structure you provide.

The project must have a valid .asd file containing a single asdf:defsystem expression.

The project must have a asd-generator-data.asd file with the structure outlined below.

Installation

Currently, not available from quicklisp.

With Roswell, you can:

$ ros install phoe/asd-generator

Lisp API

write-asd

Syntax: (write-asd system-designator &key im-sure)

This writes the ASD file for a provided ASDF-loadable system.

You need to press Enter before anything happens, unless the im-sure key is set to non-nil.

regen

Syntax: (regen &key im-sure)

This calls write-asd on the current package, as stated in the *package* variable.

You need to press Enter before anything happens, unless the im-sure key is set to non-nil.

Command line API

update-asdf [-y] [-C pathname] [-f data] [[-s SYSTEM]*]

Mostly corresponds to calling regen and write-asd.

• -y : Do not confirm; equivalent to :im-sure t.
• -C pathname : Specify the system pathname. Similar to make -C path
• -s SYSTEM : Specify which asdf system definition to update. This is because the current directory could contain multiple asdf definitions. By default, it selects the first system in the dictionary order of the names. Can be specified multiple times, in which case all definitions are updated. Do not include .asd in the system name.
• -f data : Specify the asd-generator-data file relative to the system pathname, or an absolute pathname. Defaulted to asd-generator-data.asd. Similar to Makefile -f makefile.mk.
• -r : Call ql:register-local-projects.

Known bugs/TODO

Save all of your files in Emacs before running this, as it will pull files like .#file.lisp into the :COMPONENTS tree along with all others.

Example of usage:

Original asdf file:

(defsystem #:asd-generator-test
 :description "system for testing asd-generator"
 :author "Masataro Asai"
 :depends-on (#:cl-fad
              #:iterate
              #:alexandria)
 :serial t
 :components ())

asd-generator-data.asd

(("package")        ;single element list (<PATH>) is an abbreviation of (:file <PATH>)
 (:file "constants")
 (:file "constants2" :depends-on ("constants")) ; you have to specify :file when you use other features
 (:cffi-grovel-file "grovel") ; works well with asdf extensions
 ;;
 (:dir :src                             ; abbreviation of :module + :components.
       ("a")
       ("b")
       (:dir "sub" ("a"))
       
       (:rest)
       ;; Traverse the current directory recursively and expands to the list of
       ;; files that are not included by any other directives.
       ;; 
       ;; This means that the expansion is affected by the components not just
       ;; before, but also after (:rest).  Thus the files "a", "b", "sub/a", "c",
       ;; "rest", all files below "more-grovels", all files below "non-recursive",
       ;; all files below "sub2" are excluded.
       ;; 
       ;; This could be somewhat similar to the behavior of
       ;; (call-next-method).
       
       ;; (:rest :as :file)    ; You can specify the component type (:file by default).

       ("c")
       
       ;; A file rest.lisp should be included by (:file "rest")
       (:file "rest")
       
       (:dir "more-grovels"
             (:rest :as :cffi-grovel-file)) ; Specifying the component type.
    
       (:dir "non-recursive"
             ;; You can disable the recursive traversal.  Note that while the
             ;; expansion includes only the files immediately below
             ;; "non-recursive" and does not include the files in the
             ;; subdirectory "non-recursive/sub", the files below
             ;; "non-recursive/sub" are also excluded from the above (:rest)
             ;; directive. In other words, all files below "non-recursive" are
             ;; treated as if they are already included.
             (:rest :recursive nil))
         
       (:dir "sub2")                  ; directory without subcomponents imply (:rest).
       ;; (:dir "sub2" (:rest))       ; eqivalent definition
       ))

Result asdf file:

(defsystem #:asd-generator-test
 :description "system for testing asd-generator"
 :author "Masataro Asai"
 :depends-on (#:cl-fad
              #:iterate
              #:alexandria)
 :serial t
 :components ((:file "package")
              (:file "constants")
              (:file "constants2"
               :depends-on ("constants"))
              (:cffi-grovel-file "grovel")
              (:module "src"
               :components ((:file "a")
                            (:file "b")
                            (:module "sub"
                             :components ((:file "a")))
                            (:file "not-specified-anywhere/a")
                            (:file "not-specified-anywhere/b")
                            (:file "not-specified-anywhere/c")
                            (:file "c")
                            (:file "rest")
                            (:module "more-grovels"
                             :components ((:cffi-grovel-file "a")
                                          (:cffi-grovel-file "b")
                                          (:cffi-grovel-file "c")))
                            (:module "non-recursive"
                             :components ((:file "a")
                                          (:file "b")
                                          (:file "c")))
                            (:module "sub2"
                             :components ((:file "a")
                                          (:file "b")
                                          (:file "c")))))))

2 Systems

The main system appears first, followed by any subsystem dependency.

2.1 asd-generator

Author

Michał "phoe" Herda <phoe@openmailbox.org>

License

GPLv3

Description

Automatic directory scanner/generator for .asd project files.

Dependencies

• cl-fad
• iterate
• alexandria
• trivia

Source

asd-generator.asd (file)

Components

• package.lisp (file)
• asd-generator.lisp (file)

3 Files

Files are sorted by type and then listed depth-first from the systems components trees.

3.1 Lisp

3.1.1 asd-generator.asd

Location

asd-generator.asd

Systems

asd-generator (system)

3.1.2 asd-generator/package.lisp

Parent

asd-generator (system)

Location

package.lisp

Packages

asd-generator

3.1.3 asd-generator/asd-generator.lisp

Dependency

package.lisp (file)

Parent

asd-generator (system)

Location

asd-generator.lisp

Exported Definitions

• regen (function)
• write-asd (function)

Internal Definitions

• all-pathnames (function)
• backup-pathname (function)
• ensure-system (macro)
• expand (function)
• generate-asd (function)
• generate-components (function)
• get-unix-time (function)
• pprint-asd (function)
• process-rest-form (function)
• read-asd (function)
• to-string (function)

4 Packages

Packages are listed by definition order.

4.1 asd-generator

Source

package.lisp (file)

Use List

• alexandria
• trivia.level2
• iterate
• cl-fad
• common-lisp

Exported Definitions

• regen (function)
• write-asd (function)

Internal Definitions

• all-pathnames (function)
• backup-pathname (function)
• ensure-system (macro)
• expand (function)
• generate-asd (function)
• generate-components (function)
• get-unix-time (function)
• pprint-asd (function)
• process-rest-form (function)
• read-asd (function)
• to-string (function)

5 Definitions

Definitions are sorted by export status, category, package, and then by lexicographic order.

5.1 Exported definitions

5.1.1 Functions

Function: regen &key IM-SURE

Package

asd-generator

Source

asd-generator.lisp (file)

Function: write-asd SYSTEM &key IM-SURE DATA

Package

asd-generator

Source

asd-generator.lisp (file)

5.2 Internal definitions

5.2.1 Macros

Macro: ensure-system PLACE

Ensure the PLACE is a system

Package

asd-generator

Source

asd-generator.lisp (file)

5.2.2 Functions

Function: all-pathnames DIRECTORY

Package

asd-generator

Source

asd-generator.lisp (file)

Function: backup-pathname PATHNAME

Package

asd-generator

Source

asd-generator.lisp (file)

Function: expand DATA DIR

Package

asd-generator

Source

asd-generator.lisp (file)

Function: generate-asd SYSTEM &optional DATA

Package

asd-generator

Source

asd-generator.lisp (file)

Function: generate-components SYSTEM DATA

Generate a form for the :COMPONENT section of the ASDF definition of SYSTEM, from the given DATA

Package

asd-generator

Source

asd-generator.lisp (file)

Function: get-unix-time ()

Package

asd-generator

Source

asd-generator.lisp (file)

Function: pprint-asd ASDF-DEFINITION &optional *STANDARD-OUTPUT*

Package

asd-generator

Source

asd-generator.lisp (file)

Function: process-rest-form DIR PATHS &key AS RECURSIVE TYPE

Package

asd-generator

Source

asd-generator.lisp (file)

Function: read-asd ASD-PATHNAME

Read a definition file and find the asdf definition. Handle older ASDF files which contain multiple forms. The recent ASDF assumes one system per file.

Package

asd-generator

Source

asd-generator.lisp (file)

Function: to-string SYMBOL

Package

asd-generator

Source

asd-generator.lisp (file)

Appendix A Indexes

A.1 Concepts

A.2 Functions

A.3 Variables

A.4 Data types