C.1.3 Here-Documents

Don’t rely on ‘\’ being preserved just because it has no special
meaning together with the next symbol. In the native sh
on OpenBSD 2.7 ‘\"’ expands to ‘"’ in here-documents with
unquoted delimiter. As a general rule, if ‘\\’ expands to ‘\’
use ‘\\’ to get ‘\’.

With OpenBSD 2.7’s sh

$ cat <<EOF
> \" \\
> EOF
" \

and with Bash:

bash-2.04$ cat <<EOF
> \" \\
> EOF
\" \

Using command substitutions in a here-document that is fed to a shell
function is not portable. For example, with Solaris 10 /bin/sh:

Some shells mishandle large here-documents: for example,
Solaris 10 dtksh and the UnixWare 7.1.1 Posix shell, which are
derived from Korn shell version M-12/28/93d, mishandle braced variable
expansion that crosses a 1024- or 4096-byte buffer boundary
within a here-document. Only the part of the variable name after the boundary
is used. For example, ${variable} could be replaced by the expansion
of ${ble}. If the end of the variable name is aligned with the block
boundary, the shell reports an error, as if you used ${}.
Instead of ${variable-default}, the shell may expand
${riable-default}, or even ${fault}. This bug can often
be worked around by omitting the braces: $variable. The bug was
fixed in
‘ksh93g’ (1998-04-30) but as of 2006 many operating systems were
still shipping older versions with the bug.

Empty here-documents are not portable either; with the following code,
zsh up to at least version 4.3.10 creates a file with a single
newline, whereas other shells create an empty file:

cat >file <<EOF
EOF

Many shells (including the Bourne shell) implement here-documents
inefficiently. In particular, some shells can be extremely inefficient when
a single statement contains many here-documents. For instance if your
configure.ac includes something like:

if <cross_compiling>; then
assume this and that
else
check this
check that
check something else
…
on and on forever
…
fi

A shell parses the whole if/fi construct, creating
temporary files for each here-document in it. Some shells create links
for such here-documents on every fork, so that the clean-up code
they had installed correctly removes them. It is creating the links
that can take the shell forever.

Moving the tests out of the if/fi, or creating multiple
if/fi constructs, would improve the performance
significantly. Anyway, this kind of construct is not exactly the
typical use of Autoconf. In fact, it’s even not recommended, because M4
macros can’t look into shell conditionals, so we may fail to expand a
macro when it was expanded before in a conditional path, and the
condition turned out to be false at runtime, and we end up not
executing the macro at all.

Be careful with the use of ‘<<-’ to unindent here-documents. The
behavior is only portable for stripping leading TABs, and things
can silently break if an overzealous editor converts to using leading
spaces (not all shells are nice enough to warn about unterminated
here-documents).