Bug 16432

The two differ by more than the extension: they are expanded by different
programs against different variable sets. Same four references, run down
both paths:

  reference           WICVARS  .wks (wic)          .wks.in (bitbake)
  ${IMAGE_ROOTFS}     yes      /path/to/rootfs     /path/to/rootfs
  ${TMPDIR}           no       ${TMPDIR}           /build/tmp
  ${@1024*2}          n/a      ${@1024*2}          2048
  ${NOWHERE_DEFINED}  no       ${NOWHERE_DEFINED}  (empty)

TMPDIR is set in the datastore but is not one of the 33 WICVARS names,
which is the whole of why row two differs; NOWHERE_DEFINED is set in
neither.

A .wks is expanded by wic's expand_line() from <image>.env, which
do_rootfs_wicenv writes from WICVARS alone. An undefined name warns and
survives verbatim; ${@...} never matches wic's regex, so it passes through
without even a warning.

A .wks.in is expanded by bitbake: image_types_wic.bbclass reads the body
into _WKS_TEMPLATE and do_write_wks_template writes out
d.getVar('_WKS_TEMPLATE'). Anything still looking like a reference is
afterwards deleted, so an undefined name silently becomes empty - the
opposite of the .wks behaviour.

Worth stating explicitly: a .wks.in using "include" gets both regimes.
do_write_wks_template expands only the template body; the included file is
opened later by wic's _parse(), so it sees WICVARS alone. Verified by
parsing an outer .wks whose include named one variable of each kind: the
first expanded, the second stayed literal.

ref-manual/classes.rst (uboot-extlinux-config) already tells the reader to
"explicitly configure the .wks.in file" without the manuals saying what
one is: the term is in use ahead of its definition.

Against openembedded-core 3e06b44aa911 and wic 610a61a25e5f.

(In reply to Trevor Woerner from comment #1)
> Worth stating explicitly: a .wks.in using "include" gets both regimes.
> do_write_wks_template expands only the template body; the included file is
> opened later by wic's _parse(), so it sees WICVARS alone. Verified by
> parsing an outer .wks whose include named one variable of each kind: the
> first expanded, the second stayed literal.

I've also found that the include directive is only supported for .wks files, not .wks.in. Documented it, and the rest of this bug in https://lore.kernel.org/r/20261102-wks-in-v1-0-fbb797a3d5cb@bootlin.com.