Added gitignore entries needed to ignore derived objects generated from full build...
[bash.git] / NOTES
blob4fe9e6ca21489b04487e5f88ff34eea350d572e4
1 Platform-Specific Configuration and Operation Notes
2 ===================================================
4 1.  configure --without-gnu-malloc on:
6         alpha running OSF/1, Linux, or NetBSD (malloc needs 8-byte alignment;
7         bash malloc has 8-byte alignment now, but I have no alphas to test on)
9         next running NeXT/OS
11         all machines running SunOS YP code: SunOS4, SunOS5, HP/UX, if you
12         have problems with username completion or tilde expansion for
13         usernames found via YP/NIS
15         linux (optional, but don't do it if you're using Doug Lea's malloc)
17         QNX 4.2
18         other OSF/1 machines (KSR/1, HP, IBM AIX/ESA)
19         AIX
20         sparc SVR4, SVR4.2 (ICL reference port)
21         DG/UX
22         Cray
24         NetBSD/sparc (malloc needs 8-byte alignment; bash malloc has 8-byte
25         alignment now, but I have no NetBSD machines to test on)
27         BSD/OS 2.1, 3.x if you want to use loadable builtins
29         Motorola m68k machines running System V.3.  There is a file descriptor
30         leak caused by using the bash malloc because closedir(3) needs to read
31         freed memory to find the file descriptor to close
33 2.  Configure using shlicc2 on BSD/OS 2.1 and BSD/OS 3.x to use loadable
34     builtins
36 3.  Bash cannot be built in a directory separate from the source directory
37     using configure --srcdir=... unless the version of `make' you're using
38     does $VPATH handling right.  The script support/mkclone can be used to
39     create a `build tree' using symlinks to get around this.
41 4.  I've had reports that username completion (as well as tilde expansion
42     and \u prompt expansion) does not work on IRIX 5.3 when linking with
43     -lnsl.  This is only a problem when you're running NIS, since
44     apparently -lnsl supports only /etc/passwd and not the NIS functions
45     for retrieving usernames and passwords.  Editing the Makefile after
46     configure runs and removing the `-lnsl' from the assignment to `LIBS'
47     fixes the problem.
49 5.  There is a problem with the `makewhatis' script in older (pre-7.0)
50     versions of Red Hat Linux.  Running `makewhatis' with bash-2.0 or
51     later versions results in error messages like this:
53     /usr/sbin/makewhatis: cd: manpath: No such file or directory
54     /usr/sbin/makewhatis: manpath/whatis: No such file or directory
55     chmod: manpath/whatis: No such file or directory
56     /usr/sbin/makewhatis: cd: catpath: No such file or directory
57     /usr/sbin/makewhatis: catpath/whatis: No such file or directory
58     chmod: catpath/whatis: No such file or directory
60     The problem is with `makewhatis'.  Red Hat (and possibly other
61     Linux distributors) uses a construct like this in the code:
63         eval path=$"$pages"path
65     to do indirect variable expansion.  This `happened to work' in
66     bash-1.14 and previous versions, but that was more an accident
67     of implementation than anything else -- it was never supported
68     and certainly is not portable.
70     Bash-2.0 has a new feature that gives a new meaning to $"...".
71     This is explained more completely in item 1 in the COMPAT file.
73     The three lines in the `makewhatis' script that need to be changed
74     look like this:
76              eval $topath=$"$topath":$name
77     [...]
78        eval path=$"$pages"path
79     [...]
80     eval path=$"$pages"path
82     The portable way to write this code is
84              eval $topath="\$$topath":$name
85        eval path="\$$pages"path
86     eval path="\$$pages"path
88     You could also experiment with another new bash feature: ${!var}.
89     This does indirect variable expansion, making the use of eval
90     unnecessary.
92 6.  There is a problem with syslogd on many Linux distributions (Red Hat
93     and Slackware are two that I have received reports about).  syslogd
94     sends a SIGINT to its parent process, which is waiting for the daemon
95     to finish its initialization.  The parent process then dies due to
96     the SIGINT, and bash reports it, causing unexpected console output
97     while the system is booting that looks something like
99         starting daemons: syslogd/etc/rc.d/rc.M: line 29: 38 Interrupt ${NET}/syslogd
101     Bash-2.0 reports events such as processes dying in scripts due to
102     signals when the standard output is a tty.  Bash-1.14.x and previous
103     versions did not report such events.
105     This should probably be reported as a bug to whatever Linux distributor
106     people see the problem on.  In my opinion, syslogd should be changed to
107     use some other method of communication, or the wrapper function (which
108     appeared to be `daemon' when I looked at it some time ago) or script
109     (which appeared to be `syslog') should catch SIGINT, since it's an
110     expected event, and exit cleanly.
112 7.  Several people have reported that `dip' (a program for SLIP/PPP
113     on Linux) does not work with bash-2.0 installed as /bin/sh.
115     I don't run any Linux boxes myself, and do not have the dip
116     code handy to look at, but the `problem' with bash-2.0, as
117     it has been related to me, is that bash requires the `-p'
118     option to be supplied at invocation if it is to run setuid
119     or setgid. 
121     This means, among other things, that setuid or setgid programs
122     which call system(3) (a horrendously bad practice in any case)
123     relinquish their setuid/setgid status in the child that's forked
124     to execute /bin/sh. 
126     The following is an *unofficial* patch to bash-2.0 that causes it
127     to not require `-p' to run setuid or setgid if invoked as `sh'.
128     It has been reported to work on Linux.  It will make your system
129     vulnerable to bogus system(3) calls in setuid executables.
131 --- ../bash-2.0.orig/shell.c    Wed Dec 18 14:16:30 1996
132 +++ shell.c     Fri Mar  7 13:12:03 1997
133 @@ -347,7 +347,7 @@
134    if (posixly_correct)
135      posix_initialize (posixly_correct);
137 -  if (running_setuid && privileged_mode == 0)
138 +  if (running_setuid && privileged_mode == 0 && act_like_sh == 0)
139      disable_priv_mode ();
141    /* Need to get the argument to a -c option processed in the
143 8.  Some people have asked about binding all of the keys in a PC-keyboard-
144     style numeric keypad to readline functions.  Here's something I
145     received from the gnu-win32 list that may help.  Insert the following
146     lines into ~/.inputrc:
148 # home key
149 "\e[1~":beginning-of-line
150 # insert key
151 "\e[2~":kill-whole-line
152 # del key
153 "\e[3~":delete-char
154 # end key
155 "\e[4~":end-of-line
156 # pgup key
157 "\e[5~":history-search-forward
158 # pgdn key
159 "\e[6~":history-search-backward
161 9.  Hints for building under Minix 2.0 (Contributed by Terry R. McConnell,
162     <tmc@barnyard.syr.edu>)
164    The version of /bin/sh distributed with Minix is not up to the job of
165    running the configure script. The easiest solution is to swap /bin/sh
166    with /usr/bin/ash. Then use chmem(1) to increase the memory allocated
167    to /bin/sh. The following settings are known to work:
169    text         data     bss   stack  memory
170    63552  9440          3304   65536  141832  /bin/sh
172    If you have problems with make or yacc it may be worthwhile first to
173    install the GNU versions of these utilities before attempting to build
174    bash. (As of this writing, all of these utilities are available for the
175    i386 as pre-built binaries via anonymous ftp at math.syr.edu in the
176    pub/mcconnell/minix directory. Note that the GNU version of yacc is called
177    bison.)
179    Unless you want to see lots of warnings about old-style declarations,
180    do LOCAL_CFLAGS=-wo; export LOCAL_CFLAGS before running configure.
181    (These warnings are harmless, but annoying.)
183    configure will insist that you supply a host type. For example, do
184    ./configure --host=i386-pc-minix.
186    Minix does not support the system calls required for a proper 
187    implementation of ulimit().  The `ulimit' builtin will not be available.
189    Configure will fail to notice that many things like uid_t are indeed
190    typedef'd in <sys/types.h>, because it uses egrep for this purpose
191    and minix has no egrep. You could try making a link /usr/bin/egrep -->
192    /usr/bin/grep. Better is to install the GNU version of grep in
193    /usr/local/bin and make the link /usr/local/bin/egrep -->/usr/local/bin/grep.
194    (These must be hard links, of course, since Minix does not support
195    symbolic links.)
197    You will see many warnings of the form:
198    warning: unknown s_type: 98
199    I have no idea what this means, but it doesn't seem to matter.
201 10. If you do not have /usr/ccs/bin in your PATH when building on SunOS 5.x
202     (Solaris 2), the configure script will be unable to find `ar' and
203     `ranlib' (of course, ranlib is unnecessary).  Make sure your $PATH
204     includes /usr/ccs/bin on SunOS 5.x.  This generally manifests itself
205     with libraries not being built and make reporting errors like
206     `cr: not found' when library construction is attempted.
208 11. Building a statically-linked bash on Solaris 2.5.x, 2.6, 7, or 8 is
209     complicated.
211     It's not possible to build a completely statically-linked binary, since
212     part of the C library depends on dynamic linking.  The following recipe
213     assumes that you're using gcc and the Solaris ld (/usr/ccs/bin/ld) on
214     Solaris 2.5.x or 2.6:
216         configure --enable-static-link
217         make STATIC_LD= LOCAL_LIBS='-Wl,-B,dynamic -ldl -Wl,-B,static'
219     This should result in a bash binary that depends only on libdl.so:
221         thor(2)$ ldd bash
222                 libdl.so.1 =>    /usr/lib/libdl.so.1
224     If you're using the Sun C Compiler (Sun WorkShop C Compiler version
225     4.2 was what I used), you should be able to get away with using
227         configure --enable-static-link
228         make STATIC_LD=  LOCAL_LIBS='-B dynamic -ldl -B static'
230     If you want to completely remove any dependence on /usr, perhaps
231     to put a copy of bash in /sbin and have it available when /usr is
232     not mounted, force the build process to use the shared dl.so library
233     in /etc/lib.
235     For gcc, this would be something like
237         configure --enable-static-link
238         make STATIC_LD= LOCAL_LIBS='-Wl,-B,dynamic -Wl,-R/etc/lib -ldl -Wl,-B,static'
240     For Sun's WS4.2 cc
242         configure --enable-static-link
243         make STATIC_LD=  LOCAL_LIBS='-B dynamic -R/etc/lib -ldl -B static'
245     seems to work, at least on Solaris 2.5.1:
247         thor(2)$ ldd bash
248                 libdl.so.1 =>    /etc/lib/libdl.so.1
250     On Solaris 7 (Solaris 8, using the version of gcc on the free software
251     CD-ROM), the following recipe appears to work for gcc:
253         configure --enable-static-link
254         make STATIC_LD='-Wl,-Bstatic' LOCAL_LIBS='-Wl,-Bdynamic -Wl,-R/etc/lib -ldl -Wl,-Bstatic'
256         thor.ins.cwru.edu(2)$ ldd bash
257                 libdl.so.1 =>    /etc/lib/libdl.so.1
259     Make the analogous changes if you are running Sun's C Compiler.
261     I have received word that adding -L/etc/lib (or the equivalent
262     -Wl,-L/etc/lib) might also be necessary, in addition to the -R/etc/lib.
264     On later versions of Solaris, it may be necessary to add -lnsl before
265     -ldl; statically-linked versions of bash using libnsl are not guaranteed
266     to work correctly on future versions of Solaris.
268 12. Configuring bash to build it in a cross environment.  Currently only
269     two native versions can be compiled this way, cygwin32 and x86 BeOS.
270     For BeOS, you would configure it like this:
272         export RANLIB=i586-beos-ranlib
273         export AR=i586-beos-ar
274         export CC=i586-beos-gcc
275         configure i586-beos
277     Similarly for cygwin32.
279 13. Bash-2.05 has reverted to the bash-2.03 behavior of honoring the current
280     locale setting when processing ranges within pattern matching bracket
281     expressions ([A-Z]).  This is what POSIX.2 and SUSv2 specify.
283     The behavior of the matcher in bash-2.05 depends on the current LC_COLLATE
284     setting.  Setting this variable to `C' or `POSIX' will result in the
285     traditional behavior ([A-Z] matches all uppercase ASCII characters).
286     Many other locales, including the en_US locale (the default on many US
287     versions of Linux) collate the upper and lower case letters like this:
289         AaBb...Zz
291     which means that [A-Z] matches every letter except `z'.
293     The portable way to specify upper case letters is [:upper:] instead of
294     A-Z; lower case may be specified as [:lower:] instead of a-z.
296     Look at the manual pages for setlocale(3), strcoll(3), and, if it is
297     present, locale(1).  If you have locale(1), you can use it to find
298     your current locale information even if you do not have any of the
299     LC_ variables set.
301     My advice is to put
303         export LC_COLLATE=C
305     into /etc/profile and inspect any shell scripts run from cron for
306     constructs like [A-Z].  This will prevent things like
308         rm [A-Z]*
310     from removing every file in the current directory except those beginning
311     with `z' and still allow individual users to change the collation order.
312     Users may put the above command into their own profiles as well, of course.
314 14. Building on Interix (nee OpenNT), which Microsoft bought from Softway
315     Systems and has seemingly abandoned (thanks to Kevin Moore for this item).
317         1.  cp cross-build/opennt.cache config.cache
319         2.  If desired, edit pathnames.h to set the values of SYS_PROFILE and
320             DEFAULT_HOSTS_FILE appropriately.
322         3.  export CONFIG_SHELL=$INTERIX_ROOT/bin/sh
324         4.  ./configure --prefix=$INTERIX_ROOT/usr/local (or wherever you
325             want it).
327         5. make; make install; enjoy
329 15.  Configure with `CC=xlc' if you don't have gcc on AIX 4.2 and later
330      versions.  `xlc' running in `cc' mode has trouble compiling error.c.
332 16.  Configure --disable-multibyte on NetBSD versions (1.4 through at least
333      1.6.1) that include wctype.h but do not define wctype_t.
335 17.  Do NOT use bison-1.75.  It builds a non-working parser.  The most
336      obvious effect is that constructs like "for i; do echo $i; done" don't
337      loop over the positional parameters.
339 18.  I have received reports that using -O2 with the MIPSpro results in a
340      binary that fails in strange ways.  Using -O1 seems to work.
342 19.  There is special handling to ensure the shell links against static
343      versions of the included readline and history libraries on Mac OS X;
344      Apple ships inadequate dynamic libreadline and libhistory "replacements"
345      as standard libraries.
347 20.  If you're on a system like SGI Irix, and you get an error about not
348      being able to refer to a dynamic symbol
349      (ld: non-dynamic relocations refer to dynamic symbol PC), add
350      -DNEED_EXTERN_PC to the LOCAL_CFLAGS variable in lib/readline/Makefile.in
351      and rebuild.