autoconf: File System Conventions

1 
1 11.6 File System Conventions
1 ============================
1 
1 Autoconf uses shell-script processing extensively, so the file names
1 that it processes should not contain characters that are special to the
1 shell.  Special characters include space, tab, newline, NUL, and the
1 following:
1 
1      " # $ & ' ( ) * ; < = > ? [ \ ` |
1 
1    Also, file names should not begin with `~' or `-', and should
1 contain neither `-' immediately after `/' nor `~' immediately after
1 `:'.  On Posix-like platforms, directory names should not contain `:',
1 as this runs afoul of `:' used as the path separator.
1 
1    These restrictions apply not only to the files that you distribute,
1 but also to the absolute file names of your source, build, and
1 destination directories.
1 
1    On some Posix-like platforms, `!' and `^' are special too, so they
1 should be avoided.
1 
1    Posix lets implementations treat leading `//' specially, but
1 requires leading `///' and beyond to be equivalent to `/'.  Most Unix
1 variants treat `//' like `/'.  However, some treat `//' as a
1 "super-root" that can provide access to files that are not otherwise
1 reachable from `/'.  The super-root tradition began with Apollo
1 Domain/OS, which died out long ago, but unfortunately Cygwin has
1 revived it.
1 
1    While `autoconf' and friends are usually run on some Posix variety,
1 they can be used on other systems, most notably DOS variants.  This
1 impacts several assumptions regarding file names.
1 
1 For example, the following code:
1 
1      case $foo_dir in
1        /*) # Absolute
1           ;;
1        *)
1           foo_dir=$dots$foo_dir ;;
1      esac
1 
1 fails to properly detect absolute file names on those systems, because
1 they can use a drivespec, and usually use a backslash as directory
1 separator.  If you want to be portable to DOS variants (at the price of
1 rejecting valid but oddball Posix file names like `a:\b'), you can
1 check for absolute file names like this:
1 
1      case $foo_dir in
1        [\\/]* | ?:[\\/]* ) # Absolute
1           ;;
1        *)
1           foo_dir=$dots$foo_dir ;;
1      esac
1 
1 Make sure you quote the brackets if appropriate and keep the backslash
1 as first character (⇒Limitations of Shell Builtins case.).
1 
1    Also, because the colon is used as part of a drivespec, these
1 systems don't use it as path separator.  When creating or accessing
1 paths, you can use the `PATH_SEPARATOR' output variable instead.
1 `configure' sets this to the appropriate value for the build system
1 (`:' or `;') when it starts up.
1 
1    File names need extra care as well.  While DOS variants that are
1 Posixy enough to run `autoconf' (such as DJGPP) are usually able to
1 handle long file names properly, there are still limitations that can
1 seriously break packages.  Several of these issues can be easily
1 detected by the doschk
1 (ftp://ftp.gnu.org/gnu/non-gnu/doschk/doschk-1.1.tar.gz) package.
1 
1    A short overview follows; problems are marked with SFN/LFN to
1 indicate where they apply: SFN means the issues are only relevant to
1 plain DOS, not to DOS under Microsoft Windows variants, while LFN
1 identifies problems that exist even under Microsoft Windows variants.
1 
1 No multiple dots (SFN)
1      DOS cannot handle multiple dots in file names.  This is an
1      especially important thing to remember when building a portable
1      configure script, as `autoconf' uses a .in suffix for template
1      files.
1 
1      This is perfectly OK on Posix variants:
1 
1           AC_CONFIG_HEADERS([config.h])
1           AC_CONFIG_FILES([source.c foo.bar])
1           AC_OUTPUT
1 
1      but it causes problems on DOS, as it requires `config.h.in',
1      `source.c.in' and `foo.bar.in'.  To make your package more portable
1      to DOS-based environments, you should use this instead:
1 
1           AC_CONFIG_HEADERS([config.h:config.hin])
1           AC_CONFIG_FILES([source.c:source.cin foo.bar:foobar.in])
1           AC_OUTPUT
1 
1 No leading dot (SFN)
1      DOS cannot handle file names that start with a dot.  This is
1      usually not important for `autoconf'.
1 
1 Case insensitivity (LFN)
1      DOS is case insensitive, so you cannot, for example, have both a
1      file called `INSTALL' and a directory called `install'.  This also
1      affects `make'; if there's a file called `INSTALL' in the
1      directory, `make install' does nothing (unless the `install'
1      target is marked as PHONY).
1 
1 The 8+3 limit (SFN)
1      Because the DOS file system only stores the first 8 characters of
1      the file name and the first 3 of the extension, those must be
1      unique.  That means that `foobar-part1.c', `foobar-part2.c' and
1      `foobar-prettybird.c' all resolve to the same file name
1      (`FOOBAR-P.C').  The same goes for `foo.bar' and `foo.bartender'.
1 
1      The 8+3 limit is not usually a problem under Microsoft Windows, as
1      it uses numeric tails in the short version of file names to make
1      them unique.  However, a registry setting can turn this behavior
1      off.  While this makes it possible to share file trees containing
1      long file names between SFN and LFN environments, it also means
1      the above problem applies there as well.
1 
1 Invalid characters (LFN)
1      Some characters are invalid in DOS file names, and should therefore
1      be avoided.  In a LFN environment, these are `/', `\', `?', `*',
1      `:', `<', `>', `|' and `"'.  In a SFN environment, other
1      characters are also invalid.  These include `+', `,', `[' and `]'.
1 
1 Invalid names (LFN)
1      Some DOS file names are reserved, and cause problems if you try to
1      use files with those names.  These names include `CON', `AUX',
1      `COM1', `COM2', `COM3', `COM4', `LPT1', `LPT2', `LPT3', `NUL', and
1      `PRN'.  File names are case insensitive, so even names like
1      `aux/config.guess' are disallowed.
1 
1