You can support this project by donating at:

Or see the list of project sponsors.

hu.dwim.asdfasdf-exension

Documentation	🥺
Docstrings	🥺
Tests	🥺
Examples	🥺
RepositoryActivity	🥺
CI	🥺

Today I want to review a hu.dwim.asdf system, which is a part of the large ecosystem, created by a group of Hungarian lispers.

This is the most popular asdf extension. I've created a script which analyzed all Quicklisp projects and "hu.dwim.asdf" is mentioned in "defsystem-depends-on" of 150 systems.

The first feature it provides is a way to distinguish between development and production builds.

There is a variable hu.dwim.asdf:*load-as-production?* which is nil by default. Macroses debug-only and production-only will expand only when you are compiling code in a particular mode.

Also, there is optimize-declaration function, which also depends on *load-as-production?* variable and returns either (optimize (speed 3) (debug 0) (safety 0)) for production or (optimize (debug 3) (safety 3)) for development mode.

The similar feature you'll find also in com.google.base system, reviewed on this week.

In code it can be used like this:

(defun foo ()
  (declare #.(optimize-declaration))
  (debug-only
    (format t "Function foo was called~%"))
  (do-some-real-work))

If you'll set a :class "hu.dwim.asdf:hu.dwim.system" for your ASDF system, then some additional features will be enabled.

For example, all compiler's output will be stored in a special slot, and you'll be able to inspect it at any time to find out compiler warnings:

POFTHEDAY> (hu.dwim.asdf:system-compile-output
            (asdf:find-system :hu.dwim.logger))
"; compiling file "/Users/art/poftheday/.../package.lisp"
; compiling (IN-PACKAGE :HU.DWIM.DEF)
; compiling (DEF PACKAGE ...)

; wrote /Users/art/.cache/common-lisp/sbcl-2.0.2-macosx-x64/...
; compilation finished in 0:00:00.002
; compiling file
..."

POFTHEDAY> (hu.dwim.asdf:system-load-output
            (asdf:find-system :hu.dwim.logger))
""

There are three ASDF system classes:

• hu.dwim.system
• hu.dwim.test-system
• hu.dwim.documentation-system

When you use them in a combination, hu.dwim.asdf allows to call asdf:test-system on a base system and test suite will be automatically called. But you should also use hu.dwim.stefil test framework:

POFTHEDAY> (asdf:test-system :hu.dwim.logger)

The result of HU.DWIM.LOGGER.TEST::TEST is:

  #<test-run: 1 test, 0 assertions, 0 failures in 0.0f0 sec>

For more details run it from the REPL and use the customized Slime inspector
to inspect the results (ASDF eats up the return values).

Also, hu.dwim.test-system class stores a test result and output inside the system object. This allows to extract this information later:

POFTHEDAY> (hu.dwim.asdf:system-test-result
            (asdf:find-system :hu.dwim.logger.test))
#<test-run: 1 test, 0 assertions, 0 failures in 0.0 sec>
POFTHEDAY> (hu.dwim.asdf:system-test-output
            (asdf:find-system :hu.dwim.logger.test))
"Running test: TEST
The result of HU.DWIM.LOGGER.TEST::TEST is:

  #<test-run: 1 test, 0 assertions, 0 failures in 0.0 sec>

For more details run it from the REPL and use the customized Slime inspector
to inspect the results (ASDF eats up the return values).
"

You can define your own class based on hu.dwim.test-system and a method run-test-suite to run test framework other than stefil.

There isn't any special code for hu.dwim.documentation-system except that such a system will have this string as a default for its description:

"Documentation for the similarly named system. It should contain formally processable data and its contents should be available at http://dwim.hu"

Another feature of hu.dwim.asdf is its develop-system function which does a few things:

• turn's on debug mode;
• evals (declaim (optimize (debug 3)));
• loads system using quicklisp if it is available with verbose output;
• loads swank and integrations of the loaded system with it;
• changes current package to the package associated with a loaded system.

As a final note, I want to mention there was hard to understand what this system is able to do because there is no documentation, nor docstrings or examples.

Hu.dwim.* systems contains interesting solutions. Probably we should document them properly.