logging-with-log4cl

name	logging-with-log4cl
description	Use when adding or changing log calls in a Common Lisp project that uses log4cl (the LOG package), when compilation fails with "Package LOG does not exist" in an ASDF package-inferred system, or when a log:info call with a path or tilde crashes or garbles at runtime.

Logging with log4cl

Overview

log4cl exposes the LOG package (log:info, log:error, log:debug, …). These macros are cl:format-based: the first argument is a format control string and any further arguments are format args.

When to Use

• Adding log output to a CL file that uses (or should use) log4cl
• Compile error The package LOG does not exist in a package-inferred system
• A log:info call crashes or mangles output because of a literal ~ (typically from a path)

Prefer log:info over format t

log:info / log:error give structured, level-filterable, redirectable output. Do not use (format t ...) for diagnostics.

(log:info "Processed ~A rows in ~A ms" count elapsed)   ;; good
(format t "[info] Processed ~A rows~%" count)            ;; bad

Write log:info with the log: prefix (aids grep). Do not (:import-from #:log #:info) just to drop the prefix unless the project convention says so.

First argument is a format control string

~ is the format directive character. Paths and home-directory strings contain ~ and will crash or mangle output if inlined into the control string.

(log:info "Loading plugins from ~/.config/barista/plugins/")   ;; bad — ~ consumed as a directive
(log:info "Loading plugins from ~~/.config/...")               ;; works but brittle — breaks the moment this becomes dynamic
(log:info "Loading plugins from ~A" dir)                       ;; good — value passed as a ~A argument

Rule of thumb: the control string holds fixed structure; every ~-bearing or variable value goes in as a ~A argument. Paths are dynamic in practice — never inline them.

Package LOG does not exist in package-inferred systems

ASDF infers a file's dependencies from its uiop:define-package clauses. If log only appears as a prefixed symbol in the body (log:info), ASDF does not see a dependency on log4cl, and compiling the file fails because the LOG package is not loaded yet.

Fix — register the package nickname in the main .asd, then files can (:import-from #:log ...) and ASDF inference resolves log4cl:

;; in myapp.asd
(asdf:register-system-packages "log4cl" '("LOG"))

;; in the file
(uiop:define-package #:myapp/src/workers/poller
  (:use #:cl)
  (:import-from #:log #:info)
  (:export #:run-poller))

Common Mistakes

Symptom	Fix
log:info crashes / garbles on a path containing ~	Pass the path as a ~A argument, not inline in the control string
The package LOG does not exist at compile time in a package-inferred file	(asdf:register-system-packages "log4cl" '("LOG")) in the main .asd, plus (:import-from #:log #:info) in the file
Using format t for diagnostics	Replace with log:info / log:error
~~ used to escape an inlined path	Replace with ~A + argument — paths are dynamic

Related skills

For the surrounding package and uiop:define-package conventions: writing-common-lisp.