INSTALL

   1 File: bash.info,  Node: Install,  Next: Invoke,  Prev: Built-in,  Up: Top
   2
   3 Installing BASH
   4 ***************
   5
   6 To install BASH you simply type `make'.  The BASH `Makefile' tries
   7 to dynamically figure out what kind of machine and operating system
   8 you are using.  It makes an educated guess based on the information
   9 it finds.
  10
  11 During the `make' process, a message is displayed describing what
  12 machine and operating system has been chosen for you.  This
  13 information is also saved in the file `.machine' so you can look at
  14 it later.
  15
  16 Therefore, for most machines, simply follow this simple checklist
  17 to install BASH:
  18
  19   1. Type `make'.  If you want to use GCC to compile bash, type
  20      `make CC=gcc CPPNAME='$(CC) -E''.
  21
  22   2. Wait for the compilation to finish.
  23
  24   3. Type `./bash' to see if the compile worked.
  25
  26   4. Type `make install prefix=/usr/gnu/' (or the appropriate root
  27      of your local GNU software installation tree) to copy bash to
  28      your binaries directory, assumed to be ${prefix}/bin.  This will
  29      also attempt to install the manual pages under ${prefix}/man
  30      and the info file under ${prefix}/info.
  31
  32 * Menu:
  33
  34 * Problems::  What to do if BASH doesn't install quite so easily.
  35
  36 * Files::     Files used in the `make' process.
  37
  38 * Porting::   Porting BASH to a new machine.
  39
  40 * Bugs::      What to do if you Discover Bugs in BASH.
  41
  42
  43 File: bash.info,  Node: Problems,  Next: Files,  Prev: Install,  Up: Install
  44
  45 What if it Doesn't Install so Easily?
  46 =====================================
  47
  48 Sometimes BASH gets confused and will make the wrong assumptions
  49 about your machine or operating system.  If the displayed
  50 information (also found in `.machine') is incorrect, you will have
  51 to edit the file `machines.h' and provide the appropriate
  52 information so that BASH can be installed correctly.  The complete
  53 instructions for doing this are located in the `machines.h' file.
  54
  55 However, if BASH says that your machine type is an
  56 "UNKNOWN_MACHINE", or BASH thought it knew something about your
  57 machine but was wrong, then reading the next few sections could
  58 be of use to you (*note Files::., and *note Porting::., for more
  59 information).
  60
  61 On the MIPSEB with the BSD universe, you must:
  62
  63 1) Place /bsd43/bin in your PATH before /bin
  64 2) Use $(CC) -E instead of /lib/cpp to build cpp-Makefile.
  65
  66 On SCO Xenix 386, you must:
  67
  68 1) Use $(CC) -E instead of /lib/cpp to build cpp-Makefile.
  69
  70 On Interactive Unix version 3 or 4, you must:
  71
  72 1) Edit cpp-Makefile to remove either -O or -g from DEBUG_FLAGS
  73
  74 File: bash.info,  Node: Files,  Next: Porting,  Prev: Problems,  Up: Install
  75
  76 Files Used in the `make' Process.
  77 =================================
  78
  79 The following files are used during the installation of BASH, in
  80 the `make' process:
  81
  82 `Makefile'
  83      This is responsible for making the actual `Makefile' that is
  84      used to create Bash.  It runs the C preprocessor (usually
  85      located in `/lib/cpp') on the file `cpp-Makefile', producing
  86      the output file `bash-Makefile'.
  87
  88 `cpp-Makefile'
  89      This is a file of C comments and text.  It contains a
  90      reasonable number of `ifdefs' which control what files get
  91      compiled and which flags are passed to the various C files
  92      comprising BASH.  It includes files named `machines.h',
  93      `sysdefs.h', and `config.h'.
  94
  95 `machines.h'
  96      This file contains the basic compilation parameters for all of
  97      the machines to which BASH has been ported.  This file
  98      consists of a series of conditional blocks, one per machine
  99      type.
 100
 101      These conditional blocks are depend upon the unique identifier
 102      that `cpp' has predefined for this machine.  In some cases,
 103      additional information can be passed from `Makefile'.  It is
 104      possible to pass information such as whether or not a
 105      particular file is available on this system, and so on.
 106
 107 `sysdefs.h'
 108      This file is dynamically made at build time by running the shell
 109      script `support/mksydefs'.  If there appears to be something wrong
 110      in this file, then edit the `mksysdefs' script, and mail the
 111      changes that you make to bash-maintainers@prep.ai.mit.edu.
 112
 113 `bash-Makefile'
 114      This is the output from the initial stage of `make'.  It is a
 115      stripped down version of `cpp-Makefile' which is tailor-made
 116      for your machine and operating system.  All subsequent `makes'
 117      use this file.
 118
 119
 120 File: bash.info,  Node: Porting,  Next: Bugs,  Prev: Files,  Up: Install
 121
 122 What if You Have to Port to a New Machine?
 123 ==========================================
 124
 125 Sometimes you may want to port BASH to a new, previously
 126 unsupported machine.  To do so you need to create a block in
 127 `machines.h' which is conditional based on a unique identifier
 128 present in your version of the C preprocessor.
 129
 130 If you don't know what that symbol is, you might try the following
 131 simple test:
 132
 133      echo "main () { }" > foo.c
 134      cc -v foo.c
 135
 136 You are looking for `-DMACHINE', where `MACHINE' is an identifier
 137 for your machine.  If you are very unlucky and your machine's C
 138 preprocessor doesn't have a unique identifier, you will have to
 139 define the identifier in Makefile manually.
 140
 141 Let's say you have a machine from Yoyodyne Industries, called the
 142 YoYo.  It runs a version of BSD, so it is reasonably compatible.
 143 However, the `cpp' on this YoYo machine doesn't define any unique
 144 identifiers.  You should change the `Makefile' line for `CPPFLAGS'
 145 to:
 146
 147      CPPFLAGS = -P -DYoYo
 148
 149 Then, in `machines.h', you copy the block for `UNKNOWN_MACHINE',
 150 and change the conditional to;
 151
 152      #if defined (YoYo)
 153
 154 Inside of the YoYo block you define `M_MACHINE="YoYo"', and
 155 `M_OS=Bsd'.  You also modify the existing defines to match your
 156 machine's software.
 157
 158 If BASH still won't compile, perhaps because of missing code that
 159 is required for your YoYo machine, you will have to write that code
 160 and place it within a conditional block based on YoYo.
 161
 162 Most machines aren't that difficult; simply redefining a few of the
 163 default values is sufficient.  If you do run across a difficult
 164 machine, please send all fixes and changes to
 165 bash-maintainers@prep.ai.mit.edu in the form of context diffs:
 166
 167      diff -c orig-machines.h machines.h >machines.diffs
 168
 169 Please include information about which version of the shell you have.
 170
 171 For those machines which prove more difficult, or if you are not
 172 sure about where to start, the scripts in the `portbash' directory
 173 may prove helpful.
 174
 175 File: bash.info,  Node: Bugs,  Prev: Porting,  Up: Install
 176
 177 Reporting Bugs
 178 ==============
 179
 180 If you find a bug in bash, you should report it.  But first you
 181 should make sure that it really is a bug and that it appears in the
 182 latest version of BASH that is available.
 183
 184 Once you have ascertained that a bug really exists, you are welcome
 185 to mail in a bug report.  If you have a fix, please mail that too!
 186 The program `bashbug' is used to submit bug reports.
 187
 188 Suggestions and "philosophical" bug reports should be mailed to
 189 bug-bash@ai.mit.edu.  Genuine bug reports should be mailed to the
 190 same place, or to bash-maintainers@prep.ai.mit.edu.  The `bashbug'
 191 script sends its messages to bug-bash@prep.ai.mit.edu.
 192
 193 *All* bug reports should include:
 194
 195    * The version number of BASH.
 196
 197    * The hardware and operating system used.
 198
 199    * The compiler used to compile BASH.
 200
 201    * A description of the bug's behavior.
 202
 203    * A short script or "recipe" which demonstrates the bug.
 204
 205 The `bashbug' program includes much of this information
 206 automatically.  Without this information, it is generally not
 207 possible to successfully debug BASH.  Usually, without this
 208 information, the bug won't manifest itself!
 209
 210 Discussion and questions about BASH in general (including
 211 questions about this documentation) can be sent to
 212 bash-maintainers@prep.ai.mit.edu.