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